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.
I think this is true of function-level docstrings. However, don't forget that namespaces can have docstrings as well. That's where I like to put overview-type documentation. > Javadoc has an interesting property: it considers that the first > sentence serves as a summary for the doc. The "sentence" delimiter is > just the point in the case of javadoc. Emacs docstrings work this way too; the first line must stand alone and provide a summary. I think this would be a great convention to adapt for Clojure, but that cat may already be out of the bag. -Phil -- 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
