docs/internal: add builtins and invoke modules

4 files changed, 40 insertions, 35 deletions

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.