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.v...@gmail.com>
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.
>
--
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.
