add internals docs

17 files changed, 327 insertions, 82 deletions

diff --git a/Dockerfile b/Dockerfile
index 5f92039..a84234b 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -5,7 +5,8 @@ RUN apt-get update && \
     apt-get install -y --allow-unauthenticated \
       build-essential m4 libmarkdown2-dev git
 RUN luarocks install discount DISCOUNT_INCDIR=/usr/include/x86_64-linux-gnu && \
-    luarocks install moonscript
+    luarocks install moonscript && \
+    luarocks install https://raw.githubusercontent.com/s-ol/LDoc/moonscript/ldoc-scm-2.rockspec
 
 COPY . /build/
 RUN make docs
diff --git a/Makefile b/Makefile
index 7b32a9c..60d8034 100644
--- a/Makefile
+++ b/Makefile
@@ -2,9 +2,11 @@ MODULES=$(wildcard lib/*.moon) lib/midi/launchctl.moon
 MODREFS=$(MODULES:lib/%.moon=docs/reference/%.html)
 DEPS=core/version.moon extra/docs.moon extra/layout.moon extra/dom.moon
 
-.PHONY: docs release clean
+.PHONY: docs reference internals release clean
 
-docs: docs/index.html docs/guide.html $(MODREFS) docs/reference/index.html
+docs: docs/index.html docs/guide.html reference internals
+
+reference: $(MODREFS) docs/reference/index.html
 
 release:
 	rm -f core/version.moon
@@ -22,6 +24,16 @@ docs/reference/%.html: lib/%.moon $(DEPS)
 docs/reference/index.html: $(MODREFS) $(DEPS)
 	moon extra/docs.moon $@ reference $(MODULES)
 
+docs/ldoc.css: docs/style.css
+	cp $< $@
+	
+docs/ldoc.ltp: $(DEPS)
+	moon extra/docs.moon $@ ldoc
+
+internals: core/config.ld docs/ldoc.ltp docs/ldoc.css
+	ldoc core
+
 clean:
-	rm -rf docs/reference/*
-	rm docs/index.html docs/guide.html
+	rm -rf docs/reference
+	rm -rf docs/internals
+	rm -f docs/index.html docs/guide.html docs/ldoc.*
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"
 }
diff --git a/docs/.gitignore b/docs/.gitignore
index 3014dfc..834a17b 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,2 +1,4 @@
 *.html
-copilot
+ldoc.*
+internals
+reference
diff --git a/docs/style.css b/docs/style.css
index cc84456..e063e58 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -13,6 +13,8 @@ body {
 
   font-family: 'Source Sans Pro', sans-serif;
   color: #222222;
+
+  overflow-y: scroll;
 }
 @media (max-width: 699px) {
   body {
@@ -21,7 +23,7 @@ body {
 }
 
 article {
-  padding: 3rem 2em 1em;
+  padding: 4rem 2em 1em;
 }
 
 code {
@@ -31,7 +33,6 @@ code {
   padding: 0.03em 0.2em;
 }
 
-
 pre {
   white-space: pre-wrap;
   padding: 0.5rem 1rem;
@@ -59,9 +60,9 @@ a {
   color: inherit;
 }
 
-ul {
+ul, ol {
   list-style: '- ';
-  margin: 0;
+  margin: 0.5em 0;
   padding-left: 0.6em;
 }
 
@@ -90,6 +91,10 @@ nav a {
 
 nav > a {
   margin-left: 1rem;
+  text-decoration: none;
+}
+nav > a.active {
+  text-decoration: underline;
 }
 
 nav span a {
@@ -140,5 +145,4 @@ a:hover code,
 
 .nest > p {
   margin: 0;
-  white-space: pre-wrap;
 }
diff --git a/extra/docs.moon b/extra/docs.moon
index 3afa340..ae59d6a 100644
--- a/extra/docs.moon
+++ b/extra/docs.moon
@@ -1,8 +1,8 @@
 import Value, Scope from require 'core'
 import render, layout, autoref from require 'extra.layout'
-import section, h2, p, ul, li, a, code, r from require 'extra.dom'
+import section, h1, h2, p, ul, li, a, code, r from require 'extra.dom'
 
-export OUT, require
+export OUT, BASE, require
 { OUT, command } = arg
 
 slurp = (file) ->
@@ -41,6 +41,13 @@ spit OUT, switch command
     layout
       title: 'reference'
       body: {
+        h1 (code 'alive'), " language reference"
+        p "This section documents all builtins and modules that are currently
+          available in the alive programming language."
+        p autoref "If you are new to alive, the [getting started guide][:../guide/:] is
+          the recommended place to start. If you are looking for
+          information on adding your own module or contributing to alive, check
+          out the [developer documentation][:../internals/index/:]."
         section {
           id: 'modules'
           h2 a "module index", href: '#modules'
@@ -70,5 +77,176 @@ spit OUT, switch command
 
     layout compile autoref contents, 'githubtags', 'fencedcode'
 
+  when 'ldoc'
+    BASE = '$(base)'
+    layout
+      style: '$(ldoc.css)'
+      title: '$(ldoc.title)'
+      preamble: '
+# local iter = ldoc.modules.iter
+# local M = ldoc.markup
+# local function display_name(item)
+#   if item.type == "function" then
+#     return item.name:gsub(":new$", "")..item.args
+#   else return item.name end
+#  end
+# local function use_li(ls)
+#   if #ls > 1 then return "<li>","</li>" else return "","" end
+# end
+# local base = module and "../../" or "../"'
+      body: '
+# if not module then
+# if ldoc.description then
+  <h1>$(M(ldoc.description))</h1>
+# end
+# if ldoc.full_description then
+  <p>$(M(ldoc.full_description))</p>
+#end
+
+# for kind, mods in ldoc.kinds() do
+#   kind = kind:lower()
+    <h2>$(kind)</h2>
+    <ul>
+#   for m in mods() do
+      <li>
+    		<label><a href="$(kind)/$(m.name).html"><code>$(m.name)</code></a>:</label>
+    		<span>$(M(m.summary))</span>
+    	</tr>
+#   end
+    </ul>
+# end
+# else
+  <h1>$(ldoc.module_typename(module):lower()) <code>$(module.name)</code></h1>
+  <p>$(M(module.summary, module))</p>
+  <p>$(M(module.description, module))</p>
+
+# if module.see then
+#   local li,il = use_li(module.see)
+    <h3>see also:</h3>
+    <ul>
+#   for see in iter(module.see) do
+      $(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
+#   end
+    </ul>
+# end
+
+  <h2>index</h2>
+# for kind, items in module.kinds() do
+    <h3>$(kind)</h3>
+    <ul>
+#   for item in items() do
+      <li>
+        <a href="#$(item.name)"><code>$(display_name(item))</code></a>
+        &ensp;&ndash;&ensp;$(M(item.summary))
+      </li>
+#   end
+    </ul>
+# end
+
+  <h2>details</h2>
+# for kind, items in module.kinds() do
+  <h3>$(kind)</h3>
+  <ul>
+# for item in items() do
+    <li class="def" id="$(item.name)">
+      <label>
+        <a href="#$(item.name)"><code>$(display_name(item))</code></a>
+      </label>
+      &ensp;&ndash;&ensp;$(M(item.summary))
+      <div class="nest">
+      $(M(item.description))
+
+#     if item.usage then
+#       local li,il = use_li(item.usage)
+        <h4>usage:</h4>
+        <ul>
+#       for usage in iter(item.usage) do
+          $(li)<pre class="example"><code>$(usage)</code></pre>$(il)
+#       end
+        </ul>
+#     end
+
+#     if item.params and #item.params > 0 then
+#       local subnames = module.kinds:type_of(item).subnames
+#       if subnames then
+          <h4>$(subnames:lower()):</h4>
+#       end
+        <ul>
+#       for parm in iter(item.params) do
+#         local param,sublist = item:subparam(parm)
+#         for p in iter(param) do
+#           local name = item:display_name_of(p)
+#           local tp = ldoc.typename(item:type_of_param(p))
+#           local def = item:default_of_param(p)
+#           local desc = item.params.map[p]
+#           local col = desc and desc ~= "" and ":" or ""
+            <li>
+              <label>
+                <code>$(name)</code>
+#               if tp ~= "" then
+                  ($(tp))$(col)
+#               else
+                  $(col)
+#               end
+              </label>
+              $(M(desc,item))
+#           if def == true then
+              (<em>optional</em>)
+#           elseif def then
+              (<em>default</em> $(def))
+#           end
+            </li>
+#         end
+#       end
+        </ul>
+#     end
+
+#     if item.retgroups then local groups = item.retgroups
+        <h4>returns:</h4>
+#       for i,group in ldoc.ipairs(groups) do
+          <ol>
+#         for r in group:iter() do
+#           local type, ctypes = item:return_type(r)
+#           local rt = ldoc.typename(type)
+#           local col = r.text and r.text ~= "" and ":" or ""
+            <li>
+#             if rt ~= "" then
+                ($(rt))$(col)
+#             end
+              $(M(r.text,item))
+#             if ctypes then
+                <ul>
+#               for c in ctypes:iter() do
+                  <li><span class="parameter">$(c.name)</span>
+                  <span class="types">$(ldoc.typename(c.type))</span>
+                  $(M(c.comment,item))</li>
+#               end
+                </ul>
+#             end
+            </li>
+#         end
+          </ol>
+#         if i < #groups then
+           <h4>or</h4>
+#         end
+#       end
+#     end
+
+#     if item.usage then
+#       local li,il = use_li(item.usage)
+        <h4>usage:</h4>
+        <ul>
+#       for usage in iter(item.usage) do
+          $(li)<pre class="example">$(ldoc.prettify(usage))</pre>$(il)
+#       end
+        </ul>
+#     end
+      </div>
+  </li>
+#   end
+</ul>
+# end
+# end
+'
   else
     error "unknown command '#{command}'"
diff --git a/extra/git-version.sh b/extra/git-version.sh
index 612bea4..1c90d8c 100755
--- a/extra/git-version.sh
+++ b/extra/git-version.sh
@@ -6,7 +6,7 @@ REV_LONG=`git rev-parse HEAD`
 
 cat <<EOF
 ----
--- \`alive\` source code version information
+-- \`alive\` source code version information.
 --
 -- @module version
 
diff --git a/extra/layout.moon b/extra/layout.moon
index 3f2024a..dfc8116 100644
--- a/extra/layout.moon
+++ b/extra/layout.moon
@@ -2,7 +2,7 @@ v = require 'core.version'
 
 -- render an ALV Value to a HTML string
 render = (name, value, prefix=nil) ->
-  import div, label, code, ul, li, i, a, p from require 'extra.dom'
+  import div, label, code, ul, li, i, a, pre from require 'extra.dom'
 
   id = if prefix then "#{prefix}/#{name}" else name
   type = i value.type
@@ -12,7 +12,7 @@ render = (name, value, prefix=nil) ->
       ul for k, result in opairs value!.values
         li render k, result.value, id
     when 'opdef', 'builtin'
-      p value!.doc
+      pre value!.doc
     when 'num', 'str', 'bool'
       code tostring value!
 
@@ -24,11 +24,14 @@ render = (name, value, prefix=nil) ->
 
 -- generate a relative link
 abs = (page) ->
-  assert OUT, "OUT needs to be set"
-  relative = assert (OUT\match '^docs/(.*)'), "unexpected output path"
-  _, depth = relative\gsub '/', '/'
-  up = string.rep '../', depth
-  "#{up}#{page}"
+  if BASE
+    "#{BASE}#{page}"
+  else
+    assert OUT, "OUT needs to be set"
+    relative = assert (OUT\match '^docs/(.*)'), "unexpected output path"
+    _, depth = relative\gsub '/', '/'
+    up = string.rep '../', depth
+    "#{up}#{page}"
 
 -- generate a link to a reference entry
 -- entry is one of
@@ -53,6 +56,12 @@ autoref = (str) ->
   str = str\gsub '%[([^%]]-)%]%[:(.-):%]', r
   str
 
+aopts = (href, pat) ->
+  {
+    href: abs href
+    class: if OUT\match "^docs/#{pat}" then 'active'
+  }
+
 -- layout and write a doc page
 -- opts:
 --  - title
@@ -68,9 +77,10 @@ layout = (opts) ->
       ' documentation'
     }
     div class: 'grow'
-    a 'home', href: abs 'index.html'
-    a 'getting started', href: abs 'guide.html'
-    a 'reference', href: abs 'reference/index.html'
+    a 'home', aopts 'index.html', 'index.html$'
+    a 'getting started', aopts 'guide.html', 'guide.html$'
+    a 'reference', aopts 'reference/index.html', 'reference'
+    a 'internals', aopts 'internals/index.html', 'ldoc'
   }
   body = article opts.body
   title = if opts.title
@@ -84,14 +94,15 @@ layout = (opts) ->
     os.date '!%Y-%m-%d %T'
   }
 
-  "<!DOCTYPE html>
+  "#{opts.preamble or ''}
+<!DOCTYPE html>
 <html>
   <head>
     <meta charset=\"UTF-8\">
     <meta name=\"viewport\" content=\"width=640\">
 
     <title>#{title}</title>
-    <link rel=\"stylesheet\" href=\"#{abs 'style.css'}\">
+    <link rel=\"stylesheet\" href=\"#{opts.style or abs 'style.css'}\">
     #{opts.css or ''}
   </head>
   <body>