On May 6, 2014, at 8:11 AM, Phillip Lord <phillip.l...@newcastle.ac.uk> wrote: > I've used this example before; consider this unstructured string from > `cons`. > > Returns a new seq where x is the first element and seq is > the rest.
Just because one (or several) of the clojure.core function docstrings are poorly written, doesn't mean Clojure's current documentation system is broken. This simply comes back to developers needing to write _better_ documentation, not _more_ documentation. 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 Corfield -- (904) 302-SEAN An Architect's View -- http://corfield.org/ "Perfection is the enemy of the good." -- Gustave Flaubert, French realist novelist (1821-1880)
signature.asc
Description: Message signed with OpenPGP using GPGMail
