Well, if you completely forget about some function, you will have to read something anyway. I guess what you say is that the documentation is obviously more readable than code, but I'm not so sure...
It probably varies. Natural language is a mess, and in the hands of geeks...ugh. So if I have an interesting function to understand I would just as soon see the code. But if I am looking at standard library stuff it will be hard to muck up the one very short sentence description. Add to that that we have a new language with a lot of shortcut syntax and that its a Lisp and a lot of non-Lispers are hopefully looking at the language, I think maybe the ball was dropped when we were told to just read the code, as much as I grok that sentiment. It is something I am much faster to say when we have people asking about application code in a language everyone asking is supposed to know.
(mac in (x . choices)
(w/uniq g
`(let ,g ,x
(or ,@(map1 (fn (c) `(is ,g ,c)) choices)))))
(mac on (var s . body)
(if (is var 'index)
(err "Can't use index as first arg to on.")
(w/uniq gs
`(let ,gs ,s
(forlen index ,gs
(let ,var (,gs index)
,@body))))))
versus:
(from "arc.arc")
[mac] (in x . choices)
Returns true if the first argument is one of the other arguments.
See also [[some]] [[mem]]
(from "arc.arc")
[mac] (on var s . body)
Loops across the sequence `s', assigning each element to `var',
and providing the current index in `index'.
See also [[each]] [[forlen]]
The main point is this: documentation says "what this code should do". Code says: "this is how we do it". In many cases, the user of a function or macro is interested in what the code is supposed to do; how it's done is less important.
Err, sorry, but that's not what I meant. Just tooting my own horn ^^. In any case, the documentation can be improved. I did most of that while I was sick, and I'm not 100% sure it's correct - there may be subtle uses that I haven't documented. Also, the docs are far from complete - there are a huge bunch of functions without decent "see also" links. And I've only completed arc.arc yet, still haven't had time to do srv.arc, html.arc, app.arc, and prompt.arc
