On Sep 18, 2:58 am, "Stephen C. Gilardi" <[EMAIL PROTECTED]> wrote:
> 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.
>
> 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 ...)
>
>
> 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.
>
I'm not in favor of doing it this way, for several reasons. First,
there needs to be one place for canonic docs for each thing. For
functions and macros, that's the inline docs, from which the API page
on the site is generated. For special forms, it's:
http://clojure.org/special_forms
I'm not going to start maintaining the special forms docs in source
code. These docs inherently involve lots of prose, example code,
highlighting and mutual reference. They are not a good fit for doc,
doc is not man.
There's simply no substitute for reading the special forms page on the
site, and everyone who intends to use Clojure should do so in its
entirety.
If we want to make it so (doc def) et al do something, they should
return the simple message:
Please see: http://clojure.org/special_forms
I'll add anchors within that if it helps.
Also, fn*, let* and loop* are not part of the public interface, I
don't want them exposed - they are subject to change/disappearance at
any time.
& isn't really a special form, it's just part of the syntax for fn. It
doesn't need docs.
Thanks,
Rich
--~--~---------~--~----~------------~-------~--~----~
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
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
-~----------~----~----~----~------~----~------~--~---
