>It feels right to me, and you feel that code becomes a 'definition', so I now think I should be trained enough to read "arc.arc" _without_ documentation, as if I was reading math or something
Sure, sure. Then you completely forget wtf 'on is supposed to do, and how it's different from 'in, and have to read it again.
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
