commenting coffee-script.coffee for documentation

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'