commenting coffee-script.coffee for documentation

Cakefile

@@ -55,7 +55,8 @@ task 'doc:site', 'watch and continually rebuild the documentation for the websit
 
 
 task 'doc:source', 'rebuild the internal documentation', ->
-  exec 'docco src/*.coffee && mv docs documentation/docs'
+  exec 'docco src/*.coffee && rm -r documentation/docs && mv docs documentation/docs', (err) ->
+    throw err if err
 
 
 task 'test', 'run the CoffeeScript language test suite', ->

lib/coffee-script.js

@@ -1,6 +1,12 @@
 (function(){
   var lexer, parser, path, process_scripts;
-  // Set up for both the browser and the server.
+  // 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.
+  // If included on a webpage, it will automatically sniff out, compile, and
+  // execute all scripts present in `text/coffeescript` tags.
+  // Set up dependencies correctly for both the server and the browser.
   if ((typeof process !== "undefined" && process !== null)) {
     process.mixin(require('nodes'));
     path = require('path');
@@ -11,7 +17,26 @@
     parser = exports.parser;
     this.exports = (this.CoffeeScript = {});
   }
-  // Thin wrapper for Jison compatibility around the real lexer.
+  // The current CoffeeScript version number.
+  exports.VERSION = '0.5.4';
+  // Compile a string of CoffeeScript code to JavaScript, using the Coffee/Jison
+  // compiler.
+  exports.compile = function compile(code, options) {
+    return (parser.parse(lexer.tokenize(code))).compile(options);
+  };
+  // Tokenize a string of CoffeeScript code, and return the array of tokens.
+  exports.tokens = function tokens(code) {
+    return lexer.tokenize(code);
+  };
+  // Tokenize and parse a string of CoffeeScript code, and return the AST. You can
+  // then compile it by calling `.compile()` on the root, or traverse it by using
+  // `.traverse()` with a callback.
+  exports.nodes = function nodes(code) {
+    return parser.parse(lexer.tokenize(code));
+  };
+  // The real Lexer produces a generic stream of tokens. This object provides a
+  // thin wrapper around it, compatible with the Jison API. We can then pass it
+  // directly as a "Jison lexer".
   parser.lexer = {
     lex: function lex() {
       var token;
@@ -32,21 +57,10 @@
       return this.pos;
     }
   };
-  exports.VERSION = '0.5.4';
-  // Compile CoffeeScript to JavaScript, using the Coffee/Jison compiler.
-  exports.compile = function compile(code, options) {
-    return (parser.parse(lexer.tokenize(code))).compile(options);
-  };
-  // Just the tokens.
-  exports.tokens = function tokens(code) {
-    return lexer.tokenize(code);
-  };
-  // Just the nodes.
-  exports.nodes = function nodes(code) {
-    return parser.parse(lexer.tokenize(code));
-  };
-  // Activate CoffeeScript in the browser by having it compile and eval
-  // all script tags with a content-type of text/coffeescript.
+  // Activate CoffeeScript in the browser by having it compile and evaluate
+  // all script tags with a content-type of `text/coffeescript`. This happens
+  // on page load. Unfortunately, the text contents of remote scripts cannot be
+  // accessed from the browser, so only inline script tags will work.
   if ((typeof document !== "undefined" && document !== null) && document.getElementsByTagName) {
     process_scripts = function process_scripts() {
       var _a, _b, _c, _d, tag;

src/coffee-script.coffee

@@ -1,4 +1,12 @@
-# Set up for both the browser and the server.
+# 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.
+#
+# If included on a webpage, it will automatically sniff out, compile, and
+# execute all scripts present in `text/coffeescript` tags.
+
+# Set up dependencies correctly for both the server and the browser.
 if process?
   process.mixin require 'nodes'
   path:         require 'path'
@@ -9,7 +17,27 @@ else
   parser: exports.parser
   this.exports: this.CoffeeScript: {}
 
-# Thin wrapper for Jison compatibility around the real lexer.
+# The current CoffeeScript version number.
+exports.VERSION: '0.5.4'
+
+# Compile a string of CoffeeScript code to JavaScript, using the Coffee/Jison
+# compiler.
+exports.compile: (code, options) ->
+  (parser.parse lexer.tokenize code).compile options
+
+# Tokenize a string of CoffeeScript code, and return the array of tokens.
+exports.tokens: (code) ->
+  lexer.tokenize code
+
+# Tokenize and parse a string of CoffeeScript code, and return the AST. You can
+# then compile it by calling `.compile()` on the root, or traverse it by using
+# `.traverse()` with a callback.
+exports.nodes: (code) ->
+  parser.parse lexer.tokenize code
+
+# The real Lexer produces a generic stream of tokens. This object provides a
+# thin wrapper around it, compatible with the Jison API. We can then pass it
+# directly as a "Jison lexer".
 parser.lexer: {
   lex: ->
     token: @tokens[@pos] or [""]
@@ -24,22 +52,10 @@ parser.lexer: {
   showPosition: -> @pos
 }
 
-exports.VERSION: '0.5.4'
-
-# Compile CoffeeScript to JavaScript, using the Coffee/Jison compiler.
-exports.compile: (code, options) ->
-  (parser.parse lexer.tokenize code).compile(options)
-
-# Just the tokens.
-exports.tokens: (code) ->
-  lexer.tokenize code
-
-# Just the nodes.
-exports.nodes: (code) ->
-  parser.parse lexer.tokenize code
-
-# Activate CoffeeScript in the browser by having it compile and eval
-# all script tags with a content-type of text/coffeescript.
+# Activate CoffeeScript in the browser by having it compile and evaluate
+# all script tags with a content-type of `text/coffeescript`. This happens
+# on page load. Unfortunately, the text contents of remote scripts cannot be
+# accessed from the browser, so only inline script tags will work.
 if document? and document.getElementsByTagName
   process_scripts: ->
     for tag in document.getElementsByTagName('script') when tag.type is 'text/coffeescript'