From 202ebf06ff7f0f599fe628fca15710fbc216e068 Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Sun, 7 Mar 2010 00:28:58 -0500 Subject: [PATCH] documentation for command.coffee --- Cakefile | 2 +- documentation/docs/cake.html | 2 +- documentation/docs/coffee-script.html | 2 +- .../docs/{command_line.html => command.html} | 65 ++++++++++--------- documentation/docs/grammar.html | 4 +- documentation/docs/lexer.html | 2 +- documentation/docs/nodes.html | 2 +- documentation/docs/optparse.html | 2 +- documentation/docs/repl.html | 2 +- documentation/docs/rewriter.html | 2 +- documentation/docs/scope.html | 2 +- lib/command.js | 65 +++++++++++-------- src/command.coffee | 63 +++++++++++------- 13 files changed, 124 insertions(+), 91 deletions(-) rename documentation/docs/{command_line.html => command.html} (66%) diff --git a/Cakefile b/Cakefile index 83c428e8..f9dc0549 100644 --- a/Cakefile +++ b/Cakefile @@ -55,7 +55,7 @@ task 'doc:site', 'watch and continually rebuild the documentation for the websit task 'doc:source', 'rebuild the internal documentation', -> - exec 'docco src/*.coffee && cp -rf docs documentation/docs && rm -r docs', (err) -> + exec 'docco src/*.coffee && cp -rf docs documentation && rm -r docs', (err) -> throw err if err diff --git a/documentation/docs/cake.html b/documentation/docs/cake.html index 0135ae12..ba9e7c37 100644 --- a/documentation/docs/cake.html +++ b/documentation/docs/cake.html @@ -1,4 +1,4 @@ - cake.coffee

cake.coffee

#

cake is a simplified version of Make + cake.coffee

cake.coffee

#

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.

diff --git a/documentation/docs/coffee-script.html b/documentation/docs/coffee-script.html index a8c55895..83ff08fc 100644 --- a/documentation/docs/coffee-script.html +++ b/documentation/docs/coffee-script.html @@ -1,4 +1,4 @@ - coffee-script.coffee

coffee-script.coffee

#

CoffeeScript can be used both on the server, as a command-line compiler based + coffee-script.coffee

coffee-script.coffee

#

CoffeeScript can be used both on the server, as a command-line compiler based on Node.js/V8, or to run CoffeeScripts directly in the browser. This module contains the main entry functions for tokenzing, parsing, and compiling source CoffeeScript into JavaScript.

diff --git a/documentation/docs/command_line.html b/documentation/docs/command.html similarity index 66% rename from documentation/docs/command_line.html rename to documentation/docs/command.html index b5139fb7..eb3cb9ff 100644 --- a/documentation/docs/command_line.html +++ b/documentation/docs/command.html @@ -1,16 +1,16 @@ - command_line.coffee

command_line.coffee

# 
fs:           require 'fs'
+      command.coffee           
                      
                
                        
               command.coffee             
           		                               
                                             
                            
                 #               
               
The coffee utility. Handles command-line compilation of CoffeeScript
+into various forms: saved into .js files or printed to stdout, piped to
+JSLint or recompiled every time the source is
+saved, printed as a token stream or as the syntax tree, or launch an
+interactive REPL.
             		                            
             		           
                               
                            
                 #               
               
External dependencies.
             		                            
fs:           require 'fs'
 path:         require 'path'
 optparse:     require 'optparse'
-CoffeeScript: require 'coffee-script'
-
-BANNER: '''
+CoffeeScript: require 'coffee-script'
             		           
                               
                            
                 #               
               
The help banner that is printed when coffee is called without arguments.
             		                            
BANNER: '''
   coffee compiles CoffeeScript source files into JavaScript.
 
   Usage:
     coffee path/to/script.coffee
-        '''
-
-SWITCHES: [
+        '''
             		           
                               
                            
                 #               
               
The list of all the valid option flags that coffee knows how to handle.
             		                            
SWITCHES: [
   ['-c', '--compile',       'compile to JavaScript and save as .js files']
   ['-i', '--interactive',   'run an interactive CoffeeScript REPL']
   ['-o', '--output [DIR]',  'set the directory for compiled JavaScript']
@@ -24,11 +24,11 @@
   ['-n', '--nodes',         'print the parse tree that Jison produces']
   ['-v', '--version',       'display CoffeeScript version']
   ['-h', '--help',          'display this help message']
-]
-
-options: {}
+]
             		           
                               
                            
                 #               
               
Top-level objects shared by all the functions.
             		                            
options: {}
 sources: []
-option_parser: null
             		           
                               
                            
                 #               
               
The CommandLine handles all of the functionality of the coffee utility.
             		                            
exports.run: ->
+option_parser: null
             		           
                               
                            
                 #               
               
Run coffee by parsing passed options and determining what action to take.
+Many flags cause us to divert before compiling anything. Flags passed after
+-- will be passed verbatim to your script as arguments in process.ARGV
             		                            
exports.run: ->
   parse_options()
   return usage()                              if options.help
   return version()                            if options.version
@@ -43,19 +43,16 @@
     sources: sources[0...separator]
   process.ARGV: process.argv: flags
   watch_scripts() if options.watch
-  compile_scripts()
-  this
             		           
                               
                            
                 #               
               
The "--help" usage message.
             		                            
usage: ->
-  puts option_parser.help()
-  process.exit 0
             		           
                               
                            
                 #               
               
The "--version" message.
             		                            
version: ->
-  puts "CoffeeScript version ${CoffeeScript.VERSION}"
-  process.exit 0
             		           
                               
                            
                 #               
               
Compiles the source CoffeeScript, returning the desired JavaScript, tokens,
-or JSLint results.
             		                            
compile_scripts: ->
+  compile_scripts()
             		           
                               
                            
                 #               
               
Asynchronously read in each CoffeeScript in a list of source files and
+compile them.
             		                            
compile_scripts: ->
   compile: (source) ->
     path.exists source, (exists) ->
       throw new Error "File not found: $source" unless exists
       fs.readFile source, (err, code) -> compile_script(source, code)
-  compile(source) for source in sources
             		           
                               
                            
                 #               
               
Compile a single source script, containing the given code, according to the
-requested options. Both compile_scripts and watch_scripts share this method.
             		                            
compile_script: (source, code) ->
+  compile(source) for source in sources
             		           
                               
                            
                 #               
               
Compile a single source script, containing the given code, according to the
+requested options. Both compile_scripts and watch_scripts share this method
+in common. If evaluating the script directly sets __filename, __dirname
+and module.filename to be correct relative to the script's path.
             		                            
compile_script: (source, code) ->
   o: options
   try
     if      o.tokens            then print_tokens CoffeeScript.tokens code
@@ -71,37 +68,47 @@ requested options. Both compile_scripts and watch_scripts share this method.

         module.filename:  source
         eval js
   catch err
-    if o.watch                  then puts err.message else throw err
             		           
                               
                            
                 #               
               
Listen for and compile scripts over stdio.
             		                            
compile_stdio: ->
+    if o.watch                  then puts err.message else throw err
             		           
                               
                            
                 #               
               
Attach the appropriate listeners to compile scripts incoming over stdin,
+and write them back to stdout.
             		                            
compile_stdio: ->
   code: ''
   process.stdio.open()
   process.stdio.addListener 'data', (string) ->
     code += string if string
   process.stdio.addListener 'close', ->
-    process.stdio.write CoffeeScript.compile code, compile_options()
             		           
                               
                            
                 #               
               
Watch a list of source CoffeeScript files, recompiling them every time the
-files are updated.
             		                            
watch_scripts: ->
+    process.stdio.write CoffeeScript.compile code, compile_options()
             		           
                               
                            
                 #               
               
Watch a list of source CoffeeScript files using fs.watchFile, recompiling
+them every time the files are updated. May be used in combination with other
+options, such as --lint or --print.
             		                            
watch_scripts: ->
   watch: (source) ->
     fs.watchFile source, {persistent: true, interval: 500}, (curr, prev) ->
       return if curr.mtime.getTime() is prev.mtime.getTime()
       fs.readFile source, (err, code) -> compile_script(source, code)
-  watch(source) for source in sources
             		           
                               
                            
                 #               
               
Write out a JavaScript source file with the compiled code.
             		                            
write_js: (source, js) ->
+  watch(source) for source in sources
             		           
                               
                            
                 #               
               
Write out a JavaScript source file with the compiled code. By default, files
+are written out in cwd as .js files with the same name, but the output
+directory can be customized with --output.
             		                            
write_js: (source, js) ->
   filename: path.basename(source, path.extname(source)) + '.js'
   dir:      options.output or path.dirname(source)
   js_path:  path.join dir, filename
-  fs.writeFile js_path, js
             		           
                               
                            
                 #               
               
Pipe compiled JS through JSLint (requires a working 'jsl' command).
             		                            
lint: (js) ->
+  fs.writeFile js_path, js
             		           
                               
                            
                 #               
               
Pipe compiled JS through JSLint (requires a working jsl command), printing
+any errors or warnings that arise.
             		                            
lint: (js) ->
   jsl: process.createChildProcess('jsl', ['-nologo', '-stdin'])
   jsl.addListener 'output', (result) ->
     puts result.replace(/\n/g, '') if result
   jsl.addListener 'error', (result) ->
     puts result if result
   jsl.write js
-  jsl.close()
             		           
                               
                            
                 #               
               
Pretty-print a token stream.
             		                            
print_tokens: (tokens) ->
+  jsl.close()
             		           
                               
                            
                 #               
               
Pretty-print a stream of tokens.
             		                            
print_tokens: (tokens) ->
   strings: for token in tokens
     [tag, value]: [token[0], token[1].toString().replace(/\n/, '\\n')]
     "[$tag $value]"
-  puts strings.join(' ')
             		           
                               
                            
                 #               
               
Use OptionParser for all the options.
             		                            
parse_options: ->
+  puts strings.join(' ')
             		           
                               
                            
                 #               
               
Use the OptionParser module to extract all options from
+process.ARGV that are specified in SWITCHES.
             		                            
parse_options: ->
   option_parser: new optparse.OptionParser SWITCHES, BANNER
   options: option_parser.parse(process.ARGV)
-  sources: options.arguments[2...options.arguments.length]
             		           
                               
                            
                 #               
               
The options to pass to the CoffeeScript compiler.
             		                            
compile_options: ->
-  if options['no-wrap'] then {no_wrap: true} else {}
+  sources: options.arguments[2...options.arguments.length]
             		           
                               
                            
                 #               
               
The compile-time options to pass to the CoffeeScript compiler.
             		                            
compile_options: ->
+  if options['no-wrap'] then {no_wrap: true} else {}
             		           
                               
                            
                 #               
               
Print the --help usage message and exit.
             		                            
usage: ->
+  puts option_parser.help()
+  process.exit 0
             		           
                               
                            
                 #               
               
Print the --version message and exit.
             		                            
version: ->
+  puts "CoffeeScript version ${CoffeeScript.VERSION}"
+  process.exit 0
 
 
             		           
                     
   
   
\ No newline at end of file
diff --git a/documentation/docs/grammar.html b/documentation/docs/grammar.html
index 4b1e9707..4f96b3f2 100644
--- a/documentation/docs/grammar.html
+++ b/documentation/docs/grammar.html
@@ -1,4 +1,4 @@
-      grammar.coffee           
                      
                
                        
               grammar.coffee             
           		                               
                                             
                            
                 #               
                            		                            
Parser: require('jison').Parser
             		           
                               
                            
                 #               
               
DSL ===================================================================
             		                            
             		           
                               
                            
                 #               
               
Detect functions: [
             		                            
unwrap: /function\s*\(\)\s*\{\s*return\s*([\s\S]*);\s*\}/
             		           
                               
                            
                 #               
               
Quickie DSL for Jison access.
             		                            
o: (pattern_string, func, options) ->
+      grammar.coffee           
                      
                
                        
               grammar.coffee             
           		                               
                                             
                            
                 #               
                            		                            
Parser: require('jison').Parser
             		           
                               
                            
                 #               
               
DSL ===================================================================
             		                            
             		           
                               
                            
                 #               
               
Detect functions: [
             		                            
unwrap: /function\s*\(\)\s*\{\s*return\s*([\s\S]*);\s*\}/
             		           
                               
                            
                 #               
               
Quickie DSL for Jison access.
             		                            
o: (pattern_string, func, options) ->
   if func
     func: if match: (func + '').match(unwrap) then match[1] else "($func())"
     [pattern_string, "$$ = $func;", options]
@@ -12,7 +12,7 @@
   ["left",      '&', '|', '^']
   ["left",      '<=', '<', '>', '>=']
   ["right",     'DELETE', 'INSTANCEOF', 'TYPEOF']
-  ["right",     '==', '!=', 'IS', 'ISNT']
+  ["left",      '==', '!=', 'IS', 'ISNT']
   ["left",      '&&', '||', 'AND', 'OR']
   ["right",     '-=', '+=', '/=', '*=', '%=', '||=', '&&=', '?=']
   ["left",      '.']
diff --git a/documentation/docs/lexer.html b/documentation/docs/lexer.html
index 3d9a3f57..3c592251 100644
--- a/documentation/docs/lexer.html
+++ b/documentation/docs/lexer.html
@@ -1,4 +1,4 @@
-      lexer.coffee           
                      
                
                        
               lexer.coffee             
           		                               
                                             
                            
                 #               
               
The CoffeeScript Lexer. Uses a series of token-matching regexes to attempt
+      lexer.coffee           
                      
                
                        
               lexer.coffee             
           		                               
                                             
                            
                 #               
               
The CoffeeScript Lexer. Uses a series of token-matching regexes to attempt
 matches against the beginning of the source code. When a match is found,
 a token is produced, we consume the match, and start again. Tokens are in the
 form:

diff --git a/documentation/docs/nodes.html b/documentation/docs/nodes.html
index e08c1d1a..bc23b3ce 100644
--- a/documentation/docs/nodes.html
+++ b/documentation/docs/nodes.html
@@ -1,4 +1,4 @@
-      nodes.coffee           
                      
                
                        
               nodes.coffee             
           		                               
                                             
                            
                 #               
                            		                            
if process?
+      nodes.coffee           
                      
                
                        
               nodes.coffee             
           		                               
                                             
                            
                 #               
                            		                            
if process?
   process.mixin require 'scope'
 else
   this.exports: this
             		           
                               
                            
                 #               
               
Some helper functions
             		                            
             		           
                               
                            
                 #               
               
Tabs are two spaces for pretty printing.
             		                            
TAB: '  '
diff --git a/documentation/docs/optparse.html b/documentation/docs/optparse.html
index a1c0ce99..3af5b263 100644
--- a/documentation/docs/optparse.html
+++ b/documentation/docs/optparse.html
@@ -1,4 +1,4 @@
-      optparse.coffee           
                      
                
                        
               optparse.coffee             
           		                               
                                             
                            
                 #               
               
Create an OptionParser with a list of valid options, in the form:
+      optparse.coffee           
                      
                
                        
               optparse.coffee             
           		                               
                                             
                            
                 #               
               
Create an OptionParser with a list of valid options, in the form:
   [short-flag (optional), long-flag, description]
 And an optional banner for the usage help.
             		                            
exports.OptionParser: class OptionParser
 
diff --git a/documentation/docs/repl.html b/documentation/docs/repl.html
index 61d57c74..12b46dd0 100644
--- a/documentation/docs/repl.html
+++ b/documentation/docs/repl.html
@@ -1,4 +1,4 @@
-      repl.coffee           
                      
                
                        
               repl.coffee             
           		                               
                                             
                            
                 #               
               
A CoffeeScript port/version of the Node.js REPL.
             		                            
             		           
                               
                            
                 #               
               
Required modules.
             		                            
coffee: require 'coffee-script'
             		           
                               
                            
                 #               
               
Shortcut variables.
             		                            
prompt: 'coffee> '
+      repl.coffee           
                      
                
                        
               repl.coffee             
           		                               
                                             
                            
                 #               
               
A CoffeeScript port/version of the Node.js REPL.
             		                            
             		           
                               
                            
                 #               
               
Required modules.
             		                            
coffee: require 'coffee-script'
             		           
                               
                            
                 #               
               
Shortcut variables.
             		                            
prompt: 'coffee> '
 quit:   -> process.exit(0)
             		           
                               
                            
                 #               
               
The main REPL function. Called everytime a line of code is entered.
 Attempt to evaluate the command. If there's an exception, print it.
             		                            
readline: (code) ->
   try
diff --git a/documentation/docs/rewriter.html b/documentation/docs/rewriter.html
index 41be854a..1e62cc14 100644
--- a/documentation/docs/rewriter.html
+++ b/documentation/docs/rewriter.html
@@ -1,4 +1,4 @@
-      rewriter.coffee           
                      
                
                        
               rewriter.coffee             
           		                               
                                             
                            
                 #               
                            		                            
this.exports: this unless process?
             		           
                               
                            
                 #               
               
Tokens that must be balanced.
             		                            
BALANCED_PAIRS: [['(', ')'], ['[', ']'], ['{', '}'], ['INDENT', 'OUTDENT'],
+      rewriter.coffee           
                      
                
                        
               rewriter.coffee             
           		                               
                                             
                            
                 #               
                            		                            
this.exports: this unless process?
             		           
                               
                            
                 #               
               
Tokens that must be balanced.
             		                            
BALANCED_PAIRS: [['(', ')'], ['[', ']'], ['{', '}'], ['INDENT', 'OUTDENT'],
   ['PARAM_START', 'PARAM_END'], ['CALL_START', 'CALL_END'],
   ['INDEX_START', 'INDEX_END'], ['SOAKED_INDEX_START', 'SOAKED_INDEX_END']]
             		           
                               
                            
                 #               
               
Tokens that signal the start of a balanced pair.
             		                            
EXPRESSION_START: pair[0] for pair in BALANCED_PAIRS
             		           
                               
                            
                 #               
               
Tokens that signal the end of a balanced pair.
             		                            
EXPRESSION_TAIL: pair[1] for pair in BALANCED_PAIRS
             		           
                               
                            
                 #               
               
Tokens that indicate the close of a clause of an expression.
             		                            
EXPRESSION_CLOSE: ['CATCH', 'WHEN', 'ELSE', 'FINALLY'].concat(EXPRESSION_TAIL)
             		           
                               
                            
                 #               
               
Tokens pairs that, in immediate succession, indicate an implicit call.
             		                            
IMPLICIT_FUNC: ['IDENTIFIER', 'SUPER', ')', 'CALL_END', ']', 'INDEX_END']
 IMPLICIT_BLOCK:['->', '=>', '{', '[', ',']
diff --git a/documentation/docs/scope.html b/documentation/docs/scope.html
index 7e051414..7b26534e 100644
--- a/documentation/docs/scope.html
+++ b/documentation/docs/scope.html
@@ -1,4 +1,4 @@
-      scope.coffee           
                      
                
                        
               scope.coffee             
           		                               
                                             
                            
                 #               
                            		                            
this.exports: this unless process?
             		           
                               
                            
                 #               
               
Scope objects form a tree corresponding to the shape of the function
+      scope.coffee           
                      
                
                        
               scope.coffee             
           		                               
                                             
                            
                 #               
                            		                            
this.exports: this unless process?
             		           
                               
                            
                 #               
               
Scope objects form a tree corresponding to the shape of the function
 definitions present in the script. They provide lexical scope, to determine
 whether a variable has been seen before or if it needs to be declared.

 
diff --git a/lib/command.js b/lib/command.js
index 1fc519bb..88b460d3 100644
--- a/lib/command.js
+++ b/lib/command.js
@@ -2,19 +2,25 @@
   var BANNER, CoffeeScript, SWITCHES, compile_options, compile_script, compile_scripts, compile_stdio, fs, lint, option_parser, options, optparse, parse_options, path, print_tokens, sources, usage, version, watch_scripts, write_js;
   // The `coffee` utility. Handles command-line compilation of CoffeeScript
   // into various forms: saved into `.js` files or printed to stdout, piped to
-  // JSLint or recompiled every time the source is saved, printed as a token
-  // stream or as the syntax tree.
+  // [JSLint](http://javascriptlint.com/) or recompiled every time the source is
+  // saved, printed as a token stream or as the syntax tree, or launch an
+  // interactive REPL.
   // External dependencies.
   fs = require('fs');
   path = require('path');
   optparse = require('optparse');
   CoffeeScript = require('coffee-script');
+  // The help banner that is printed when `coffee` is called without arguments.
   BANNER = "coffee compiles CoffeeScript source files into JavaScript.\n\nUsage:\n  coffee path/to/script.coffee";
+  // The list of all the valid option flags that `coffee` knows how to handle.
   SWITCHES = [['-c', '--compile', 'compile to JavaScript and save as .js files'], ['-i', '--interactive', 'run an interactive CoffeeScript REPL'], ['-o', '--output [DIR]', 'set the directory for compiled JavaScript'], ['-w', '--watch', 'watch scripts for changes, and recompile'], ['-p', '--print', 'print the compiled JavaScript to stdout'], ['-l', '--lint', 'pipe the compiled JavaScript through JSLint'], ['-s', '--stdio', 'listen for and compile scripts over stdio'], ['-e', '--eval', 'compile a string from the command line'], ['--no-wrap', 'compile without the top-level function wrapper'], ['-t', '--tokens', 'print the tokens that the lexer produces'], ['-n', '--nodes', 'print the parse tree that Jison produces'], ['-v', '--version', 'display CoffeeScript version'], ['-h', '--help', 'display this help message']];
+  // Top-level objects shared by all the functions.
   options = {};
   sources = [];
   option_parser = null;
-  // The CommandLine handles all of the functionality of the `coffee` utility.
+  // Run `coffee` by parsing passed options and determining what action to take.
+  // Many flags cause us to divert before compiling anything. Flags passed after
+  // `--` will be passed verbatim to your script as arguments in `process.ARGV`
   exports.run = function run() {
     var flags, separator;
     parse_options();
@@ -46,21 +52,10 @@
     if (options.watch) {
       watch_scripts();
     }
-    compile_scripts();
-    return this;
+    return compile_scripts();
   };
-  // The "--help" usage message.
-  usage = function usage() {
-    puts(option_parser.help());
-    return process.exit(0);
-  };
-  // The "--version" message.
-  version = function version() {
-    puts("CoffeeScript version " + (CoffeeScript.VERSION));
-    return process.exit(0);
-  };
-  // Compiles the source CoffeeScript, returning the desired JavaScript, tokens,
-  // or JSLint results.
+  // Asynchronously read in each CoffeeScript in a list of source files and
+  // compile them.
   compile_scripts = function compile_scripts() {
     var _a, _b, _c, _d, compile, source;
     compile = function compile(source) {
@@ -81,7 +76,9 @@
     return _a;
   };
   // Compile a single source script, containing the given code, according to the
-  // requested options. Both compile_scripts and watch_scripts share this method.
+  // requested options. Both compile_scripts and watch_scripts share this method
+  // in common. If evaluating the script directly sets `__filename`, `__dirname`
+  // and `module.filename` to be correct relative to the script's path.
   compile_script = function compile_script(source, code) {
     var __dirname, __filename, js, o;
     o = options;
@@ -113,7 +110,8 @@
       }
     }
   };
-  // Listen for and compile scripts over stdio.
+  // Attach the appropriate listeners to compile scripts incoming over **stdin**,
+  // and write them back to **stdout**.
   compile_stdio = function compile_stdio() {
     var code;
     code = '';
@@ -127,8 +125,9 @@
       return process.stdio.write(CoffeeScript.compile(code, compile_options()));
     });
   };
-  // Watch a list of source CoffeeScript files, recompiling them every time the
-  // files are updated.
+  // Watch a list of source CoffeeScript files using `fs.watchFile`, recompiling
+  // them every time the files are updated. May be used in combination with other
+  // options, such as `--lint` or `--print`.
   watch_scripts = function watch_scripts() {
     var _a, _b, _c, _d, source, watch;
     watch = function watch(source) {
@@ -151,7 +150,9 @@
     }
     return _a;
   };
-  // Write out a JavaScript source file with the compiled code.
+  // Write out a JavaScript source file with the compiled code. By default, files
+  // are written out in `cwd` as `.js` files with the same name, but the output
+  // directory can be customized with `--output`.
   write_js = function write_js(source, js) {
     var dir, filename, js_path;
     filename = path.basename(source, path.extname(source)) + '.js';
@@ -159,7 +160,8 @@
     js_path = path.join(dir, filename);
     return fs.writeFile(js_path, js);
   };
-  // Pipe compiled JS through JSLint (requires a working 'jsl' command).
+  // Pipe compiled JS through JSLint (requires a working `jsl` command), printing
+  // any errors or warnings that arise.
   lint = function lint(js) {
     var jsl;
     jsl = process.createChildProcess('jsl', ['-nologo', '-stdin']);
@@ -176,7 +178,7 @@
     jsl.write(js);
     return jsl.close();
   };
-  // Pretty-print a token stream.
+  // Pretty-print a stream of tokens.
   print_tokens = function print_tokens(tokens) {
     var _a, _b, _c, _d, _e, strings, tag, token, value;
     strings = (function() {
@@ -194,16 +196,27 @@
     }).call(this);
     return puts(strings.join(' '));
   };
-  // Use OptionParser for all the options.
+  // Use the [OptionParser module](optparse.html) to extract all options from
+  // `process.ARGV` that are specified in `SWITCHES`.
   parse_options = function parse_options() {
     option_parser = new optparse.OptionParser(SWITCHES, BANNER);
     options = option_parser.parse(process.ARGV);
     return sources = options.arguments.slice(2, options.arguments.length);
   };
-  // The options to pass to the CoffeeScript compiler.
+  // The compile-time options to pass to the CoffeeScript compiler.
   compile_options = function compile_options() {
     return options['no-wrap'] ? {
       no_wrap: true
     } : {};
   };
+  // Print the `--help` usage message and exit.
+  usage = function usage() {
+    puts(option_parser.help());
+    return process.exit(0);
+  };
+  // Print the "--version" message and exit.
+  version = function version() {
+    puts("CoffeeScript version " + (CoffeeScript.VERSION));
+    return process.exit(0);
+  };
 })();
diff --git a/src/command.coffee b/src/command.coffee
index a65b1bb2..d52582a5 100644
--- a/src/command.coffee
+++ b/src/command.coffee
@@ -1,7 +1,8 @@
 # The `coffee` utility. Handles command-line compilation of CoffeeScript
 # into various forms: saved into `.js` files or printed to stdout, piped to
-# JSLint or recompiled every time the source is saved, printed as a token
-# stream or as the syntax tree.
+# [JSLint](http://javascriptlint.com/) or recompiled every time the source is
+# saved, printed as a token stream or as the syntax tree, or launch an
+# interactive REPL.
 
 # External dependencies.
 fs:           require 'fs'
@@ -9,6 +10,7 @@ path:         require 'path'
 optparse:     require 'optparse'
 CoffeeScript: require 'coffee-script'
 
+# The help banner that is printed when `coffee` is called without arguments.
 BANNER: '''
   coffee compiles CoffeeScript source files into JavaScript.
 
@@ -16,6 +18,7 @@ BANNER: '''
     coffee path/to/script.coffee
         '''
 
+# The list of all the valid option flags that `coffee` knows how to handle.
 SWITCHES: [
   ['-c', '--compile',       'compile to JavaScript and save as .js files']
   ['-i', '--interactive',   'run an interactive CoffeeScript REPL']
@@ -32,11 +35,14 @@ SWITCHES: [
   ['-h', '--help',          'display this help message']
 ]
 
+# Top-level objects shared by all the functions.
 options: {}
 sources: []
 option_parser: null
 
-# The CommandLine handles all of the functionality of the `coffee` utility.
+# Run `coffee` by parsing passed options and determining what action to take.
+# Many flags cause us to divert before compiling anything. Flags passed after
+# `--` will be passed verbatim to your script as arguments in `process.ARGV`
 exports.run: ->
   parse_options()
   return usage()                              if options.help
@@ -53,20 +59,9 @@ exports.run: ->
   process.ARGV: process.argv: flags
   watch_scripts() if options.watch
   compile_scripts()
-  this
 
-# The "--help" usage message.
-usage: ->
-  puts option_parser.help()
-  process.exit 0
-
-# The "--version" message.
-version: ->
-  puts "CoffeeScript version ${CoffeeScript.VERSION}"
-  process.exit 0
-
-# Compiles the source CoffeeScript, returning the desired JavaScript, tokens,
-# or JSLint results.
+# Asynchronously read in each CoffeeScript in a list of source files and
+# compile them.
 compile_scripts: ->
   compile: (source) ->
     path.exists source, (exists) ->
@@ -75,7 +70,9 @@ compile_scripts: ->
   compile(source) for source in sources
 
 # Compile a single source script, containing the given code, according to the
-# requested options. Both compile_scripts and watch_scripts share this method.
+# requested options. Both compile_scripts and watch_scripts share this method
+# in common. If evaluating the script directly sets `__filename`, `__dirname`
+# and `module.filename` to be correct relative to the script's path.
 compile_script: (source, code) ->
   o: options
   try
@@ -94,7 +91,8 @@ compile_script: (source, code) ->
   catch err
     if o.watch                  then puts err.message else throw err
 
-# Listen for and compile scripts over stdio.
+# Attach the appropriate listeners to compile scripts incoming over **stdin**,
+# and write them back to **stdout**.
 compile_stdio: ->
   code: ''
   process.stdio.open()
@@ -103,8 +101,9 @@ compile_stdio: ->
   process.stdio.addListener 'close', ->
     process.stdio.write CoffeeScript.compile code, compile_options()
 
-# Watch a list of source CoffeeScript files, recompiling them every time the
-# files are updated.
+# Watch a list of source CoffeeScript files using `fs.watchFile`, recompiling
+# them every time the files are updated. May be used in combination with other
+# options, such as `--lint` or `--print`.
 watch_scripts: ->
   watch: (source) ->
     fs.watchFile source, {persistent: true, interval: 500}, (curr, prev) ->
@@ -112,14 +111,17 @@ watch_scripts: ->
       fs.readFile source, (err, code) -> compile_script(source, code)
   watch(source) for source in sources
 
-# Write out a JavaScript source file with the compiled code.
+# Write out a JavaScript source file with the compiled code. By default, files
+# are written out in `cwd` as `.js` files with the same name, but the output
+# directory can be customized with `--output`.
 write_js: (source, js) ->
   filename: path.basename(source, path.extname(source)) + '.js'
   dir:      options.output or path.dirname(source)
   js_path:  path.join dir, filename
   fs.writeFile js_path, js
 
-# Pipe compiled JS through JSLint (requires a working 'jsl' command).
+# Pipe compiled JS through JSLint (requires a working `jsl` command), printing
+# any errors or warnings that arise.
 lint: (js) ->
   jsl: process.createChildProcess('jsl', ['-nologo', '-stdin'])
   jsl.addListener 'output', (result) ->
@@ -129,19 +131,30 @@ lint: (js) ->
   jsl.write js
   jsl.close()
 
-# Pretty-print a token stream.
+# Pretty-print a stream of tokens.
 print_tokens: (tokens) ->
   strings: for token in tokens
     [tag, value]: [token[0], token[1].toString().replace(/\n/, '\\n')]
     "[$tag $value]"
   puts strings.join(' ')
 
-# Use OptionParser for all the options.
+# Use the [OptionParser module](optparse.html) to extract all options from
+# `process.ARGV` that are specified in `SWITCHES`.
 parse_options: ->
   option_parser: new optparse.OptionParser SWITCHES, BANNER
   options: option_parser.parse(process.ARGV)
   sources: options.arguments[2...options.arguments.length]
 
-# The options to pass to the CoffeeScript compiler.
+# The compile-time options to pass to the CoffeeScript compiler.
 compile_options: ->
   if options['no-wrap'] then {no_wrap: true} else {}
+
+# Print the `--help` usage message and exit.
+usage: ->
+  puts option_parser.help()
+  process.exit 0
+
+# Print the `--version` message and exit.
+version: ->
+  puts "CoffeeScript version ${CoffeeScript.VERSION}"
+  process.exit 0