more changes for ldoc

5 files changed, 111 insertions, 96 deletions

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