Thanks for reply, thalia <https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2Fjafingerhut%2Fthalia&sa=D&sntz=1&usg=AFQjCNFAGHJPid23j0q9p53dhfSOGKr_sw> looks very close for what i'm looking for, and i find cool being able to inject arbitrary docstrings :) But there is always some kind of uncertainty about synchronisation of examples, that they 100% works with the current implementation.
For a moment - now, I'm speaking not only about the language codebase itself, but about an abstact big clojure codebase! Both thalia and clojuredocs ways are nice, but I think it's incorrect distribution of responsibility: Who is to blame if example would behave as written? How and when would docs maitainer know about this? (I meant this under "challenge") Would codebase maintainer care about these examples? Finally, who would write the most appopriate example how to use function if not the author? As such, I think such "external" way to document codebase is going to explode soon. I think, 1) such examples should be distributed *within* the codebase docstrings (again think, that if someone just reads the source - examples inside are very nice, aren't they?) 2) these examples should be part of test suite, and codebase maintainer is due to keeping them up-to-date And that's why I mentioned core-team, because now it's time to convince them to write examples, perhaps import from clojuredocs first (and discover a tool, what would parse them out and check them) BTW, I'm *highly interested* in these kind of things and *I'm surely would start develop it if none would explored and if there would be a mentor to review my first attempts*. понедельник, 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.
