On Thursday, April 21, 2016 at 11:49:16 AM UTC-5, Andy Fingerhut wrote: > > Most doc strings are considered terse by many people. This appears to be > considered a feature by those who maintain Clojure, not a bug, with one > reason given by Stuart Halloway in his recent talk on using the scientific > method in debugging [1]. Paraphrased from memory it was approximately "if > you have a bug in some API you are using, you should read all of the > documentation for it. That is easier if it is short." > > If you want longer documentation and/or examples, ClojureDocs.org and > conj.io take user submissions for additional documentation, with quite > low friction. >
Yeah, there are tradeoffs. I understand the value of brief docstrings. The current docstring for 'get' is correct for maps and vectors, even though the meaning for vectors won't be apparent for novices. Lots of things aren't apparent for novices. The behavior with strings is simply undocumented anywhere, afaik, though. That seems wrong. (Correction: I just added an example to clojure.docs. I still think that all of the intended behavior of a function should be at least tersely implied by its docstring.) -- 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.
