Add some documentation to the parser.

dart/lib/compiler/implementation/scanner/parser.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * An event generating parser of Dart programs. This parser expects
- * all tokens in a linked list.
+ * all tokens in a linked list (aka a token stream).
+ *
+ * The class [Scanner] is used to generate a token stream. See the
+ * file scanner.dart.
+ *
+ * Subclasses of the class [Listener] are used to listen to events.
  */
 class Parser {
   final Listener listener;
   bool mayParseFunctionExpressions = true;
 
   Parser(Listener this.listener);
 
   void parseUnit(Token token) {
     while (token.kind !== EOF_TOKEN) {
       token = parseTopLevelDeclaration(token);
@@ skipping 1601 matching lines @@
     }
     listener.handleContinueStatement(hasTarget, continueKeyword, token);
     return expectSemicolon(token);
   }
 
   Token parseEmptyStatement(Token token) {
     listener.handleEmptyStatement(token);
     return expectSemicolon(token);
   }
 }