Tim Peters invented the idea of doctest in python. He had a great love of using the REPL (sound familiar to anyone in Clojure?).
He felt that "throwing away" a constructive REPL session was a huge waste. He'd often tested some code via the REPL, particularly the edge cases. His REPL work, if polished and preserved acted as the best type of (testable) documentation on the purpose of the code. And yet it was lost. I would have thought that his ideas would be very, very close to the heart of those in Clojure. After all, the most useful part of the docs is the pseudo REPL session after the words. Eg. http://clojuredocs.org/clojure_core/clojure.core/merge My eye goes to the REPL sessions first, and the words last. (I've been reading the docs a LOT in the last 6 months as I've been climbing the learning curve). Anyway, you can read his original words here (you'll notice that Tim Peters was relentless amusing and fun): https://groups.google.com/forum/#!topic/comp.lang.python/DfzH5Nrt05E Then look at this attempt in clojure: https://github.com/clojure/data.xml/blob/master/src/main/clojure/clojure/data/xml.clj#L173-L175 Notice how the two line pseudo REPL session there at the end is SO MUCH MORE USEFUL than the words above. That's the power of doctests. It is massive. I would encourage the core committers in Clojure to consider this seriously. doctests seem such a *perfect* fit with clojure to me. I'd like to emphasis that the REPL sessions in the doc string becomes "executable" and testable. In python, the REPL examples embedded in the docs can be checked for correctness!! They are part of the unittesting. To me, one big impediment to the adoption of this sort of approach is the lack of triple quoted strings in Clojure. https://docs.python.org/release/1.4/tut/node70.html I hope that perspective helps, Mike On Monday, June 16, 2014 11:59:19 PM UTC+10, Vladimir Bokov 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 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.
