Commenting cake.coffee for Docco docs.

lib/cake.js

@@ -1,41 +1,50 @@
 (function(){
   var coffee, fs, no_such_task, oparse, options, optparse, path, print_tasks, switches, tasks;
   var __hasProp = Object.prototype.hasOwnProperty;
-  // `cake` is a simplified version of Make (Rake, Jake) for CoffeeScript.
-  // You define tasks with names and descriptions in a Cakefile, and can call them
-  // from the command line, or invoke them from other tasks.
+  // `cake` is a simplified version of [Make](http://www.gnu.org/software/make/)
+  // ([Rake](http://rake.rubyforge.org/), [Jake](http://github.com/280north/jake))
+  // for CoffeeScript. You define tasks with names and descriptions in a Cakefile,
+  // and can call them from the command line, or invoke them from other tasks.
+  // Running `cake` with no arguments will print out a list of all the tasks in the
+  // current directory's Cakefile.
+  // External dependencies.
   fs = require('fs');
   path = require('path');
   coffee = require('coffee-script');
   optparse = require('optparse');
+  // Keep track of the list of defined tasks, the accepted options, and so on.
   tasks = {};
   options = {};
   switches = [];
   oparse = null;
-  // Mixin the top-level Cake functions for Cakefiles to use.
+  // Mixin the top-level Cake functions for Cakefiles to use directly.
   process.mixin({
-    // Define a task with a name, a description, and the action itself.
+    // Define a Cake task with a short name, a sentence description,
+    // and the function to run as the action itself.
     task: function task(name, description, action) {
       return tasks[name] = {
         name: name,
         description: description,
         action: action
       };
     },
-    // Define an option that the Cakefile accepts.
+    // Define an option that the Cakefile accepts. The parsed options hash,
+    // containing all of the command-line options passed, will be made available
+    // as the first argument to the action.
     option: function option(letter, flag, description) {
       return switches.push([letter, flag, description]);
     },
-    // Invoke another task in the Cakefile.
+    // Invoke another task in the current Cakefile.
     invoke: function invoke(name) {
       if (!(tasks[name])) {
         no_such_task(name);
       }
       return tasks[name].action(options);
     }
   });
-  // Running `cake` runs the tasks you pass asynchronously (node-style), or
-  // prints them out, with no arguments.
+  // Run `cake`. Executes all of the tasks you pass, in order. Note that Node's
+  // asynchrony may cause tasks to execute in a different order than you'd expect.
+  // If no tasks are passed, print the help screen.
   exports.run = function run() {
     return path.exists('Cakefile', function(exists) {
       var _a, _b, _c, _d, arg, args;
@@ -57,7 +66,7 @@
       return _a;
     });
   };
-  // Display the list of Cake tasks.
+  // Display the list of Cake tasks in a format similar to `rake -T`
   print_tasks = function print_tasks() {
     var _a, _b, _c, _d, _e, _f, i, name, spaces, task;
     puts('');

src/cake.coffee

@@ -1,37 +1,47 @@
-# `cake` is a simplified version of Make (Rake, Jake) for CoffeeScript.
-# You define tasks with names and descriptions in a Cakefile, and can call them
-# from the command line, or invoke them from other tasks.
+# `cake` is a simplified version of [Make](http://www.gnu.org/software/make/)
+# ([Rake](http://rake.rubyforge.org/), [Jake](http://github.com/280north/jake))
+# for CoffeeScript. You define tasks with names and descriptions in a Cakefile,
+# and can call them from the command line, or invoke them from other tasks.
+#
+# Running `cake` with no arguments will print out a list of all the tasks in the
+# current directory's Cakefile.
 
+# External dependencies.
 fs:       require 'fs'
 path:     require 'path'
 coffee:   require 'coffee-script'
 optparse: require 'optparse'
 
+# Keep track of the list of defined tasks, the accepted options, and so on.
 tasks: {}
 options: {}
 switches: []
 oparse: null
 
-# Mixin the top-level Cake functions for Cakefiles to use.
+# Mixin the top-level Cake functions for Cakefiles to use directly.
 process.mixin {
 
-  # Define a task with a name, a description, and the action itself.
+  # Define a Cake task with a short name, a sentence description,
+  # and the function to run as the action itself.
   task: (name, description, action) ->
     tasks[name]: {name: name, description: description, action: action}
 
-  # Define an option that the Cakefile accepts.
+  # Define an option that the Cakefile accepts. The parsed options hash,
+  # containing all of the command-line options passed, will be made available
+  # as the first argument to the action.
   option: (letter, flag, description) ->
     switches.push [letter, flag, description]
 
-  # Invoke another task in the Cakefile.
+  # Invoke another task in the current Cakefile.
   invoke: (name) ->
     no_such_task name unless tasks[name]
-    tasks[name].action(options)
+    tasks[name].action options
 
 }
 
-# Running `cake` runs the tasks you pass asynchronously (node-style), or
-# prints them out, with no arguments.
+# Run `cake`. Executes all of the tasks you pass, in order. Note that Node's
+# asynchrony may cause tasks to execute in a different order than you'd expect.
+# If no tasks are passed, print the help screen.
 exports.run: ->
   path.exists 'Cakefile', (exists) ->
     throw new Error("Cakefile not found in ${process.cwd()}") unless exists
@@ -42,7 +52,7 @@ exports.run: ->
     options: oparse.parse(args)
     invoke arg for arg in options.arguments
 
-# Display the list of Cake tasks.
+# Display the list of Cake tasks in a format similar to `rake -T`
 print_tasks: ->
   puts ''
   for name, task of tasks