Improve documentation;

doc/README.md

@@ -1,4 +1,3 @@
-
 # Observer
 
 Observers are simple objects that receive values from Observables.
@@ -7,19 +6,36 @@ Observers are simple objects that receive values from Observables.
 
 Creates a new Observer.
 
+Arguments:
+
+- `[onNext=]` (`function`) - Called when the Observable produces a value.
+- `[onError=]` (`function`) - Called when the Observable terminates due to an error.
+- `[onComplete=]` (`function`) - Called when the Observable completes normally.
+
+Returns:
+
+- `Observer`
+
 #### `:onNext(value)`
 
 Pushes a new value to the Observer.
 
+Arguments:
+
+- `value` (`*`)
+
 #### `:onError(message)`
 
 Notify the Observer that an error has occurred.
 
+Arguments:
+
+- `[message=]` (`string`) - A string describing what went wrong.
+
 #### `:onComplete()`
 
 Notify the Observer that the sequence has completed and will produce no more values.
 
-
 # Observable
 
 Observables push values to Observers.
@@ -28,43 +44,156 @@ Observables push values to Observers.
 
 Creates a new Observable.
 
+Arguments:
+
+- `subscribe` (`function`) - The subscription function that produces values.
+
+Returns:
+
+- `Observable`
+
 #### `.fromValue(value)`
 
 Creates an Observable that produces a single value.
 
-#### `.fromCoroutine(cr)`
+Arguments:
+
+- `value` (`*`)
+
+Returns:
+
+- `Observable`
+
+#### `.fromCoroutine(coroutine)`
 
 Creates an Observable that produces values when the specified coroutine yields.
 
+Arguments:
+
+- `coroutine` (`thread`)
+
+Returns:
+
+- `Observable`
+
 #### `:subscribe(onNext, onError, onComplete)`
 
 Shorthand for creating an Observer and passing it to this Observable's subscription function.
 
+Arguments:
+
+- `onNext` (`function`) - Called when the Observable produces a value.
+- `onError` (`function`) - Called when the Observable terminates due to an error.
+- `onComplete` (`function`) - Called when the Observable completes normally.
+
 #### `:dump(name)`
 
 Subscribes to this Observable and prints values it produces.
 
+Arguments:
+
+- `[name=]` (`string`) - Prefixes the printed messages with a name.
+
 #### `:first()`
 
 Returns a new Observable that only produces the first result of the original.
 
+Returns:
+
+- `Observable`
+
 #### `:last()`
 
 Returns a new Observable that only produces the last result of the original.
 
+Returns:
+
+- `Observable`
+
 #### `:map(callback)`
 
 Returns a new Observable that produces the values of the original transformed by a function.
 
+Arguments:
+
+- `callback` (`function`) - The function to transform values from the original Observable.
+
+Returns:
+
+- `Observable`
+
 #### `:reduce(accumulator, seed)`
 
 Returns a new Observable that produces a single value computed by accumulating the results of running a function on each value produced by the original Observable.
 
+Arguments:
+
+- `accumulator` (`function`) - Accumulates the values of the original Observable. Will be passed the return value of the last call as the first argument and the current value as the second.
+- `seed` (`*`) - A value to pass to the accumulator the first time it is run.
+
+Returns:
+
+- `Observable`
+
 #### `:sum()`
 
 Returns a new Observable that produces the sum of the values of the original Observable as a single result.
 
-#### `:combineLatest(...)`
+Returns:
+
+- `Observable`
+
+#### `:combineLatest(observables, combinator)`
 
 Returns a new Observable that runs a combinator function on the most recent values from a set of Observables whenever any of them produce a new value. The results of the combinator function are produced by the new Observable.
 
+Arguments:
+
+- `observables` (`Observable...`) - One or more Observables to combine.
+- `combinator` (`function`) - A function that combines the latest result from each Observable and returns a single value.
+
+Returns:
+
+- `Observable`
+
+# Scheduler
+
+Schedulers manage groups of Observables.
+
+# CooperativeScheduler
+
+Manages Observables using coroutines and a virtual clock that must be updated manually.
+
+#### `.create(currentTime)`
+
+Creates a new Cooperative Scheduler.
+
+Arguments:
+
+- `[currentTime=0]` (`number`) - A time to start the scheduler at.
+
+Returns:
+
+- `Scheduler.Cooperative`
+
+#### `:schedule(action, delay)`
+
+Schedules a function to be run after an optional delay.
+
+Arguments:
+
+- `action` (`function`) - The function to execute. Will be converted into a coroutine. The coroutine may yield execution back to the scheduler with an optional number, which will put it to sleep for a time period.
+- `[delay=0]` (`number`) - Delay execution of the action by a time period.
+
+#### `:update(delta)`
+
+Triggers an update of the Cooperative Scheduler. The clock will be advanced and the scheduler will run any coroutines that are due to be run.
+
+Arguments:
+
+- `[delta=0]` (`number`) - An amount of time to advance the clock by. It is common to pass in the time in seconds or milliseconds elapsed since this function was last called.
+
+#### `:isEmpty()`
+
+Returns whether or not the Cooperative Scheduler's queue is empty.
+

rx.lua

@@ -3,8 +3,8 @@ local rx
 local function noop() end
 local function identity(x) return x end
 
---- Observer
--- Observers are simple objects that receive values from Observables.
+--- @class Observer
+-- @description Observers are simple objects that receive values from Observables.
 local Observer = {}
 Observer.__index = Observer
 
@@ -49,8 +49,8 @@ function Observer:onComplete()
   end
 end
 
---- Observable
--- Observables push values to Observers.
+--- @class Observable
+-- @description Observables push values to Observers.
 local Observable = {}
 Observable.__index = Observable
 
@@ -275,12 +275,13 @@ function Observable:combineLatest(...)
   end)
 end
 
---- Scheduler
--- Schedulers manage groups of Observables.
+--- @class Scheduler
+-- @description Schedulers manage groups of Observables.
 local Scheduler = {}
 
---- Cooperative Scheduler
--- Manages Observables using coroutines and a virtual clock that must be updated manually.
+--- @class CooperativeScheduler
+-- @description Manages Observables using coroutines and a virtual clock that must be updated
+-- manually.
 local Cooperative = {}
 Cooperative.__index = Cooperative
 

tools/docroc.lua

@@ -0,0 +1,86 @@
+-- docroc - Lua documentation generator
+-- https://github.com/bjornbytes/docroc
+-- License - MIT, see LICENSE for details.
+
+local rocdoc = {}
+
+function rocdoc.process(filename)
+  local file = io.open(filename, 'r')
+  local text = file:read('*a')
+  file:close()
+
+  local comments = {}
+  text:gsub('%s*%-%-%-(.-)\n([%w\n][^\n%-]*)', function(chunk, context)
+    chunk = chunk:gsub('^%s*%-*%s*', ''):gsub('\n%s*%-*%s*', ' ')
+    chunk = chunk:gsub('^[^@]', '@description %1')
+    context = context:match('[^\n]+')
+
+    local tags = {}
+    chunk:gsub('@(%w+)%s?([^@]*)', function(name, body)
+      body = body:gsub('(%s+)$', '')
+      local processor = rocdoc.processors[name]
+      local tag = processor and processor(body) or {}
+      tag.tag = name
+      tag.raw = body
+      tags[name] = tags[name] or {}
+      table.insert(tags[name], tag)
+      table.insert(tags, tag)
+    end)
+
+    table.insert(comments, {
+      tags = tags,
+      context = context
+    })
+  end)
+
+  return comments
+end
+
+rocdoc.processors = {
+  description = function(body)
+    return {
+      text = body
+    }
+  end,
+
+  arg = function(body)
+    local name = body:match('^%s*(%w+)') or body:match('^%s*%b{}%s*(%w+)')
+    local description = body:match('%-%s*(.*)$')
+    local optional, default
+    local type = body:match('^%s*(%b{})'):sub(2, -2):gsub('(%=)(.*)', function(_, value)
+      optional = true
+      default = value
+      return ''
+    end)
+
+    return {
+      type = type,
+      name = name,
+      description = description,
+      optional = optional,
+      default = default
+    }
+  end,
+
+  returns = function(body)
+    local type
+    body:gsub('^%s*(%b{})', function(match)
+      type = match:sub(2, -2)
+      return ''
+    end)
+    local description = body:match('^%s*(.*)')
+
+    return {
+      type = type,
+      description = description
+    }
+  end,
+
+  class = function(body)
+    return {
+      name = body
+    }
+  end
+}
+
+return rocdoc

tools/documentation.lua

@@ -0,0 +1,66 @@
+local docroc = require 'tools/docroc'
+
+io.output('doc/README.md')
+
+for _, comment in ipairs(docroc.process('rx.lua')) do
+  local tags = comment.tags
+
+  if tags.class then
+    io.write('# ' .. tags.class[1].name .. '\n\n')
+    if tags.description then
+      io.write(tags.description[1].text .. '\n\n')
+    end
+  else
+    local context = comment.context:match('function.-([:%.].+)')
+    if tags.arg then
+      context = context:gsub('%b()', function(signature)
+        local args = {}
+
+        for _, arg in ipairs(tags.arg) do
+          table.insert(args, arg.name)
+        end
+
+        return '(' .. table.concat(args, ', ') .. ')'
+      end)
+
+    end
+
+    io.write(('#### `%s`\n\n'):format(context))
+
+    if tags.description then
+      io.write(('%s\n\n'):format(tags.description[1].text))
+    end
+
+    if tags.arg then
+      io.write('Arguments:\n\n')
+
+      for _, arg in ipairs(tags.arg) do
+        local name = arg.name
+        if arg.optional then
+          if arg.default then
+            name = '[' .. name .. '=' .. arg.default .. ']'
+          else
+            name = '[' .. name .. ']'
+          end
+        end
+        name = '`' .. name .. '`'
+        local description = arg.description and (' - ' .. arg.description) or ''
+        local type = ' (`' .. arg.type .. '`)'
+        local line = '- ' .. name .. type .. description
+        io.write(line .. '\n')
+      end
+
+      io.write('\n')
+    end
+
+    if tags.returns then
+      io.write('Returns:\n\n')
+
+      for _, result in ipairs(tags.returns) do
+        io.write('- `' .. result.type .. '`\n')
+      end
+
+      io.write('\n')
+    end
+  end
+end