Update parser documentation.

pkg/front_end/lib/src/fasta/parser/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.
 
 library fasta.parser.parser;
 
 import '../scanner.dart' show ErrorToken;
 
 import '../scanner/recover.dart' show closeBraceFor, skipToEof;
 
@@ skipping 72 matching lines @@
   final String type;
   const FormalParameterType(this.type);
   bool get isRequired => this == REQUIRED;
   bool get isPositional => this == POSITIONAL;
   bool get isNamed => this == NAMED;
   static final REQUIRED = const FormalParameterType('required');
   static final POSITIONAL = const FormalParameterType('positional');
   static final NAMED = const FormalParameterType('named');
 }
 
-/**
- * An event generating parser of Dart programs. This parser expects
- * 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.
- *
- * Most methods of this class belong in one of two major categories:
- * parse methods and peek methods. Parse methods all have the prefix
- * parse, and peek methods all have the prefix peek.
- *
- * Parse methods generate events (by calling methods on [listener])
- * and return the next token to parse. Peek methods do not generate
- * events (except for errors) and may return null.
- *
- * Parse methods are generally named parseGrammarProductionSuffix. The
- * suffix can be one of "opt", or "star". "opt" means zero or one
- * matches, "star" means zero or more matches. For example,
- * [parseMetadataStar] corresponds to this grammar snippet: [:
- * metadata* :], and [parseTypeOpt] corresponds to: [: type? :].
- */
+/// An event generating parser of Dart programs. This parser expects 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](../scanner.dart).
+///
+/// Subclasses of the class [Listener] are used to listen to events.
+///
+/// Most methods of this class belong in one of three major categories: parse
+/// methods, peek methods, and skip methods. Parse methods all have the prefix
+/// `parse`, peek methods all have the prefix `peek`, and skip methods all have
+/// the prefix `skip`.
+///
+/// Parse methods generate events (by calling methods on [listener]) and return
+/// the next token to parse. Peek methods do not generate events (except for
+/// errors) and may return null. Skip methods are like parse methods, but skip
+/// over some parts of the file being parsed.
+///
+/// Parse methods are generally named `parseGrammarProductionSuffix`. The
+/// suffix can be one of `opt`, or `star`. `opt` means zero or one matches,
+/// `star` means zero or more matches. For example, [parseMetadataStar]
+/// corresponds to this grammar snippet: `metadata*`, and [parseTypeOpt]
+/// corresponds to: `type?`.
+///
+/// ## Implementation Notes
+///
+/// The parser assumes that keywords, built-in identifiers, and other special
+/// words (pseudo-keywords) are all canonicalized. To extend the parser to
+/// recognize a new identifier, one should modify
+/// [keyword.dart](../scanner/keyword.dart) and ensure the identifier is added
+/// to the keyword table.
+///
+/// As a consequence of this, one should not use `==` to compare strings in the
+/// parser. One should favor the methods [optional] and [expected] to recognize
+/// keywords or identifiers. In some cases, it's possible to compare a token's
+/// `stringValue` using [identical], but normally [optional] will suffice.
+///
+/// Historically, we over-used identical, and when identical is used on other
+/// objects than strings, it can often be replaced by `==`.
 class Parser {
   final Listener listener;
 
   bool mayParseFunctionExpressions = true;
 
   /// Represents parser state: what asynchronous syntax is allowed in the
   /// function being currently parsed. In rare situations, this can be set by
   /// external clients, for example, to parse an expression outside a function.
   AsyncModifier asyncState = AsyncModifier.Sync;
 
@@ skipping 256 matching lines @@
     listener.beginMetadataStar(token);
     int count = 0;
     while (optional('@', token)) {
       token = parseMetadata(token);
       count++;
     }
     listener.endMetadataStar(count, forParameter);
     return token;
   }
 
-  /**
-   * Parse
-   * [: '@' qualified (‘.’ identifier)? (arguments)? :]
-   */
+  /// Parse `'@' qualified (‘.’ identifier)? (arguments)?`
   Token parseMetadata(Token token) {
     listener.beginMetadata(token);
     Token atToken = token;
     assert(optional('@', token));
     token = parseIdentifier(token.next, IdentifierContext.metadataReference);
     token =
         parseQualifiedRestOpt(token, IdentifierContext.metadataContinuation);
     token = parseTypeArgumentsOpt(token);
     Token period = null;
     if (optional('.', token)) {
@@ skipping 534 matching lines @@
     if (optional('extends', token) || optional('super', token)) {
       extendsOrSuper = token;
       token = parseType(token.next);
     } else {
       listener.handleNoType(token);
     }
     listener.endTypeVariable(token, extendsOrSuper);
     return token;
   }
 
-  /**
-   * Returns true if the stringValue of the [token] is either [value1],
-   * [value2], or [value3].
-   */
+  /// Returns true if the stringValue of the [token] is either [value1],
+  /// [value2], or [value3].
   bool isOneOf3(Token token, String value1, String value2, String value3) {
     String stringValue = token.stringValue;
     return value1 == stringValue ||
         value2 == stringValue ||
         value3 == stringValue;
   }
 
-  /**
-   * Returns true if the stringValue of the [token] is either [value1],
-   * [value2], [value3], or [value4].
-   */
+  /// Returns true if the stringValue of the [token] is either [value1],
+  /// [value2], [value3], or [value4].
   bool isOneOf4(
       Token token, String value1, String value2, String value3, String value4) {
     String stringValue = token.stringValue;
     return value1 == stringValue ||
         value2 == stringValue ||
         value3 == stringValue ||
         value4 == stringValue;
   }
 
   bool notEofOrValue(String value, Token token) {
@@ skipping 593 matching lines @@
     int count = 0;
     while (identical(token.kind, KEYWORD_TOKEN)) {
       if (!isModifier(token)) break;
       token = parseModifier(token);
       count++;
     }
     listener.handleModifiers(count);
     return token;
   }
 
-  /**
-   * Returns the first token after the type starting at [token].
-   *
-   * This method assumes that [token] is an identifier (or void).
-   * Use [peekAfterIfType] if [token] isn't known to be an identifier.
-   */
+  /// Returns the first token after the type starting at [token].
+  ///
+  /// This method assumes that [token] is an identifier (or void).  Use
+  /// [peekAfterIfType] if [token] isn't known to be an identifier.
   Token peekAfterType(Token token) {
     // We are looking at "identifier ...".
     Token peek = token;
     if (!isGeneralizedFunctionType(token)) {
       peek = peekAfterNominalType(token);
     }
 
     // We might have just skipped over the return value of the function type.
     // Check again, if we are now at a function type position.
     while (isGeneralizedFunctionType(peek)) {
       peek = peekAfterFunctionType(peek.next);
     }
     return peek;
   }
 
-  /**
-   * Returns the first token after the nominal type starting at [token].
-   *
-   * This method assumes that [token] is an identifier (or void).
-   */
+  /// Returns the first token after the nominal type starting at [token].
+  ///
+  /// This method assumes that [token] is an identifier (or void).
   Token peekAfterNominalType(Token token) {
     Token peek = token.next;
     if (identical(peek.kind, PERIOD_TOKEN)) {
       if (peek.next.isIdentifier()) {
         // Look past a library prefix.
         peek = peek.next.next;
       }
     }
     // We are looking at "qualified ...".
     if (identical(peek.kind, LT_TOKEN)) {
       // Possibly generic type.
       // We are looking at "qualified '<'".
       BeginGroupToken beginGroupToken = peek;
       Token gtToken = beginGroupToken.endGroup;
       if (gtToken != null) {
         // We are looking at "qualified '<' ... '>' ...".
         peek = gtToken.next;
       }
     }
     return peek;
   }
 
-  /**
-   * Returns the first token after the function type starting at [token].
-   *
-   * The token must be at the token *after* the `Function` token position. That
-   * is, the return type and the `Function` token must have already been
-   * skipped.
-   *
-   * This function only skips over one function type syntax.
-   * If necessary, this function must be called multiple times.
-   *
-   * Example:
-   * ```
-   * int Function() Function<T>(int)
-   *             ^          ^
-   * A call to this function must be either at `(` or at `<`.
-   * If `token` pointed to the first `(`, then the returned
-   * token points to the second `Function` token.
-   */
+  /// Returns the first token after the function type starting at [token].
+  ///
+  /// The token must be at the token *after* the `Function` token
+  /// position. That is, the return type and the `Function` token must have
+  /// already been skipped.
+  ///
+  /// This function only skips over one function type syntax.  If necessary,
+  /// this function must be called multiple times.
+  ///
+  /// Example:
+  ///
+  ///     int Function() Function<T>(int)
+  ///                 ^          ^
+  ///
+  /// A call to this function must be either at `(` or at `<`.  If `token`
+  /// pointed to the first `(`, then the returned token points to the second
+  /// `Function` token.
   Token peekAfterFunctionType(Token token) {
     // Possible inputs are:
     //    ( ... )
     //    < ... >( ... )
 
     Token peek = token;
     // If there is a generic argument to the function, skip over that one first.
     if (identical(peek.kind, LT_TOKEN)) {
       BeginGroupToken beginGroupToken = peek;
       Token closeToken = beginGroupToken.endGroup;
       if (closeToken != null) {
         peek = closeToken.next;
       }
     }
 
     // Now we just need to skip over the formals.
     expect('(', peek);
 
     BeginGroupToken beginGroupToken = peek;
     Token closeToken = beginGroupToken.endGroup;
     if (closeToken != null) {
       peek = closeToken.next;
     }
 
     return peek;
   }
 
-  /**
-   * If [token] is the start of a type, returns the token after that type.
-   * If [token] is not the start of a type, null is returned.
-   */
+  /// If [token] is the start of a type, returns the token after that type.
+  /// If [token] is not the start of a type, null is returned.
   Token peekAfterIfType(Token token) {
     if (!optional('void', token) && !token.isIdentifier()) {
       return null;
     }
     return peekAfterType(token);
   }
 
   Token skipClassBody(Token token) {
     if (!optional('{', token)) {
       return reportUnrecoverableError(token, ErrorKind.ExpectedClassBodyToSkip)
@@ skipping 1400 matching lines @@
       while (identical(token.stringValue, '.')) {
         count++;
         token = parseIdentifier(
             token.next, IdentifierContext.literalSymbolContinuation);
       }
       listener.endLiteralSymbol(hashToken, count);
       return token;
     }
   }
 
-  /**
-   * Only called when [:token.kind === STRING_TOKEN:].
-   */
+  /// Only called when `identical(token.kind, STRING_TOKEN)`.
   Token parseSingleLiteralString(Token token) {
     listener.beginLiteralString(token);
     // Parsing the prefix, for instance 'x of 'x${id}y${id}z'
     token = token.next;
     int interpolationCount = 0;
     var kind = token.kind;
     while (kind != EOF_TOKEN) {
       if (identical(kind, STRING_INTERPOLATION_TOKEN)) {
         // Parsing ${expression}.
         token = token.next;
@@ skipping 395 matching lines @@
         break;
       }
       token = parseSwitchCase(token);
       ++caseCount;
     }
     listener.endSwitchBlock(caseCount, begin, token);
     expect('}', token);
     return token;
   }
 
-  /**
-   * Peek after the following labels (if any). The following token
-   * is used to determine if the labels belong to a statement or a
-   * switch case.
-   */
+  /// Peek after the following labels (if any). The following token
+  /// is used to determine if the labels belong to a statement or a
+  /// switch case.
   Token peekPastLabels(Token token) {
     while (token.isIdentifier() && optional(':', token.next)) {
       token = token.next.next;
     }
     return token;
   }
 
-  /**
-   * Parse a group of labels, cases and possibly a default keyword and
-   * the statements that they select.
-   */
+  /// Parse a group of labels, cases and possibly a default keyword and the
+  /// statements that they select.
   Token parseSwitchCase(Token token) {
     Token begin = token;
     Token defaultKeyword = null;
     int expressionCount = 0;
     int labelCount = 0;
     Token peek = peekPastLabels(token);
     while (true) {
       // Loop until we find something that can't be part of a switch case.
       String value = peek.stringValue;
       if (identical(value, 'default')) {
@@ skipping 157 matching lines @@
         break;
     }
     if (isRecoverable) {
       listener.handleRecoverableError(token, kind, arguments);
       return null;
     } else {
       return listener.handleUnrecoverableError(token, kind, arguments);
     }
   }
 }