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