Some work on comments, to make docco a bit happier.

src/client/base64.coffee

@@ -31,17 +31,17 @@ decodeBase64 = (input) ->
     else if       cc ==  47 then 63      # /
     else if       cc ==  61 then -1      # Padding
     else throw new Error "Invalid base64 input character: #{c}"
-    # Did we complete a quad?
-    continue unless quadIndex == 3
 
-    # Calculate the octet values.
+    # Did we complete a quad? If so, calculate the octet values and add them to the output.
     # We take bits from the character values as follows: 000000 001111 111122 222222
+    continue unless quadIndex == 3
     output[outputIndex++] = ((quad[0] & 0x3F) << 2) + ((quad[1] & 0x30) >> 4)
     output[outputIndex++] = ((quad[1] & 0x0F) << 4) + ((quad[2] & 0x3C) >> 2) unless quad[2] == -1
     output[outputIndex++] = ((quad[2] & 0x03) << 6) + ((quad[3] & 0x3F)     ) unless quad[3] == -1
 
+  # Return output.
   output
 
 
-# Exports.
+#### Exports
 exports.decodeBase64 = decodeBase64

src/client/brequire.coffee

@@ -2,6 +2,8 @@
 # This version is slightly modified, and rewritten in CoffeeScript.
 
 
+# The require function loads the module on-demand, or returns the existing `exports` object in case
+# the module is already loaded.
 require = (path) ->
   unless m = require.modules[path]
     throw "Couldn't find module for: #{path}"
@@ -12,8 +14,11 @@ require = (path) ->
 
   m.exports
 
+# Our index of modules.
 require.modules = {}
 
+# Helper used to create the `require` function used in the inner scope of the module. It takes
+# care of making paths relative to the current module work as expected.
 require.bind = (path, directory) ->
   (p) ->
     return require(p) unless p.charAt(0) == '.'
@@ -27,6 +32,8 @@ require.bind = (path, directory) ->
 
     require cwd.join('/')
 
+# The function used to define a module. Each module that is loaded into the browser should be
+# wrapped with a call to this function.
 require.module = (path, directory, fn) ->
   fn.directory =
     if typeof(directory) == 'boolean'
@@ -38,5 +45,5 @@ require.module = (path, directory, fn) ->
   require.modules[path] = fn
 
 
-# Exports.
+#### Exports
 window.require = require

src/client/index.coffee

@@ -22,6 +22,9 @@ DefaultRenderer  = require './renderer/offscreen_2d'
 EverardIsland    = require './everard'
 
 
+
+#### Common logic
+
 class BaseGame
   constructor: ->
     # Setup the key handlers.
@@ -51,12 +54,11 @@ class BaseGame
     @renderer = new DefaultRenderer(@resources.images, @sim)
     @sim.map.setView(@renderer)
 
-  # Game loop.
+  ##### Game loop.
 
   start: ->
     return if @gameTimer?
 
-    # Are we networked or not?
     @tick()
     @lastTick = Date.now()
 
@@ -76,7 +78,7 @@ class BaseGame
       @lastTick += TICK_LENGTH_MS
     @renderer.draw()
 
-  # Abstract methods.
+  ##### Abstract methods.
 
   # Called after resources are loaded.
   startup: ->
@@ -89,6 +91,9 @@ class BaseGame
   handleKeyup: (e) ->
 
 
+
+#### Local game simulation
+
 class LocalGame extends BaseGame
   startup: ->
     map = SimulationMap.load decodeBase64(EverardIsland)
@@ -100,7 +105,7 @@ class LocalGame extends BaseGame
   tick: ->
     @sim.tick()
 
-  # Key press handlers.
+  ##### Key press handlers.
 
   handleKeydown: (e) ->
     switch e.which
@@ -122,6 +127,8 @@ class LocalGame extends BaseGame
     e.preventDefault()
 
 
+#### Networked game simulation
+
 class NetworkGame extends BaseGame
   constructor: ->
     @heartbeatTimer = 0
@@ -155,7 +162,7 @@ class NetworkGame extends BaseGame
       @heartbeatTimer = 0
       @ws.send('')
 
-  # Key press handlers.
+  ##### Key press handlers.
 
   handleKeydown: (e) ->
     return unless @ws?
@@ -179,7 +186,7 @@ class NetworkGame extends BaseGame
       else return
     e.preventDefault()
 
-  # Network message handlers.
+  ##### Network message handlers.
 
   handleMessage: (e) ->
     @netctx.authoritative = yes
@@ -238,6 +245,8 @@ class NetworkGame extends BaseGame
         -1
 
 
+#### Entry point
+
 game = null
 
 init = ->
@@ -247,7 +256,7 @@ init = ->
     game = new NetworkGame()
 
 
-# Exports.
+#### Exports
 exports.init  = init
 exports.start = -> game.start()
 exports.stop  = -> game.stop()

src/client/loader.coffee

@@ -2,8 +2,9 @@
 # firing a single event when everything is complete, and exposing resources in a tidy structure.
 
 
-# FIXME: Add audio file support. Needs to be smart about supported formats.
-# FIXME: Implement progress notification.
+# FIXME:
+#  * Add audio file support. Needs to be smart about supported formats.
+#  * Implement progress notification.
 
 class Loader
   constructor: ->
@@ -52,5 +53,5 @@ class Loader
   onError: ->
 
 
-# Exports.
+#### Exports
 module.exports = Loader

src/client/renderer/common_2d.coffee

@@ -118,5 +118,5 @@ class Common2dRenderer extends BaseRenderer
     @ctx.restore()
 
 
-# Exports.
+#### Exports
 module.exports = Common2dRenderer

src/client/renderer/direct_2d.coffee

@@ -35,5 +35,5 @@ class Direct2dRenderer extends Common2dRenderer
     , stx, sty, etx, ety
 
 
-# Exports
+#### Exports
 module.exports = Direct2dRenderer

src/client/renderer/index.coffee

@@ -39,7 +39,7 @@ class BaseRenderer
   # Inherited from MapView.
   onRetile: (cell, tx, ty) ->
 
-  # Common functions.
+  #### Common functions.
 
   # Draw a single frame.
   draw: ->
@@ -67,6 +67,8 @@ class BaseRenderer
     # Update all DOM HUD elements.
     @updateHud()
 
+  #### HUD elements
+
   # Draw HUD elements that overlay the map. These are elements that need to be drawn in regular
   # game coordinates, rather than screen coordinates.
   drawOverlay: ->
@@ -126,5 +128,5 @@ class BaseRenderer
       $(node).attr('status', 'neutral')
 
 
-# Exports.
+#### Exports
 module.exports = BaseRenderer

src/client/renderer/offscreen_2d.coffee

@@ -20,7 +20,9 @@ MAP_SIZE_SEGMENTS = MAP_SIZE_TILES / SEGMENT_SIZE_TILES
 SEGMENT_SIZE_PIXEL = SEGMENT_SIZE_TILES * TILE_SIZE_PIXELS
 
 
-# This class represents a single segment.
+#### Cached segment
+
+# This class represents a single map segment.
 class CachedSegment
   constructor: (@renderer, x, y) ->
     # Tile bounds
@@ -71,31 +73,34 @@ class CachedSegment
           cell.x * TILE_SIZE_PIXELS, cell.y * TILE_SIZE_PIXELS, @ctx
 
 
+#### Renderer
+
+# The off-screen renderer keeps a 2D array of instances of MapSegment.
 class Offscreen2dRenderer extends Common2dRenderer
   constructor: (images, sim) ->
     super
 
-    # Build a 2D array of map segments.
     @cache = new Array(MAP_SIZE_SEGMENTS)
     for y in [0...MAP_SIZE_SEGMENTS]
       row = @cache[y] = new Array(MAP_SIZE_SEGMENTS)
       for x in [0...MAP_SIZE_SEGMENTS]
         row[x] = new CachedSegment(this, x, y)
 
+  # When a cell is retiled, we store the tile index and update the segment.
   onRetile: (cell, tx, ty) ->
-    # Remember the tilemap index.
     cell.tile = [tx, ty]
 
-    # Notify the segment, so it can update it's buffer if it has one.
     segx = floor(cell.x / SEGMENT_SIZE_TILES)
     segy = floor(cell.y / SEGMENT_SIZE_TILES)
     @cache[segy][segx].onRetile(cell, tx, ty)
 
+  # Drawing the map is a matter of iterating the map segments that are on-screen, and blitting
+  # the off-screen canvas to the main canvas. The segments are prepared on-demand from here, and
+  # extra care is taken to only build one segment per frame.
   drawMap: (sx, sy, w, h) ->
     ex = sx + w - 1
     ey = sy + h - 1
 
-    # Iterate all cache segments.
     alreadyBuiltOne = no
     for row in @cache
       for segment in row
@@ -106,7 +111,6 @@ class Offscreen2dRenderer extends Common2dRenderer
 
         # Make sure the segment buffer is available.
         unless segment.canvas
-          # Let's only draw one segment per frame, to keep things smooth.
           continue if alreadyBuiltOne
           segment.build()
           alreadyBuiltOne = yes
@@ -119,5 +123,5 @@ class Offscreen2dRenderer extends Common2dRenderer
     return
 
 
-# Exports
+#### Exports
 module.exports = Offscreen2dRenderer