Patch to provide special form documentation online (doc, find-doc)

[Stephen C. Gilardi]

This patch makes clojure/doc and clojure/find-doc operate on special forms as well as vars. I'm enclosing it with this message, but if that doesn't work I'll upload it to the group's file section as "specialdocs.tgz". The .tgz file contains a patch file that patches boot.clj and a new file: src/clj/clojure/specialdocs.clj. The .tgz file is meant to be expanded from within the clojure home directory. Here is an example of applying the patch and using it: $ cd <checkout of clojure trunk> $ tar xzvf specialdocs.tgz  specialdocs.patch src/clj/clojure/specialdocs.clj $ patch -p0 < specialdocs.patch patching file src/clj/clojure/boot.clj $ ant [...] BUILD SUCCESSFUL Total time: 0 seconds $ clj Clojure user=> (doc doc) ------------------------- clojure/doc ([name]) Macro   Prints documentation for a var or special form given its name nil user=> (doc if) ------------------------- (if test then) (if test then else) Special Form   Evaluates test. If not nil or false, evaluates and yields then   otherwise, evaluates and yields else. If else is not supplied it defaults   to nil. All of the other conditionals in Clojure are based upon the same   logic, that is, nil and false constitute logical falsity, and everything   else constitutes logical truth, and those meaning apply throughout. if   performs conditional test of boolean Java method returns without   conversion to Boolean. nil user=> (doc foo) no doc available for foo nil user=>  Changes: - add new file src/clj/clojure/specialdocs.clj containing a private map from symbol to doc string for each of the 19 special forms and a public function that prints the doc string given the symbol. - change boot.clj to load specialdocs.clj - move definition of special-symbol? earlier in boot.clj - change find-doc to consider special form docs as well as var docs - change doc to provide doc for special forms as well as vars and to explain when doc is not available without throwing an exception - a style correction to clojure/load: (.loadResourceScript clojure.lang.RT ...) -> (clojure.lang.RT/loadResourceScript ...) Notes: - I made the docs a separate file because they're large and they currently confuse the emacs clojure mode I'm using. It's nice if that confusion is isolated to a file I'll rarely visit. - Rather than synthetic "arg lists" in Special Form docs, I used the notation from the website. For example what could have been: ------------------------- def ([symbol] [symbol init]) Special Form ... is instead ------------------------- (def symbol init?) Special Form ... The reason is that not all special forms argument lists can be expressed as if the special form were a function. The notation used on the website has more flexibility to express the variants of the special forms clearly. - The special form docs are nearly identical to the docs on the website. In cases where an item could be elided or repeated, I used the singular form followed by *. For example (do expr*) rather than (do exprs*). I also mentioned the ' reader macro in the doc for quote. I suggest the same changes for the website. - I guessed at the doc for the "&" special form, please check it. - The new print-special-form-doc has to be public because it's called from the "doc" macro expansion - The website lists fn, let, and loop as special forms, but that's no longer true. They are now macros--the corresponding special forms are fn*, let*, and loop* which don't do destructuring. I adapted the special form docs to reflect that. I suggest an update to the docs on the website to correct this. --Steve

specialdocs.tgz
Description: Binary data