1 files changed, 22 insertions, 20 deletions
diff --git a/core/cell.moon b/core/cell.moon
index 0cb8e9f..4b28a04 100644
--- a/core/cell.moon
+++ b/core/cell.moon
@@ -3,24 +3,9 @@ import Value from require 'core.value'
 import op_invoke, fn_invoke from require 'core.invoke'
 import Tag from require 'core.tag'
 
--- ALV Cell type
+-- An S-Expression with a head expression and any number of tail expressions,
+-- an optional tag, and optionally the internal whitespace as parsed.
 class Cell
--- common
-  -- tag:      the parsed Tag
-  -- children: sequence of child AST Nodes
-  -- white:    optional sequence of whitespace segments ([0 .. #@children])
-  new: (@tag=Tag.blank!, @children, @white) =>
-    if not @white
-      @white = ['' for i=1,#@children]
-      @white[0] = ''
-
-    assert #@white == #@children, "mismatched whitespace length"
-
-  head: => @children[1]
-  tail: => [c for c in *@children[2,]]
-
-  destroy: =>
-
 -- AST interface
   eval: (scope) =>
     head = (@head!\eval scope)\const!
@@ -42,12 +27,15 @@ class Cell
 
     Action\eval_cell scope, @tag, head, @tail!
 
+  -- quoting a Cell recursively quotes children, but preserves identity this
+  -- means that a quoted Cell may only be 'used' once. use :clone() otherwise.
   quote: (scope) =>
     children = [child\quote scope for child in *@children]
     Cell @tag, children, @white
 
+  -- creates a clone of this Cell with its own identity by prepending a `parent`
+  -- tag and cloning all child expressoins recursively.
   clone: (parent) =>
-    @tag\ensure!
     tag = @tag\clone parent
     children = [child\clone parent for child in *@children]
     Cell tag, children, @white
@@ -67,6 +55,20 @@ class Cell
 
     '(' .. @tag\stringify! .. buf .. ')'
 
+-- internal
+  -- tag:      the parsed Tag
+  -- children: sequence of child AST Nodes
+  -- white:    optional sequence of whitespace segments ([0 .. #@children])
+  new: (@tag=Tag.blank!, @children, @white) =>
+    if not @white
+      @white = [' ' for i=1,#@children]
+      @white[0] = ''
+
+    assert #@white == #@children, "mismatched whitespace length"
+
+  head: => @children[1]
+  tail: => [c for c in *@children[2,]]
+
 -- static
   __tostring: => @stringify 2
 
@@ -85,9 +87,9 @@ class Cell
     tag, children, white = parse_args ...
     @ tag, children, white
 
--- A parenthesis-less Cell (root of an ALV document)
+-- A parenthesis-less Cell (root of an ALV document).
 --
--- evaluates with an implicit 'do' in the head
+-- has an implicit head of 'do'.
 class RootCell extends Cell
   head: => Value.sym 'do'
   tail: => @children