Hi, 2010/9/7 Mark Engelberg <mark.engelb...@gmail.com>: > 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.
Indeed. Though the docstring for e.g. gen-class is quite extensive and could serve as a counter-example. 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. Out of my head: instead of writing doc in several places, maybe something "like that" could be used. it could be associated with some clojure.core/*short-docstring* global var that (doc), (find-doc) could use for displaying the short or full form ? > My instinct is to put those sorts of things into comments. I think > adding a huge Clojure metadata map in front of the var would hinder > code readability. Hmmm, I wonder if maybe there would be a way to use > a macro to add metadata to the var separate from the function? E.g., > (document my-function metadata) That might make the metadata approach > more palatable... Sure. A lot of things are already placed as metadata of the var and not of the function the var is holding, anyway. > As a side note, I wish Clojure had some sort of block commenting > capability. Both (comment ...) and #_ require well formed code to > follow and sometimes it's just nice to be able to comment out a block > of text. I remember having seen #| .... |# block commenting reader macro to be on the todo list of Rich, many months ago. -- 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
