BTW, just searched through topics and found these about obsolete docstrings:
core.match incorrect docstring? https://groups.google.com/forum/#!searchin/clojure/docstring/clojure/sC16eTtVaCQ/bXC0e91wx_gJ docstrings of if-let and when-let incorrect https://groups.google.com/forum/#!searchin/clojure/docstring/clojure/1g5dEvIvGYY/PGKqr1SoOdMJ I think if there would be testable examples inside docstrings - there would be no such topics ;) понедельник, 16 июня 2014 г., 21:29:39 UTC+7 пользователь Andy Fingerhut написал: > > I cannot answer for the Clojure core committers, but from past experience > it seems unlikely that they will enhance the doc strings in the way you > suggest. > > Fortunately, it is not true that "this decision must be taken by core > committers". Anyone can add one dependency in Leiningen and replace all > doc strings for every function and macro with whatever string they prefer. > For example, this project does that for only a few functions and macros: > > https://github.com/jafingerhut/thalia > > That project does not include the feature you mention of executable > examples in-line, but such a thing could be done. > > It is true that the Clojure version number on ClojureDocs.org has not been > updated since 1.3, but note that most functions and macros have not changed > their behavior between Clojure 1.3 and the latest release, Clojure 1.6. > Even ones that have, often have only changed their behavior in 'corner > cases' that are unlikely to affect most examples. > > I am a little confused by your statement "But, honestly, adding examples > to docs by hand, updating the docs is real challenge." Do you mean that > copying and pasting the output of examples from a sample REPL session is > difficult? Or do you mean that checking whether all of those example > outputs are the same or different when a new Clojure version is released is > time consuming? If the latter, then I agree, that would be a tedious > process. > > Andy > > > On Mon, Jun 16, 2014 at 6:59 AM, Vladimir Bokov <bokov...@gmail.com > <javascript:>> wrote: > >> Hi, I'm quite new to clojure community, came from Python & Ruby. >> I see the most relevant documentation for the language is kept at >> http://clojuredocs.org/ >> I like examples listed there and idea of docstring, upon which some docs >> are generated. >> >> But, honestly, adding examples to docs by hand, updating the docs is real >> challenge. >> More confusing seems that the last version there is 1.3.0, whereas the >> top latest is actually 1.5.1 (there could be not so much difference, of >> cource, but the point is, that the docs LOOK outdated, and as such, >> unreliable) >> >> Coming across different languages there is a method in Python to embed >> pieces of code in Python doc-strings, which are pretty handy when you're >> reading source, and moreover, which may act as real test cases for that >> function,. For example: https://docs.python.org/2/library/doctest.html >> >> Why not to include these examples into source >> http://clojuredocs.org/clojure_core/clojure.core/decimal_q in similar >> way? >> This would also encourage to more using of (doc) fn, and less context >> switching (remember, I'm a newbie, and cannot grasp whole std at once) >> Of cource, this decision must be taken by core committers, and docstrings >> gonna be updated with the whole community. >> Any thoughts? >> >> -- >> You received this message because you are subscribed to the Google >> Groups "Clojure" group. >> To post to this group, send email to clo...@googlegroups.com >> <javascript:> >> Note that posts from new members are moderated - please be patient with >> your first post. >> To unsubscribe from this group, send email to >> clojure+u...@googlegroups.com <javascript:> >> 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+u...@googlegroups.com <javascript:>. >> For more options, visit https://groups.google.com/d/optout. >> > > -- 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.
