On Tue, May 6, 2014 at 9:56 AM, Sean Corfield <s...@corfield.org> wrote:
> > Returns a new seq where x is the first element and seq is > > the rest. > > Adding complexity and weaving heapings of prose in amongst the code isn't > going to make the developer that wrote the above rewrite it in a better > way. You'll just end up with more bad documentation getting in the way of > what the code actually does. Bad documentation is worse than no > documentation. At least with no documentation, the code doesn't lie. > Sean, I think you missed the point of that example. The point was that the docstring actually makes sense if it were written as: Returns a new seq where `x` is the first element and `seq` is the rest. Note how using standard markdown syntax helps distinguish the reference to the `seq` arg and the more generic use of the term seq. I think the Clojure community's lack of meaningful support for markdown in docstrings is a glaring weakness that is fairly easy to rectify. In the meantime, I've begun using markdown syntax in my own docstrings, figuring that someday the tools will eventually catch up and support it. -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
