more changes for ldoc

13 files changed, 291 insertions, 173 deletions

diff --git a/core/ast.moon b/core/ast.moon
new file mode 100644
index 0000000..31aed1f
--- /dev/null
+++ b/core/ast.moon
@@ -0,0 +1,45 @@
+----
+-- AST Node Interface.
+--
+-- implemented by `Value` and `Cell`.
+--
+-- @classmod AST
+
+
+--- members
+-- @section members
+
+  --- evaluate this AST Node.
+  --
+  -- Evaluate this node and return a `Result`.
+  --
+  -- @class function
+  -- @name eval
+  -- @tparam Scope scope the scope to evaluate in
+  -- @treturn Result the evaluation result
+
+  --- quote this AST Node, preserving its identity.
+  --
+  --- Returns a mutable copy of this Node that shares its identity.
+  --
+  -- @class function
+  -- @name quote
+  -- @treturn AST
+
+  --- create a clone with its own identity.
+  --
+  -- creates a clone of this Cell with its own identity by prepending a `parent`
+  -- Tag (and cloning all child expressions recursively).
+  --
+  -- @class function
+  -- @name clone
+  -- @tparam Tag parent
+  -- @treturn AST
+
+  --- stringify this AST Node.
+  --
+  -- Should return the exact string this node was parsed from (if it was parsed).
+  --
+  -- @class function
+  -- @name stringify
+  -- @treturn string the exact string this Node was parsed from
diff --git a/core/base/action.moon b/core/base/action.moon
index 0b9dc77..74f098a 100644
--- a/core/base/action.moon
+++ b/core/base/action.moon
@@ -13,13 +13,14 @@ class Action
 -- methods that have to be implemented by `Action` implementations.
 -- @section interface
 
-  --- create a new instance
-  -- @tparam Value head the (`\eval`d) head of the Cell to evaluate
+  --- create a new instance.
+  --
+  -- @tparam Value head the (`AST:eval`d) `head` of the Cell to evaluate
   -- @tparam Tag tag the Tag of the expression to evaluate
   new: (head, @tag) =>
     @patch head
 
-  --- perform the actual evaluation
+  --- perform the actual evaluation.
   --
   -- Implementations should:
   --
@@ -35,10 +36,10 @@ class Action
   --- free resources
   destroy: =>
 
-  --- attempt to update this instance with a new `@head` prior to `\eval`.
+  --- attempt to update this instance with a new `head` prior to `eval`.
   --
-  -- If `\patch` returns `false`, this instance is `\destroy`ed and recreated.
-  -- Must *not* return `false` when called immediately after `\new`.
+  -- If `patch` returns `false`, this instance is `destroy`ed and recreated.
+  -- Must *not* return `false` when called immediately after `new`.
   -- Only considered if Action types of old and new expression match.
   --
   -- @tparam AST head the new head value
@@ -49,6 +50,14 @@ class Action
 
     @head = head
 
+  --- the last head used to construct this instance
+  --
+  -- @tfield AST head
+
+  --- the identity of the `Cell` this Action was created for.
+  --
+  -- @tfield Tag tag
+
 --- static functions
 -- @section static
 
@@ -60,10 +69,10 @@ class Action
   --
   -- @tparam Scope scope the active scope
   -- @tparam Tag tag the tag of the `Cell` being evaluated
-  -- @tparam Value head the (`\eval`d) head of the `Cell` being evaluated
-  -- @tparam {Ast,...} tail the raw AST parameters to the `Cell` being evaluated
+  -- @tparam Value head the (`AST:eval`d) head of the `Cell` being evaluated
+  -- @tparam {AST,...} tail the raw AST parameters to the `Cell` being evaluated
   -- @treturn Result the result of evaluation
-  eval_cell: (scope, tag, head, tail) =>
+  @eval_cell: (scope, tag, head, tail) =>
     last = tag\last!
     compatible = last and
                  (last.__class == @) and
diff --git a/core/base/fndef.moon b/core/base/fndef.moon
index b6c284b..5e65eba 100644
--- a/core/base/fndef.moon
+++ b/core/base/fndef.moon
@@ -9,8 +9,8 @@
 class FnDef
   --- create a new instance
   --
-  -- @tparam {Value,...} params (`\quote`d) naming the function parameters
-  -- @tparam AST body (`\quote`d) expression the function evaluates to
+  -- @tparam {Value,...} params (`AST:quote`d) naming the function parameters
+  -- @tparam AST body (`AST:quote`d) expression the function evaluates to
   -- @tparam Scope scope the lexical scope the function was defined in (closure)
   new: (@params, @body, @scope) =>
 
diff --git a/core/base/input.moon b/core/base/input.moon
index 14c812e..772b34e 100644
--- a/core/base/input.moon
+++ b/core/base/input.moon
@@ -16,7 +16,7 @@ class Input
   --- create an instance (optional).
   --
   -- `value` is either a `Value` or a `Result` instance and should be
-  -- unwrapped and assigned to `@stream`.
+  -- unwrapped and assigned to `stream`.
   --
   -- @function new
   -- @tparam Value|Result value
@@ -32,28 +32,29 @@ class Input
 
   --- copy state from old instance (optional).
   --
-  -- called by `Op``\setup` with another `Input` instance or `nil` once this instance is
-  -- registered. Must prepare this instance for `\dirty`.
+  -- called by `Op:setup` with another `Input` instance or `nil` once this instance is
+  -- registered. Must prepare this instance for `dirty`.
   --
-  -- May enter a 'setup state' that is exited using `\finish_setup`.
+  -- May enter a 'setup state' that is exited using `finish_setup`.
   --
   -- @function setup
-  -- @tparam `Input?` prev previous `Input` intance or nil
+  -- @tparam ?Input prev previous `Input` intance or nil
+  -- @see Op\setup
   setup: (prev) =>
 
   --- whether this input requires processing (optional).
   --
   -- must return a boolean indicating whether `Op`s that refer to this instance
-  -- should be notified (via `Op``\tick`). If not overwritten, delegates to
-  -- `@stream\dirty`.
+  -- should be notified (via `Op:tick`). If not overwritten, delegates to
+  -- `stream`:@{Value:dirty|dirty}.
   --
   -- @treturn bool whether processing is necessary
   dirty: => @stream\dirty!
 
   --- leave setup state (optional).
   --
-  -- called after the `Op` has completed (or skipped) its first `Op``\tick` after
-  -- `Op``\setup`. Must prepare this instance for dataflow operation.
+  -- called after the `Op` has completed (or skipped) its first `Op:tick` after
+  -- `Op:setup`. Must prepare this instance for dataflow operation.
   finish_setup: =>
 
   --- unwrap to Lua value (optional).
@@ -64,11 +65,14 @@ class Input
   --- return the type name of this `Input` (optional).
   type: => @stream.type
 
---- methods.
---
--- @section methods
+  --- the current value
+  --
+  -- @tfield Value stream
+
+--- members
+-- @section members
 
-  --- alias for `\unwrap`.
+  --- alias for `unwrap`.
   __call: => @stream\unwrap!
 
   __tostring: => "#{@@__name}:#{@stream}"
@@ -76,41 +80,41 @@ class Input
     cls.__base.__call = @__call
     cls.__base.__tostring = @__tostring
 
---- constructors
--- @section constructors
+--- static functions
+-- @section static
 
-  --- Create a `ColdInput`.
+  --- Create a `cold` `Input`.
   --
   -- Never marked dirty. Use this for input streams that are only read when
   -- another `Input` is dirty.
   --
   -- @tparam Value|Result value
-  cold: (value) -> ColdInput value
+  @cold: (value) -> ColdInput value
 
-  --- Create a `ValueInput`.
+  --- Create a `value` `Input`.
   --
   -- Marked dirty for the eval-tick if old and new `Value` differ. This is the
   -- most common `Input` strategy. Should be used whenever a
   -- value denotes state.
   --
   -- @tparam Value|Result value
-  value: (value) -> ValueInput value
+  @value: (value) -> ValueInput value
 
-  --- Create an `EventInput`.
+  --- Create an `event` `Input`.
   --
   -- Only marked dirty if the `Value` itself is dirty. Should be used whenever
   -- an `Input` denotes a momentary event or impulse.
   --
   -- @tparam Value|Result value
-  event: (value) -> EventInput value
+  @event: (value) -> EventInput value
 
-  --- Create an `IOInput`.
+  --- Create an `IO` `Input`.
   --
   -- Marked dirty only when an `IO` is dirty. Must be used only for `Value`s
-  -- which `\unwrap` to `IO` instances.
+  -- which @{Value:unwrap|unwrap}` to `IO` instances.
   --
   -- @tparam Value|Result value
-  io: (value) -> IOInput value
+  @io: (value) -> IOInput value
 
 class ColdInput extends Input
   dirty: => false
diff --git a/core/base/io.moon b/core/base/io.moon
index e7399e8..a60410f 100644
--- a/core/base/io.moon
+++ b/core/base/io.moon
@@ -12,7 +12,7 @@ class IO
 
   --- construct a new instance.
   --
-  -- Must prepare the instance for `\dirty` to be called.
+  -- Must prepare the instance for `dirty` to be called.
   new: =>
 
   --- poll for changes.
@@ -23,8 +23,8 @@ class IO
   --- check whether this adapter requires processing.
   --
   -- Must return a boolean indicating whether `Op`s that refer to this instance
-  -- via `Input``.io` should be notified (via `Op``\tick`). May be called multiple
-  -- times. May be called before `\tick` on the first frame after construction.
+  -- via `Input.io` should be notified (via `Op:tick`). May be called multiple
+  -- times. May be called before `tick` on the first frame after construction.
   --
   -- @treturn bool whether processing is required
   dirty: =>
diff --git a/core/base/op.moon b/core/base/op.moon
index 6d1ec98..8475ded 100644
--- a/core/base/op.moon
+++ b/core/base/op.moon
@@ -12,7 +12,7 @@ class Op
 
   --- construct a new instance.
   --
-  -- The super-constructor can be used to construct a `Value` instance in `@out`.
+  -- The super-constructor can be used to construct a `Value` instance in `out`.
   --
   -- @function new
 
@@ -21,21 +21,21 @@ class Op
   -- Called once every eval-cycle. `inputs` is a list of `Result`s that are the
   -- argument to this op. The `inputs` have to be wrapped in `Input` instances
   -- to define update behaviour. Use `base.match` to parse them, then delegate to
-  -- `super\setup` to patch the `Input` instances.
+  -- `super:setup` to patch the `Input` instances.
   --
   -- @function setup
-  -- @tparam inputs [`Result`] a sequence of `Result`s
-  -- @tparam scope Scope the active scope
+  -- @tparam {Result,...} inputs a sequence of `Result`s
+  -- @tparam Scope scope the active scope
 
-  --- handle incoming events and update `@out` (optional).
+  --- handle incoming events and update `out` (optional).
   --
   -- Called once per frame if any `Input`s are dirty. Some `Input`s (like
-  -- `ValueInput`) have special behaviour immediately after `\setup`, that can
+  -- `Input.value`) have special behaviour immediately after `setup`, that can
   -- cause them to become dirty at eval-time. In this case, an eval-time tick
   -- is executed. You can detect this using the `setup` parameter.
   --
-  -- `\tick` is called after `\setup`. `tick` is not called immediately after
-  -- `\setup` if no `@inputs` are dirty. Update `@out` here.
+  -- `tick` is called after `setup`. `tick` is not called immediately after
+  -- `setup` if no `inputs` are dirty. Update `out` here.
   --
   -- @tparam bool setup whether this is an eval-time tick
   tick: =>
@@ -43,18 +43,37 @@ class Op
   --- called when the Op is destroyed (optional).
   destroy: =>
 
-  --- a `Value` instance representing this Op's computed output value.
+  do_yield = (table) ->
+    for k, v in pairs table
+      if v.__class
+        coroutine.yield v
+      else
+        do_yield v
+  --- yield all `Input`s from the (potentially nested) `inputs` table
+  --
+  -- @treturn iterator iterator over `inputs`
+  all_inputs: => coroutine.wrap -> do_yield @inputs
+
+  --- `Value` instance representing this Op's computed output value.
   --
-  -- Must be set to a `Value` instance once `\setup` finishes. Must not change
-  -- type, be removed or replaced outside of `\new` and `\setup`. Should have a
-  -- value assigned via `\set` or the `Value` constructor once `\tick` is
-  -- called the first time. If `@out`'s value is not initialized in `\new`
-  -- or `\setup`, the implementation must make sure `\tick(true)` is called at
-  -- least on the first eval-cycle the Op goes through, e.g. by using a
-  -- `ValueInput`.
+  -- Must be set to a `Value` instance once `setup` finishes. Must not change
+  -- type, be removed or replaced outside of `new` and `setup`. Should have a
+  -- value assigned via `set` or the `Value` constructor once `tick` is
+  -- called the first time. If `out`'s value is not initialized in `new`
+  -- or `setup`, the implementation must make sure `tick``(true)` is called at
+  -- least on the first eval-cycle the Op goes through, e.g. by using an
+  -- `Input.value`.
   --
   -- @tfield Value out
 
+  --- table containing `Input`s to this Op.
+  --
+  -- The `inputs` table can be nested with string or integer keys,
+  -- but all leaf-entries must be `Input` instances. It must not contain loops
+  -- or instances of other classes.
+  --
+  -- @tfield {Input,...} inputs
+
 --- implementation utilities.
 --
 -- super-methods and utilities for use by implementations.
@@ -65,64 +84,47 @@ class Op
   -- it is okay not to use this and create the output stream in :setup() if the
   -- type is not known at this time.
   --
-  -- @tparam[opt] string type the type-name for `@out`
-  -- @tparam[optchain] any init the initial value for `@out`
+  -- @tparam[opt] string type the type-name for `out`
+  -- @tparam[optchain] any init the initial value for `out`
   new: (type, init) =>
     if type
       @out = Value type, init
 
-  --- setup previous `@inputs`, if any, with the new inputs, and write them to
-  -- `@inputs`. The `inputs` table can be nested with string or integer keys,
+  do_setup = (old, cur) ->
+    for k, cur_val in pairs cur
+      old_val = old and old[k]
+
+      -- are these inputs or nested tables?
+      cur_plain = cur_val and not cur_val.__class
+      old_plain = old_val and not old_val.__class
+
+      if cur_plain and old_plain
+        -- both are tables, recurse
+        do_setup old_val, cur_val
+      elseif not (cur_plain or old_plain)
+        -- both are streams (or nil), setup them
+        cur_val\setup old_val
+  --- setup previous `inputs`, if any, with the new inputs, and write them to
+  -- `inputs`. The `inputs` table can be nested with string or integer keys,
   -- but all leaf-entries must be `Input` instances. It must not contain loops
   -- or instances of other classes.
   --
   -- @tparam table inputs table of `Input`s
-  setup: do
-    do_setup = (old, cur) ->
-      for k, cur_val in pairs cur
-        old_val = old and old[k]
-
-        -- are these inputs or nested tables?
-        cur_plain = cur_val and not cur_val.__class
-        old_plain = old_val and not old_val.__class
-
-        if cur_plain and old_plain
-          -- both are tables, recurse
-          do_setup old_val, cur_val
-        elseif not (cur_plain or old_plain)
-          -- both are streams (or nil), setup them
-          cur_val\setup old_val
-
-    (inputs) =>
+  setup: (inputs) =>
       old_inputs = @inputs
       @inputs = inputs
       do_setup old_inputs, @inputs
 
-  --- yield all `Input`s from the (potentially nested) inputs table
-  --
-  -- @treturn iterator iterator over all `Input`s
-  all_inputs: do
-    do_yield = (table) ->
-      for k, v in pairs table
-        if v.__class
-          coroutine.yield v
-        else
-          do_yield v
-
-    => coroutine.wrap -> do_yield @inputs
-
+  do_unwrap = (value) ->
+    if value.__class
+      value\unwrap!
+    else
+      {k, do_unwrap v for k,v in pairs value}
   --- `\unwrap` all `Input`s in `@inputs` and return a table with the same
   -- shape.
   --
   -- @treturn table the values of all `Input`s
-  unwrap_all: do
-    do_unwrap = (value) ->
-      if value.__class
-        value\unwrap!
-      else
-        {k, do_unwrap v for k,v in pairs value}
-
-    => do_unwrap @inputs
+  unwrap_all: => do_unwrap @inputs
 
   __tostring: => "<op: #{@@__name}>"
   __inherited: (cls) => cls.__base.__tostring = @__tostring
diff --git a/core/cell.moon b/core/cell.moon
index 4d46b64..f023b25 100644
--- a/core/cell.moon
+++ b/core/cell.moon
@@ -12,12 +12,9 @@ import Tag from require 'core.tag'
 local RootCell
 
 class Cell
---- methods
--- @section methods
+--- members
+-- @section members
 
-  -- 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]
@@ -37,6 +34,22 @@ class Cell
 
   __tostring: => @stringify 2
 
+  --- the parsed Tag.
+  --
+  -- @tfield Tag tag
+
+  --- sequence of child AST Nodes
+  --
+  -- @tfield {AST,...} children
+
+  --- optional sequence of whitespace segments.
+  --
+  -- If set, `whitespace[i]` is the whitespace between `children[i]` and
+  -- `children[i+1]`, or the closing parenthesis of this Cell. `whitespace[0]`
+  -- is the space between the opening parenthesis and `children[1]`.
+  --
+  -- @tfield ?{string,...} whitespace
+
 --- AST interface
 --
 -- `Cell` implements the `AST` interface.
@@ -44,14 +57,14 @@ class Cell
 
   --- evaluate this Cell.
   --
-  -- `\eval`uates the head of the expression, and finds the appropriate
+  -- `AST:eval`uates the head of the expression, and finds the appropriate
   -- `Action` to invoke:
   --
   -- - if head is an `opdef`, use `invoke.op_invoke`
   -- - if head is a `fndef`, use `invoke.fn_invoke`
   -- - if head is a `builtin`, unwrap it
   --
-  -- then calls `\eval_cell` on the `Action`.
+  -- then calls `Action:eval_cell` on it.
   --
   -- @tparam Scope scope the scope to evaluate in
   -- @treturn Result the evaluation result
@@ -75,20 +88,21 @@ class Cell
   --- quote this Cell, preserving its identity.
   --
   -- Recursively quotes children, but preserves identity (i.e, shares the
-  -- `Tag`). A quoted Cell may only be 'used' once. If you want to `\eval` a
-  -- `Cell` multiple times, use `\clone`.
+  -- `Tag`). A quoted Cell may only be 'used' once. If you want to `eval` a
+  -- `Cell` multiple times, use `clone`.
   --
-  -- @treturn Cell quoted
-  quote: (scope) =>
+  -- @treturn Cell
+  quote: =>
     children = [child\quote scope for child in *@children]
     Cell @tag, children, @white
 
   --- create a clone with its own identity.
   --
   -- creates a clone of this Cell with its own identity by prepending a `parent`
-  -- to `@tag` and cloning all child expressoins recursively.
+  -- to `tag` and cloning all child expressions recursively.
   --
-  -- @treturn Cell clone
+  -- @tparam Tag parent
+  -- @treturn Cell
   clone: (parent) =>
     tag = @tag\clone parent
     children = [child\clone parent for child in *@children]
@@ -138,9 +152,9 @@ class Cell
   -- @tparam[opt] Tag tag
   -- @tparam table parts
   -- @treturn Cell
-  parse: (...) =>
+  @parse: (...) ->
     tag, children, white = parse_args ...
-    @ tag, children, white
+    Cell tag, children, white
 
   --- parse a root Cell (for parsing with Lpeg).
   --
@@ -149,8 +163,9 @@ class Cell
   --
   -- @tparam table parts
   -- @treturn Cell
-  parse_root: (parts) =>
-    RootCell.parse RootCell, (Tag\parse '0'), parts
+  @parse_root: (...) ->
+    tag, children, white = parse_args (Tag\parse '0'), ...
+    RootCell tag, children, white
 
 -- @type RootCell
 class RootCell extends Cell
diff --git a/core/parsing.moon b/core/parsing.moon
index 911f473..52dde27 100644
--- a/core/parsing.moon
+++ b/core/parsing.moon
@@ -36,10 +36,10 @@ expr = (V 'cell') + atom
 explist = Ct mspace * ((V 'expr') * (space * (V 'expr'))^0 * mspace)^-1
 
 tag = (P '[') * (digit^1 / Tag\parse) * (P ']')
-cell = (P '(') * tag^-1 * (V 'explist') * (P ')') / Cell\parse
+cell = (P '(') * tag^-1 * (V 'explist') * (P ')') / Cell.parse
 
 root = P {
-  (V 'explist') / Cell\parse_root
+  (V 'explist') / Cell.parse_root
   :expr, :explist, :cell
 }
 
diff --git a/core/registry.moon b/core/registry.moon
index edce9bd..900c052 100644
--- a/core/registry.moon
+++ b/core/registry.moon
@@ -24,8 +24,8 @@ class Registry
 
   next_tag: => #@map + 1
 
---- methods
--- @section methods
+--- members
+-- @section members
 
   --- create an instance.
   new: =>
diff --git a/core/result.moon b/core/result.moon
index 9f0bce7..1d527fe 100644
--- a/core/result.moon
+++ b/core/result.moon
@@ -1,14 +1,6 @@
 ----
 -- Result of evaluating an expression.
 --
--- Contains (all optional):
---
--- - `@value`: a `Value`
--- - `@op`: an `Op` (to update)
--- - `@children`: a lsit of child `Results` (from subexpressions)
--- - `@side_inputs`: cached list of all `Inputs` affecting any `Op` in this
---   subtree
---
 -- `Result`s form a tree that controls execution order and message passing
 -- between `Op`s.
 --
@@ -16,8 +8,8 @@
 import base from require 'core.cycle'
 
 class Result
---- methods
--- @section methods
+--- members
+-- @section members
 
   --- create a new Result.
   -- @param params table with optional keys op, value, children. default: {}
@@ -104,6 +96,25 @@ class Result
     buf ..= ">"
     buf
 
+  --- the `Value` result
+  --
+  -- @tfield ?Value value
+
+  --- an Op
+  --
+  -- @tfield ?Op op
+
+  --- list of child `Result`s from subexpressions
+  --
+  -- @tfield {}|{Result,...} children
+
+  --- cached mapping of all `Value`/`Input` pairs affecting this Result.
+  --
+  -- This is the union of all `children`s `side_inputs` and all `Input`s from
+  -- `op` that are not the `value` of any child.
+  --
+  -- @tfield {[Value]=Input,...} side_inputs
+
 {
   :Result
 }
diff --git a/core/scope.moon b/core/scope.moon
index c61a446..a7373c4 100644
--- a/core/scope.moon
+++ b/core/scope.moon
@@ -6,8 +6,8 @@ import Value from require 'core.value'
 import Result from require 'core.result'
 
 class Scope
---- methods
--- @section methods
+--- members
+-- @section members
 
   --- create an instance.
   --
@@ -19,7 +19,7 @@ class Scope
 
   --- set a Lua value in the scope.
   --
-  -- wraps `val` in a `Value` and `Result` before calling `\set`.
+  -- wraps `val` in a `Value` and `Result` before calling `set`.
   --
   -- @tparam string key
   -- @tparam any val
@@ -72,21 +72,6 @@ class Scope
     for k, v in pairs other.values
       @values[k] = v
 
---- static functions
--- @section static
-
-  --- converts a Lua table to a Scope.
-  --
-  -- `tbl` may contain more tables (or `Scope`s).
-  -- Uses `Value``.wrap` on the values recursively.
-  --
-  -- @tparam table tbl the table to convert
-  -- @treturn Scope
-  from_table: (tbl) ->
-    with Scope!
-      for k, v in pairs tbl
-        \set_raw k, v
-
   __tostring: =>
     buf = "<Scope"
 
@@ -106,6 +91,21 @@ class Scope
     buf ..= ">"
     buf
 
+--- static functions
+-- @section static
+
+  --- converts a Lua table to a Scope.
+  --
+  -- `tbl` may contain more tables (or `Scope`s).
+  -- Uses `Value.wrap` on the values recursively.
+  --
+  -- @tparam table tbl the table to convert
+  -- @treturn Scope
+  @from_table: (tbl) ->
+    with Scope!
+      for k, v in pairs tbl
+        \set_raw k, v
+
 {
   :Scope
 }
diff --git a/core/tag.moon b/core/tag.moon
index 5e6de24..5819aae 100644
--- a/core/tag.moon
+++ b/core/tag.moon
@@ -19,13 +19,13 @@ class DummyReg
 dummy = DummyReg!
 
 class Tag
---- methods
--- @section methods
+--- members
+-- @section members
 
   --- obtain the registered value of the last eval-cycle.
   --
-  -- Obtain the value that was previously registered (using `\keep` or
-  -- `\replace`) for this tag on the last eval-cylce.
+  -- Obtain the value that was previously registered (using `keep` or
+  -- `replace`) for this tag on the last eval-cylce.
   --
   -- @treturn ?any
   last: =>
@@ -91,13 +91,13 @@ class Tag
   --- create a blank `Tag`.
   --
   -- @treturn Tag
-  blank: -> Tag!
+  @blank: -> Tag!
 
   --- parse a `Tag` (for Lpeg parsing).
   --
   -- @tparam string num the number-string
   -- @treturn Tag
-  parse: (num) => @ tonumber num
+  @parse: (num) => @ tonumber num
 
 class ClonedTag extends Tag
   new: (@original, @parent) =>
diff --git a/core/value.moon b/core/value.moon
index c6ed42d..b0370e0 100644
--- a/core/value.moon
+++ b/core/value.moon
@@ -12,13 +12,13 @@ ancestor = (klass) ->
   klass
 
 class Value
---- methods
--- @section methods
+--- members
+-- @section members
 
   --- construct a new Value.
   --
   -- @tparam string type the type name
-  -- @tparam any value the Lua value to be accessed through \unwrap
+  -- @tparam any value the Lua value to be accessed through `unwrap`
   -- @tparam string raw the raw string that resulted in this value. Used by `parsing`.
   new: (@type, @value, @raw) =>
 
@@ -43,7 +43,7 @@ class Value
     assert type == @type, msg or "#{@} is not a #{type}" if type
     @value
 
-  --- alias for `\unwrap`.
+  --- alias for `unwrap`.
   __call: (...) => @unwrap ...
 
   --- compare two values.
@@ -55,6 +55,38 @@ class Value
     value = if 'table' == (type @value) and rawget @value, '__base' then @value.__name else @value
     "<#{@@__name} #{@type}: #{value}>"
 
+  --- the type name of the Value.
+  --
+  -- the following builtin typenames are used:
+  --
+  -- - `str` - strings, `value` is a Lua string
+  -- - `sym` - symbols, `value` is a Lua string
+  -- - `num` - numbers, `value` is a Lua number
+  -- - `bool` - booleans, `value` is a Lua boolean
+  -- - `bang` - trigger signals, `value` is a Lua boolean
+  -- - `opdef` - `value` is an `Op` subclass
+  -- - `builtin` - `value` is an `Action` subclass
+  -- - `fndef` - `value` is a `FnDef` instance
+  -- - `scope` - `value` is a `Scope` instance
+  --
+  -- @tfield string type the type name
+
+  --- the wrapped Lua value.
+  --
+  -- the following builtin typenames are used:
+  --
+  -- - `str` - strings, `value` is a Lua string
+  -- - `sym` - symbols, `value` is a Lua string
+  -- - `num` - numbers, `value` is a Lua number
+  -- - `bool` - booleans, `value` is a Lua boolean
+  -- - `bang` - trigger signals, `value` is a Lua boolean
+  -- - `opdef` - `value` is an `Op` subclass
+  -- - `builtin` - `value` is an `Action` subclass
+  -- - `fndef` - `value` is a `FnDef` instance
+  -- - `scope` - `value` is a `Scope` instance
+  --
+  -- @tfield any value the wrapped value
+
 --- AST interface
 --
 -- `Value` implements the `AST` interface.
@@ -62,7 +94,7 @@ class Value
 
   --- evaluate this literal constant.
   --
-  -- Throws an error if `@type` is not a literal (`num`, `str` or `sym`).
+  -- Throws an error if `type` is not a literal (`num`, `str` or `sym`).
   -- Returns an eval-time const result for `num` and `str`.
   -- Resolves `sym`s in `scope` and returns a reference to them.
   --
@@ -84,7 +116,7 @@ class Value
 
   --- stringify this literal constant.
   --
-  -- Throws an error if `@raw` is not set.
+  -- Throws an error if `raw` is not set.
   --
   -- @treturn string the exact string this Value was parsed from
   stringify: => assert @raw, "stringifying Value that wasn't parsed"
@@ -97,13 +129,24 @@ class Value
 --- static functions
 -- @section static
 
+  unescape = (str) -> str\gsub '\\([\'"\\])', '%1'
+  --- create a capture-function (for parsing with Lpeg).
+  --
+  -- @tparam string type the type name (one of `num`, `sym` or `str`)
+  -- @tparam string sep the seperator char (only for `str`)
+  @parse: (type, sep) =>
+    switch type
+      when 'num' then (match) -> @ 'num', (tonumber match), match
+      when 'sym' then (match) -> @ 'sym', match, match
+      when 'str' then (match) -> @ 'str', (unescape match), sep .. match .. sep
+
   --- wrap a Lua value.
   --
   -- Attempts to guess the type and wrap a Lua value.
   --
   -- @tparam any val the value to wrap
   -- @tparam[opt] string name the name of this value (for error logging)
-  wrap: (val, name='(unknown)') ->
+  @wrap: (val, name='(unknown)') ->
     typ = switch type val
       when 'number' then 'num'
       when 'string' then 'str'
@@ -132,32 +175,21 @@ class Value
 
     Value typ, val
 
-  unescape = (str) -> str\gsub '\\([\'"\\])', '%1'
-  --- create a capture-function (for parsing with Lpeg).
-  --
-  -- @tparam string type the type name (one of `num`, `sym` or `str`)
-  -- @tparam string sep the seperator char (only for `str`)
-  parse: (type, sep) =>
-    switch type
-      when 'num' then (match) -> @ 'num', (tonumber match), match
-      when 'sym' then (match) -> @ 'sym', match, match
-      when 'str' then (match) -> @ 'str', (unescape match), sep .. match .. sep
-
   --- create a constant number.
   -- @tparam number num the number
-  num: (num) -> Value 'num', num, tostring num
+  @num: (num) -> Value 'num', num, tostring num
 
   --- create a constant string.
   -- @tparam string str the string
-  str: (str) -> Value 'str', str, "'#{str}'"
+  @str: (str) -> Value 'str', str, "'#{str}'"
 
   --- create a constant symbol.
   -- @tparam string sym the symbol
-  sym: (sym) -> Value 'sym', sym, sym
+  @sym: (sym) -> Value 'sym', sym, sym
 
   --- create a constant boolean.
   -- @tparam boolean bool the boolean
-  bool: (bool) -> Value 'bool', bool, tostring bool
+  @bool: (bool) -> Value 'bool', bool, tostring bool
 
 {
   :Value