docs/internal: add builtins and invoke modules

8 files changed, 90 insertions, 44 deletions

diff --git a/Makefile b/Makefile
index 19e3e5d..a3f736c 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,6 @@
 MODULES=$(wildcard lib/*.moon) lib/midi/launchctl.moon
 MODREFS=$(MODULES:lib/%.moon=docs/reference/%.html)
+CORE=$(wildcard core/*.moon core/**/*.moon)
 DEPS=core/version.moon extra/docs.moon extra/layout.moon extra/dom.moon
 
 .PHONY: docs reference internals release clean
@@ -30,7 +31,7 @@ docs/ldoc.css: docs/style.css
 docs/ldoc.ltp: $(DEPS)
 	moon extra/docs.moon $@ ldoc
 
-docs/internals/index.html: core/config.ld docs/ldoc.ltp docs/ldoc.css
+docs/internals/index.html: core/config.ld docs/ldoc.ltp docs/ldoc.css $(CORE)
 	ldoc core
 
 clean:
diff --git a/core/base/action.moon b/core/base/action.moon
index 74f098a..1822b58 100644
--- a/core/base/action.moon
+++ b/core/base/action.moon
@@ -1,5 +1,5 @@
 ----
--- Builtin / Special Form / `Cell`-evaluation Strategy.
+-- Builtin / Special Form evaluation Strategy (`builtin`).
 --
 -- Responsible for quoting/evaluating subexpressions, instantiating and patching
 -- `Op`s, updating the current `Scope`, etc.
diff --git a/core/base/fndef.moon b/core/base/fndef.moon
index dee914f..b79ad85 100644
--- a/core/base/fndef.moon
+++ b/core/base/fndef.moon
@@ -1,5 +1,5 @@
 ----
--- `alive` user-function definition (`fndef`).
+-- user-function definition (`fndef`).
 --
 -- When called, expands to its body with params bound to the fn arguments (see
 -- `invoke.fn_invoke`).
diff --git a/core/base/io.moon b/core/base/io.moon
index 7d031d0..3370fe1 100644
--- a/core/base/io.moon
+++ b/core/base/io.moon
@@ -1,6 +1,8 @@
 ----
--- Incoming side-effect adapter, polled by the main event loop to pump
--- events into the dataflow graph.
+-- Incoming side-effect adapter, creating events for the dataflow graph.
+--
+-- Polled by the main event loop to kick of events that cause the the dataflow
+-- graph to ripple results.
 --
 -- @classmod IO
 
diff --git a/core/base/op.moon b/core/base/op.moon
index f1aa9cc..f338673 100644
--- a/core/base/op.moon
+++ b/core/base/op.moon
@@ -5,6 +5,40 @@
 import Value from require 'core.value'
 
 class Op
+--- members
+-- @section members
+
+  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 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
+
 --- Op interface.
 --
 -- methods that have to be implemented by `Op` implementations.
@@ -44,37 +78,6 @@ class Op
   --- called when the Op is destroyed (optional).
   destroy: =>
 
-  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 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.
diff --git a/core/builtin.moon b/core/builtin.moon
index 41af7f0..3e4787c 100644
--- a/core/builtin.moon
+++ b/core/builtin.moon
@@ -1,4 +1,10 @@
--- builtin special forms
+----
+-- Builtin `Action`s and `Op`s.
+--
+-- Please see the [reference](../../reference/index.html#builtins) for
+-- documentation.
+--
+-- @module builtin
 import Action, Op, FnDef, Input, match from require 'core.base'
 import Value from require 'core.value'
 import Result from require 'core.result'
diff --git a/core/invoke.moon b/core/invoke.moon
index a401c9a..8d63962 100644
--- a/core/invoke.moon
+++ b/core/invoke.moon
@@ -7,7 +7,11 @@ import Result from require 'core.result'
 import Action from require 'core.base'
 import Scope from require 'core.scope'
 
+--- `Action` implementation that invokes an `Op`.
+--
+-- @type op_invoke
 class op_invoke extends Action
+  --- `Action:patch` implementation.
   patch: (head) =>
     return true if head == @head
 
@@ -17,7 +21,18 @@ class op_invoke extends Action
     @head, @op = head, def!
 
     true
-    
+
+  --- evaluate an `Op` invocation.
+  --
+  -- `AST:eval`s the tail, and passes the result to `op`:@{Op:setup|setup}. Then
+  -- checks if any of `op`:@{Op:all_inputs|all_inputs} are @{Input:dirty|dirty},
+  -- and if so, calls `op`:@{Op:tick|tick}.
+  --
+  -- The `Result` contains `op`, `Op.value` and all the `Result`s from the tail.
+  --
+  -- @tparam Scope scope the active scope
+  -- @tparam {AST,...} tail the arguments to this expression
+  -- @treturn Result
   eval: (scope, tail) =>
     children = [L\push expr\eval, scope for expr in *tail]
     @op\setup [result for result in *children], scope
@@ -36,11 +51,15 @@ class op_invoke extends Action
 
     Result :children, value: @op.out, op: @op
 
-class fn_invoke extends Action
-  -- @TODO:
-  -- need to :patch() the case where the new head is a new fndef
-  -- but corresponds to the last head over time
+  --- The `Op` instance.
+  --
+  -- @tfield Op op
 
+--- `Action` implementation that invokes a `FnDef`.
+--
+-- @type fn_invoke
+class fn_invoke extends Action
+  --- `Action:patch` implementation.
   patch: (head) =>
     return true if head == @head
 
@@ -48,6 +67,21 @@ class fn_invoke extends Action
 
     true
 
+  --- evaluate a user-function invocation.
+  --
+  -- Creates a new `Scope` that inherits from `FnDef.scope` and has
+  -- `outer_scope` as an additional parent for dynamic symbol resolution.
+  -- Then `AST:eval`s the tail in `outer_scope`, and defines the results to the
+  -- names in `FnDef.params` in the newly created scope. Lastly, `AST:clone`s
+  -- `FnDef.body` with the prefix `Action.tag`, and `AST:eval`s it in the newly
+  -- created `Scope`.
+  --
+  -- The `Result` contains the `Value` from the cloned AST, and its children are
+  -- all the `Result`s from evaluating the tail as well as the cloned `AST`s.
+  --
+  -- @tparam Scope outer_scope the active scope
+  -- @tparam {AST,...} tail the arguments to this expression
+  -- @treturn Result the result of this evaluation
   eval: (outer_scope, tail) =>
     { :params, :body, :scope } = @head\unwrap 'fndef', "cant fn-invoke #{@head}"
 
diff --git a/core/value.moon b/core/value.moon
index 2e93e70..0f40ef3 100644
--- a/core/value.moon
+++ b/core/value.moon
@@ -1,5 +1,5 @@
 ----
--- `alive` Value(stream), implements the `AST` inteface.
+-- Value(stream), implements the `AST` inteface.
 --
 -- @classmod Value
 import Result from require 'core.result'
@@ -31,7 +31,7 @@ class Value
   --
   -- @tparam[opt] string type the type to check for
   -- @tparam[optchain] string msg message to throw if type don't match
-  -- @treturn @value
+  -- @treturn any `value`
   unwrap: (type, msg) =>
     assert type == @type, msg or "#{@} is not a #{type}" if type
     @value