Arc Forumnew | comments | leaders | submitlogin
2 points by almkglor 6155 days ago | link | parent

>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.



1 point by pau 6154 days ago | link

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...

-----

2 points by kennytilton 6154 days ago | link

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.

-----

1 point by almkglor 6154 days ago | link

  (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.

-----

2 points by cpfr 6154 days ago | link

almkglor that documentation is beautiful

-----

2 points by almkglor 6154 days ago | link

The full documentation is available on arc-wiki.git. Wanna make a guess on who did most of the documentation?

-----

1 point by pau 6154 days ago | link

I am really sorry I gave the impression that I was critisizing your work... my apologies.

-----

1 point by almkglor 6154 days ago | link

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

-----