Some thoughts:

Having concise documentation in the same place as the code minimizes a 
certain kind of work:  I want my functions to be commented in the source 
file so that someone reading it later (maybe me) will quickly understand 
what they're supposed to do.  If Clojure didn't have docstrings, I'd put 
similar information, although maybe more terse, in comments.  As it is, I 
just write the docstring, and I've accomplished two things in one.  If all 
of the documentation was in another file, I'd have to do at least 1.5 times 
more work just to produce the kind of docstrings I produce now.

Some docstrings (e.g. for xy-plot in Incanter) are too long for convenient 
use at a repl.  So I appreciate the idea of providing different levels of 
documentation.  What's displayed by default at a prompt should be short.

I like the general idea of the Valentin's proposal, but I don't understand 
every bit of it.  It sounds complicated.  Personally, I'd rather see 
something that's relatively simple, and good enough, than something that's 
perfect but unwieldy.  If it's too difficult, people won't use it, or 
they'll waste time, or feel that the Clojure community expects them to 
spend too much time on something that detracts from what's important.  I am 
someone who I think has put more time into documentation more than most of 
the programmers I've worked with.  I'm in favor of encouraging more 
documentation of code.  But documentation tools should not make the process 
much harder than it is.  Ideally, they should make it easier, but some 
extra cost is worthwhile for extra payoff later.

-- 
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.

Reply via email to