This is how it should always be done. Encoding your ideas in any programming language is a lossy operation: it's difficult or impossible to determine from an arbitrary piece of source code what the intent and purpose of the programmer originally was. Good documentation gives the missing pieces.

I've found it incredibly helpful to write the documentation of functions before the function itself. Like you, I have a small head, and unless I know exactly what I should program beforehand, it's going to be difficult and messy to keep all details in mind. Describe the intent and purpose, give a canonical example of use (single line, or a couple of more if the function is variadic), rule out illegal input, and you're set.

Note that I'm not advocating long pieces of documentation. If you cannot describe a function well in a few lines, it's too big, and it's definitely not clear to you what it should be. If the documentation is in the same place as the source code, it is worlds easier to write the documentation, write the source code, then bounce between them while developing (since both usually require iteration).

Not at all! It's been a mind-blowing experience to me to see documentation pop up in all of the arc codebase just because we had a wikipedia-like workflow.

But in my experience on large projects that kind of documentation becomes:

   # do_my_foo() is a function accepts a float and
   # returns a float, performing necessary calculations.
   double do_my_foo(double inarg) {
   .
   .
   .

1. Why?

I can see two different use cases for modules: a) controlled sharing and reuse; b) one more tool to encapsulate functionality inside the program. Which one is it, or is it both? Neither?

2. Should modules (module names) map directly to the file system hierarchy?

Why should they? Aren't they a different concept? Would it be reasonable to have more than one module per file, or more than one file per module? And what would happen when I wanted to move files?

Why shouldn't they? Aren't they ultimately saved in files?

3. Do we really need multiple namespaces?

2. no:no:no:no:no:no:no

It could be adapted for other monads if it also took return and (>>=) as arguments.

  (mac w/ (monad x . rest)
    (w/uniq (gmonad)
      ((afn (x rest)
         (if (no rest)
           `(let ,gmonad ,monad ,x)
           (self `((car ,gmonad) (fn (_) ,(car rest)) ,x)
                 (cdr rest))))
       `((cdr ,gmonad) ,x))))

  (= list-ret list)
  (= list-bind mappend)

  (= list-monad (cons list-bind list-ret))

  (w/ list-monad 10
     (list (- _ 1) _ (+ _ 1))
     (list _ (* _ 2) (* _ 3)))

  ===>
  (9 18 27 10 20 30 11 22 33)

  item!kids   ; Should really be item.'kids
  'kids.item  ; Huh? It's the same?

You could combine it with the dot operator of course but I wouldn't really see a reason for it. (Why would you use 3.+.4 instead of (3 + 4)?)

And actually, the example you gave doesn't quite work (because of quote, you can't actually put a symbol in the functional position using the . operator).

  arc> (= item (table))
  #hash()
  arc> item!kids
  nil
  arc> 'kids.item
  kids.item

  (= src car)
  (= trg cadr)
  (= w car:cddr)

  (def make-edges l
    (let edges (join l (map [list trg._ src._ w._] l))
      (let from [keep (fn (e) (is src.e _)) edges]
          (rfn fetch (a)
              (if (no a) nil
                  (atom a) (from a)
                  (join (from car.a) (fetch cdr.a)))))))

  ; Dijkstra's algorithm.
  (def shortest-paths (edges s) 
    (with (T (table)
           S (table)
           num [case _ nil +inf.0 _])
      (= T.s 0)
      (= S.s t)
      (trav edges.s
         [map [= (T:trg _) (min (num:T:trg _) (+ (num:T:src _) w._))] _]
         [map [= (S:trg _) t] _]
         [let next (keep no:S:trg (edges (map trg _)))
                 (let m (apply min (map num:T:trg next))
                   (self (keep [<= (num:T:trg _) m] next)))])
      T))

  (= edges (make-edges 
                '(a b 2) '(a c 3)
                '(b c 2) '(b d 1) '(b e 3) '(b f 2)
                '(c e 1)
                '(d e 2) '(d f 1)
                '(e f 2)))

  (prn (shortest-paths edges 'a))

  (max 1 2) ; --> 2
  1 max 2   ; --> 2

  1 max 3 max 2 max 5 ; --> 5 

  max{ <some set> }

  max{ x : <some condition for x> } .

Coming back to Lisp and Arc, is familiarity the only reason you want infix math operators? The biggest benefit you get from prefix compared to infix is its regularity and uniformity. Control structures, function calls, and (now in Arc) array and hash table access are all identical. This means you can freely add not only new functions, but new control structures, without hacking the parser and the compiler.

One reason why this happens is that you don't have precedence levels. Precedence is always explicit (bar Arc's new intrasymbol operators, which are infix), and this is why Lisp mathematical functions, such as + and *, accept multiple arguments. The distinction between (+ 1 (+ 2 3)) and (+ (+ 1 2) 3) is useless and even harmful. It's best to write it (+ 1 2 3) or 1 + 2 + 3, because the operation is associative.

  {1 + {2 * 3}}
  (+ 1 (* 2 3))

  (def foo (x y) ...)
  {x foo y}  ; --> (foo x y)

  ; "Object-oriented" method call
  {object -> method}

  ; Different kinds of assignments, common in C/C++/Java/etc.
  ; (Perhaps of little worth in Arc.)
  {x += 1}
  {x -= 1}
  {x |= bits}

  ; A "binding" operator, or Pascal-like assignment.
  {x := 1}

  ; An arbitrary relation.
  {a R b}

  ; Perl 6 pipe operator [1] look-alike.
  {{data ==> [...]} ==> processed}

This is, in fact, the reason why dwheeler decided to eschew precedence - I kept pestering him that in the future I might want to create a 'convoke operator or some other arbitrarily-named relation. Basically any {_ sym _ [sym _]...} pattern gets converted to (sym _ _ ...)

The ith item of s:

  $s[i]

  $s[-i]

  @s[0 .. x-1]

  @s[-x .. -1]

  @s[i .. $#s]

  @s[i .. j-1]

  @s[j .. j+i]

  @s[i .. $#s-j]
  # Alternative:
  (@s[i .. $#s])[0 .. j-1]

  @s[-j .. -j-i]
  # Alternative:
  (@s[-j .. -1])[0 .. i-1]

  $s[i]  # A scalar at index i
  @s[<something complex>]  # An array slice (i.e. multiple values)
  $#s  # The last index of the array s
  a .. b  # In list context, a list of numbers or letters from a to b, inclusive (can be used outside array indexing)

I did something similar when rails was first hitting the scene.