On Tue, Sep 7, 2010 at 1:25 AM, Mark Engelberg <mark.engelb...@gmail.com> wrote: > Docstrings seem designed for fairly terse comments about the nature of > the function. It's great for providing little hints about how the > function works to jog one's memory by typing (doc ...) in the REPL, or > for searching with find-doc. But I just don't think I can fit the > kind of full documentation I want all into a docstring without ruining > its REPL usefulness.
I'm watching this thread and I'm wondering what kind of documentation people are talking about here. I've always been used to using self-documenting function / variable names and short comments for documenting everything. Clearly you guys are talking about something much bigger than this and I'd like a bit more insight into that. Who are you writing this documentation for? How detailed does it need to be? Why are good function and variable names and a short summary not enough? Genuinely curious about this. -- Sean A Corfield -- (904) 302-SEAN Railo Technologies, Inc. -- http://getrailo.com/ An Architect's View -- http://corfield.org/ "If you're not annoying somebody, you're not really alive." -- Margaret Atwood -- 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
