add internals docs

10 files changed, 93 insertions, 56 deletions

diff --git a/core/base/fndef.moon b/core/base/fndef.moon
index 5e65eba..dee914f 100644
--- a/core/base/fndef.moon
+++ b/core/base/fndef.moon
@@ -7,8 +7,12 @@
 -- @classmod FnDef
 
 class FnDef
+--- static functions
+-- @section static
+
   --- create a new instance
   --
+  -- @classmethod
   -- @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)
diff --git a/core/base/input.moon b/core/base/input.moon
index 772b34e..dae5b43 100644
--- a/core/base/input.moon
+++ b/core/base/input.moon
@@ -13,12 +13,12 @@ class Input
 -- Methods that have to be implemented by `Input` implementations.
 -- @section interface
 
-  --- create an instance (optional).
+  --- create a new Input.
   --
   -- `value` is either a `Value` or a `Result` instance and should be
   -- unwrapped and assigned to `stream`.
   --
-  -- @function new
+  -- @classmethod
   -- @tparam Value|Result value
   new: (value) =>
     assert value, "nil passed to Input: #{value}"
@@ -37,9 +37,7 @@ class Input
   --
   -- May enter a 'setup state' that is exited using `finish_setup`.
   --
-  -- @function setup
   -- @tparam ?Input prev previous `Input` intance or nil
-  -- @see Op\setup
   setup: (prev) =>
 
   --- whether this input requires processing (optional).
@@ -111,7 +109,7 @@ class Input
   --- Create an `IO` `Input`.
   --
   -- Marked dirty only when an `IO` is dirty. Must be used only for `Value`s
-  -- which @{Value:unwrap|unwrap}` to `IO` instances.
+  -- which @{Value:unwrap|unwrap} to `IO` instances.
   --
   -- @tparam Value|Result value
   @io: (value) -> IOInput value
diff --git a/core/base/io.moon b/core/base/io.moon
index a60410f..7d031d0 100644
--- a/core/base/io.moon
+++ b/core/base/io.moon
@@ -13,6 +13,7 @@ class IO
   --- construct a new instance.
   --
   -- Must prepare the instance for `dirty` to be called.
+  -- @classmethod
   new: =>
 
   --- poll for changes.
diff --git a/core/base/op.moon b/core/base/op.moon
index 8475ded..f1aa9cc 100644
--- a/core/base/op.moon
+++ b/core/base/op.moon
@@ -15,6 +15,7 @@ class Op
   -- The super-constructor can be used to construct a `Value` instance in `out`.
   --
   -- @function new
+  -- @classmethod
 
   --- parse arguments and patch self.
   --
@@ -84,6 +85,7 @@ 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.
   --
+  -- @classmethod
   -- @tparam[opt] string type the type-name for `out`
   -- @tparam[optchain] any init the initial value for `out`
   new: (type, init) =>
diff --git a/core/config.ld b/core/config.ld
index 1c07337..176db90 100644
--- a/core/config.ld
+++ b/core/config.ld
@@ -1,4 +1,15 @@
-project = 'alive copilot'
-title = 'alive copilot reference'
+project = 'alive internals'
+title = 'developer docs'
+
+description = "`alive` developer documentation"
+full_description = [[This section documents the *implementation* of the alive
+language and copilot. It is relevant to everyone who is looking to modify,
+improve or extend alive with new modules, language or interpreter features.
+
+If you are looking for the language reference for users, head over to the
+[reference](../reference/index.html) section of the documentation.]]
+
 format = 'discount'
-dir = 'docs/copilot'
+style = 'docs'
+template = 'docs'
+dir = 'docs/internals'
diff --git a/core/registry.moon b/core/registry.moon
index 900c052..7c785a6 100644
--- a/core/registry.moon
+++ b/core/registry.moon
@@ -20,23 +20,15 @@ class Registry
     L\trace "reg: init pending to #{expr}"
     table.insert @pending, { :tag, :expr }
 
-  active: -> assert Registry.active_registry, "no active Registry!"
-
   next_tag: => #@map + 1
 
 --- members
 -- @section members
 
-  --- create an instance.
-  new: =>
-    @map = {}
-    @io = {}
-
-    @tick = 0
-    @kr = Result value: Value.bool true
-
   --- wrap a function with an eval-cycle.
   --
+  -- Sets the active Registry and destroys unused `Action`s and `Op`s.
+  --
   -- @tparam function fn
   -- @treturn function `fn` wrapped with eval-cycle logic
   wrap_eval: (fn) => (...) ->
@@ -62,6 +54,8 @@ class Registry
 
   --- wrap a function with a tick.
   --
+  -- Sets the active Registry and increments the global tick count.
+  --
   -- @tparam function fn
   -- @treturn function `fn` wrapped with tick logic
   wrap_tick: (fn) => (...) ->
@@ -83,6 +77,25 @@ class Registry
     assert @ == @@active_registry, "not the active registry!"
     @@active_registry, @prev = @prev, nil
 
+--- static functions
+-- @section static
+
+  --- create a new Registry.
+  -- @classmethod
+  new: =>
+    @map = {}
+    @io = {}
+
+    @tick = 0
+    @kr = Result value: Value.bool true
+
+  --- get the active Registry.
+  --
+  -- Raises an erro when there is no active Regsitry.
+  --
+  -- @treturn Registry
+  @active: -> assert Registry.active_registry, "no active Registry!"
+
 class SimpleRegistry extends Registry
   new: =>
     @cnt = 1
diff --git a/core/result.moon b/core/result.moon
index 1d527fe..e92bc5c 100644
--- a/core/result.moon
+++ b/core/result.moon
@@ -11,25 +11,6 @@ class Result
 --- members
 -- @section members
 
-  --- create a new Result.
-  -- @param params table with optional keys op, value, children. default: {}
-  new: (params={}) =>
-    @value = params.value
-    @op = params.op
-    @children = params.children or {}
-
-    @side_inputs, is_child = {}, {}
-    for child in *@children
-      for s, d in pairs child.side_inputs
-        @side_inputs[s] = d
-      if child.value
-        is_child[child.value] = true
-
-    if @op
-      for input in @op\all_inputs!
-        if input.impure or not is_child[input.stream]
-          @side_inputs[input.stream] = input
-
   --- return whether this Result's value is const.
   is_const: => not next @side_inputs
 
@@ -115,6 +96,30 @@ class Result
   --
   -- @tfield {[Value]=Input,...} side_inputs
 
+--- static functions
+-- @section static
+
+  --- create a new Result.
+  -- @classmethod
+  -- @param params table with optional keys op, value, children. default: {}
+  new: (params={}) =>
+    @value = params.value
+    @op = params.op
+    @children = params.children or {}
+
+    @side_inputs, is_child = {}, {}
+    for child in *@children
+      for s, d in pairs child.side_inputs
+        @side_inputs[s] = d
+      if child.value
+        is_child[child.value] = true
+
+    if @op
+      for input in @op\all_inputs!
+        if input.impure or not is_child[input.stream]
+          @side_inputs[input.stream] = input
+
+
 {
   :Result
 }
diff --git a/core/scope.moon b/core/scope.moon
index a7373c4..f3699d7 100644
--- a/core/scope.moon
+++ b/core/scope.moon
@@ -9,14 +9,6 @@ class Scope
 --- members
 -- @section members
 
-  --- create an instance.
-  --
-  -- @tparam[opt] Scope parent a parent this scope inherits definitions from
-  -- @tparam[opt] Scope dynamic_parent a parent scope that should be checked for
-  -- dynamic definitions
-  new: (@parent, @dynamic_parent) =>
-    @values = {}
-
   --- set a Lua value in the scope.
   --
   -- wraps `val` in a `Value` and `Result` before calling `set`.
@@ -94,7 +86,16 @@ class Scope
 --- static functions
 -- @section static
 
-  --- converts a Lua table to a Scope.
+  --- create a new Scope.
+  --
+  -- @classmethod
+  -- @tparam[opt] Scope parent a parent this scope inherits definitions from
+  -- @tparam[opt] Scope dynamic_parent a parent scope that should be checked for
+  -- dynamic definitions
+  new: (@parent, @dynamic_parent) =>
+    @values = {}
+
+  --- convert a Lua table to a Scope.
   --
   -- `tbl` may contain more tables (or `Scope`s).
   -- Uses `Value.wrap` on the values recursively.
diff --git a/core/value.moon b/core/value.moon
index b0370e0..1e528ed 100644
--- a/core/value.moon
+++ b/core/value.moon
@@ -15,13 +15,6 @@ class Value
 --- 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 string raw the raw string that resulted in this value. Used by `parsing`.
-  new: (@type, @value, @raw) =>
-
   --- return whether this Value was changed in the current tick.
   --
   -- @treturn bool
@@ -129,6 +122,15 @@ class Value
 --- static functions
 -- @section static
 
+  --- construct a new Value.
+  --
+  -- @classmethod
+  -- @tparam string type the type name
+  -- @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) =>
+
+
   unescape = (str) -> str\gsub '\\([\'"\\])', '%1'
   --- create a capture-function (for parsing with Lpeg).
   --
diff --git a/core/version.moon b/core/version.moon
index c33a8a1..1dbde05 100644
--- a/core/version.moon
+++ b/core/version.moon
@@ -1,5 +1,5 @@
 ----
--- `alive` source code version information
+-- `alive` source code version information.
 --
 -- @module version
 
@@ -10,6 +10,6 @@
 -- @tfield string rev_long the full git revision hash
 {
   tag: "v0.0"
-  rev_short: "891c138"
-  rev_long: "891c138c8a8a4c9269f3eb70f424b5c1ea3898b0"
+  rev_short: "c1bf536"
+  rev_long: "c1bf53627c894e4068aca5576d054803bc574a86"
 }