Hi, I'd recommend looking at how plt-scheme solved this problem (see [1]). They actually defined alternative readers in which either prose or code can be the default input mechanism (with the other escaped in some way). I don't know if Clojure's reading system is quite flexible enough to support something like this.
In the case of Clojure's documentation it seems the main decision is whether the extended documentation and examples should live intermingled with the source code, or should later be applied to the core function symbols from some external location. Cheers -- Eric Also, Probably not appropriate to the immediate need at hand, but (to self promote) if you happen to use Emacs and you would like a robust literate-programming / reproducible-research tool for Clojure, Org-mode now supports weaving, tangling, and inline execution of embedded code [2] in many languages [3] including Clojure [4]. Laurent PETIT <laurent.pe...@gmail.com> writes: > 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. Footnotes: [1] http://lambda-the-ultimate.org/node/4017 http://docs.racket-lang.org/scribble/index.html [2] http://orgmode.org/worg/org-contrib/babel/index.php [3] http://orgmode.org/worg/org-contrib/babel/languages.php#langs [4] http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-clojure.php -- 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
