On Sep 18, 11:47 am, "Stephen C. Gilardi" <[EMAIL PROTECTED]> wrote:
> 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:
I don't understand the use case. Isn't doc either for getting help for
something you've seen others do that you don't understand, or finding
new things to call? Right now it does:
user=> (doc fn*)
java.lang.Exception: Unable to resolve var: fn* in this context
same as
user=> (doc foobar)
java.lang.Exception: Unable to resolve var: foobar in this context
I'm fine with that.
> [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?
>
Done, except catch and finally, which are sub-syntax of try, like & is
for fn.
> [2b] Is this acceptable for the documentation?:
>
> user=> (doc if)
> -------------------------
> if
> Special Form
> Please see:http://clojure.org/special_forms#if
> nil
> user=>
>
Yes.
> [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?
>
No.
> [3] Would it be a worthwhile change for "def" to reject definition of
> vars with names for which special-symbol? returns true?
>
That's a separate conversation/feature.
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
-~----------~----~----~----~------~----~------~--~---
