Express: Another round of docs and cleanup.

server/express/lib/cli.coffee

@@ -1,4 +1,5 @@
-# Cli for the Smallest-Federated-Wiki express server
+# **cli.coffee** command line interface for the
+# Smallest-Federated-Wiki express server
 
 path = require 'path'
 optimist = require 'optimist'
@@ -62,11 +63,9 @@ argv = optimist
 # If h/help is set print the generated help message and exit.
 if argv.h
   optimist.showHelp()
-  process.exit()
-
 # If f/farm is set call../lib/farm.coffee with argv object, else call
 # ../lib/server.coffee with argv object.
-if argv.test
+else if argv.test
   console.log "WARNING: Server started in testing mode, other options ignored"
   server({p: 33333, d: path.join(argv.r, 'spec', 'data')})
 else if argv.f

server/express/lib/defaultargs.coffee

@@ -1,5 +1,6 @@
-# **defaultargs.coffee** when called with on the argv object this
-# module will create reasonable defaults for options not supplied.
+# **defaultargs.coffee** when called on the argv object this
+# module will create reasonable defaults for options not supplied,
+# based on what information is provided.
 path = require 'path'
 
 module.exports = (argv) ->

server/express/lib/farm.coffee

@@ -1,4 +1,4 @@
-# **farm.coffee *
+# **farm.coffee**
 # The farm module works by putting a bouncy host based proxy
 # in front of servers that it creates
 
@@ -7,22 +7,37 @@ bouncy = require 'bouncy'
 server = require '../'
 
 module.exports = exports = (argv) ->
+  # Map incoming hosts to their wiki's port
   hosts = {}
+  # Keep an array of servers that are currently active
   runningServers = []
 
+  # Get the next available port.
   nextport = do ->
+    # Start port as farm port -1 so it returns the original farm
+    # port the first time it is used.
+    # TODO: Call out to the os to make sure we return an open and valid port.
     port = argv.F - 1
     -> port += 1
 
+  # Bouncy watches for incoming requests on the listen port at the bottom,
+  # and passes them to the callback it's called with,
+  # redirecting the requests at the port specified when
+  # the bounce function is called.
   bouncy( (req, bounce) ->
+    # Don't do anything for requests without a host header.
     unless req.headers?.host
       return
+    # If the host starts with "www." treat it the same as if it didn't
     if req.headers.host[0..3] is "www."
       req.headers.host = req.headers.host[4..]
+    # if we already have a port for this host, forward the request to it.
     if hosts[req.headers.host]
       bounce(hosts[req.headers.host])
     else
       hosts[req.headers.host] = nextport()
+      # Create a new options object, copy over the options used to start the
+      # farm, and modify them to make sense for servers spawned from the farm.
       newargv = {}
       for key, value of argv
         newargv[key] = value
@@ -32,6 +47,8 @@ module.exports = exports = (argv) ->
       else
         path.join(argv.r or path.join(__dirname, '..', '..', '..'), 'data', req.headers.host)
       newargv.u = "http://#{req.headers.host}"
+      # Create a new server, add it to the list of servers, and
+      # once it's ready send the request to it.
       local = server(newargv)
       runningServers.push(local)
       local.once "ready", ->

server/express/lib/page.coffee

@@ -2,14 +2,15 @@
 # Module for interacting with pages persisted on the server.
 # Everything is stored using json flat files.
 
-#### Require some stuff, nothing special here. ####
-fs = require('fs')
-path = require('path')
-mkdirp = require('mkdirp')
-random_id = require('./random_id')
-events = require('events')
+#### Requires ####
+fs = require 'fs'
+path = require 'path'
+mkdirp = require 'mkdirp'
+random_id = require './random_id'
+events = require 'events'
 
-# Export a function that generates a page handler when called options object.
+# Export a function that generates a page handler
+# when called with options object.
 module.exports = exports = (argv) ->
 
   #### Private utility methods. ####
@@ -18,7 +19,7 @@ module.exports = exports = (argv) ->
       if err then cb(err)
       cb(null, JSON.parse(data))
     )
-  
+
   load_parse_copy = (defloc, file, cb) ->
     fs.readFile(defloc, (err, data) ->
       if err then cb(err)
@@ -32,8 +33,8 @@ module.exports = exports = (argv) ->
   # Reads and writes are async, but serially queued to avoid race conditions.
   queue = []
 
-  # Main file io function, when called without page it reads, when called with page
-  # it writes.
+  # Main file io function, when called without page it reads,
+  # when called with page it writes.
   fileio = (file, page, cb) ->
     loc = path.join(argv.db, file)
     unless page?
@@ -65,8 +66,8 @@ module.exports = exports = (argv) ->
           )
       )
 
-  # Control variable that tells if the serial queue is currently happening.
-  # Set back to 0 when all jobs are complete.
+  # Control variable that tells if the serial queue is currently working.
+  # Set back to false when all jobs are complete.
   working = false
 
   # Keep file io working on queued jobs, but don't block the main thread.
@@ -82,6 +83,7 @@ module.exports = exports = (argv) ->
     else
       itself.stop()
 
+  #### Public stuff ####
   # Make the exported object an instance of EventEmitter
   # so other modules can tell if it is working or not.
   itself = new events.EventEmitter
@@ -95,16 +97,14 @@ module.exports = exports = (argv) ->
   itself.isWorking = ->
     working
 
-  # get takes a slug and a callback, it then calls the callback with the page
-  # it wanted, or the same named page from default-data, or a 404 status and message
-  # and sends it back.
+  # get method takes a slug and a callback, adding them to the queue,
+  # starting serial if it isn't already working.
   itself.get = (file, cb) ->
     queue.push({file, page: null, cb})
     serial(queue.shift()) unless working
-
-
+
   # put takes a slugged name, the page as a json object, and a callback.
-  # calls cb with an err if anything goes wrong.
+  # adds them to the queue, and starts it unless it is working.
   itself.put =  (file, page, cb) ->
       queue.push({file, page, cb})
       serial(queue.shift()) unless working

server/express/lib/random_id.coffee

@@ -1,4 +1,4 @@
-# ** random_id.coffee **
+# **random_id.coffee**
 # Simple random hex generator, takes an optional number of
 # chars that defaults to 16 and returns a random id.