On Sep 18, 2008, at 7:52 AM, Rich Hickey wrote:
> 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. OK, given that, I have some thoughts and questions: [1] We have 4 symbols for which special-symbol? returns true, but which shouldn't be documented because they are private to Clojure's (current) implementation: & fn* let* loop* [1a] Would it be acceptable for doc to acknowledge the fact that they are not ordinary symbols, but give no further info as in: user=> (doc fn*) ------------------------- fn* Reserved Symbol fn* is used internally by Clojure and should be avoided in user code nil user=> or would you prefer user=> (doc fn*) no doc available for fn* user=> [1b] The docs for monitor-enter and monitor-exit essentially put them in this same group of symbols intended for internal use. Should they be moved into this class of "Reserved Symbols" or left where they are as special forms that are documented as "don't use". (One advantage of their current status is the pointer the docs provide to the locking macro.) [2] There are 15 other symbols for which special-symbol? returns true that we could document by referring to an anchor: . catch def do finally if monitor-enter monitor-exit new quote recur set! throw try var [2a] Would you please provide anchors for those on the special_forms page? [2b] Is this acceptable for the documentation?: user=> (doc if) ------------------------- if Special Form Please see: http://clojure.org/special_forms#if nil user=> [2c] Am I correct that strictly speaking, a "special form" is a form with one of these special symbols in its first position? Should doc refer to these symbols as "Special Symbols" of "Special Operators" instead? [3] Would it be a worthwhile change for "def" to reject definition of vars with names for which special-symbol? returns true? Here are a couple of interactions that one might find confusing in the absence of "def" rejecting them with a clear message: user=> (defn fn* [x] (+ x 3)) #'user/fn* user=> (fn* 4) java.lang.ClassCastException: java.lang.Integer cannot be cast to clojure.lang.ISeq [...] user=> (defn monitor-enter [x] (+ x 3)) #'user/monitor-enter user=> (monitor-enter 4) java.lang.IllegalMonitorStateException [...] Thanks, --Steve --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
