Fix comment references in shared parser and scanner.

Fix bracketed references in doc comments that previously pointed to
nowhere, in the shared parser
(pkg/_fe_analyzer_shared/lib/src/parser/...) and scanner
(pkg/_fe_analyzer_shared/lib/src/scanner/...).

This is part of a larger effort to clean up _fe_analyzer_shared to the
point where the `comment_references` lint can be enabled.

Change-Id: I60c402d9b4df50208ed51587e71a0663e369d622
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/375221
Reviewed-by: Johnni Winther <[email protected]>
Commit-Queue: Paul Berry <[email protected]>

Author: stereotype441

pkg/_fe_analyzer_shared/lib/src/parser/class_member_parser.dart

@@ -2,6 +2,7 @@
 // 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.
 
+/// @docImport 'top_level_parser.dart';
 library _fe_analyzer_shared.parser.class_member_parser;
 
 import '../scanner/token.dart' show Token;

pkg/_fe_analyzer_shared/lib/src/parser/identifier_context.dart

@@ -321,15 +321,15 @@ abstract class IdentifierContext {
   /// Ensure that the next token is an identifier (or keyword which should be
   /// treated as an identifier) and return that identifier.
   /// Report errors as necessary via [parser].
-  /// If [recovered] implementers could allow 'token' to be used as an
+  /// If [isRecovered] implementers could allow 'token' to be used as an
   /// identifier, even if it isn't a valid identifier.
   Token ensureIdentifierPotentiallyRecovered(
           Token token, Parser parser, bool isRecovered) =>
       ensureIdentifier(token, parser);
 }
 
-/// Return `true` if the given [token] should be treated like the start of
-/// an expression for the purposes of recovery.
+/// Return `true` if [next] should be treated like the start of an expression
+/// for the purposes of recovery.
 bool looksLikeExpressionStart(Token next) =>
     next.isIdentifier ||
     next.isKeyword && !looksLikeStatementStart(next) ||
@@ -353,8 +353,8 @@ bool looksLikeExpressionStart(Token next) =>
     optional('++', next) ||
     optional('--', next);
 
-/// Returns `true` if the given [token] should be treated like the start of a
-/// pattern for the purposes of recovery.
+/// Returns `true` if [next] should be treated like the start of a pattern for
+/// the purposes of recovery.
 ///
 /// Note: since the syntax for patterns is very similar to that for expressions,
 /// we mostly re-use [looksLikeExpressionStart].

pkg/_fe_analyzer_shared/lib/src/parser/listener.dart

@@ -2,6 +2,7 @@
 // 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.
 
+/// @docImport 'parser_impl.dart';
 library _fe_analyzer_shared.parser.listener;
 
 import '../experiments/errors.dart';
@@ -315,7 +316,7 @@ class Listener implements UnescapeErrorListener {
   /// This method exists for analyzer compatibility only
   /// and will be removed once analyzer/fasta integration is complete.
   ///
-  /// This is called when [parseDirectives] has parsed all directives
+  /// This is called when [Parser.parseDirectives] has parsed all directives
   /// and is skipping the remainder of the file.  Substructures:
   /// - metadata
   void handleDirectivesOnly() {}

pkg/_fe_analyzer_shared/lib/src/parser/parser_impl.dart

@@ -2,6 +2,8 @@
 // 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.
 
+/// @docImport '../scanner/scanner.dart';
+/// @docImport 'util.dart';
 library _fe_analyzer_shared.parser.parser;
 
 import '../experiments/flags.dart';
@@ -181,9 +183,9 @@ import 'util.dart'
 /// 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 [expect] to recognize
-/// keywords or identifiers. In some cases, it's possible to compare a token's
-/// `stringValue` using [identical], but normally [optional] will suffice.
+/// parser. One should favor the method [optional] 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 objects
 /// other than strings, it can often be replaced by `==`.
@@ -229,7 +231,7 @@ import 'util.dart'
 ///
 /// When attempting to parse this function, the parser eventually calls
 /// [parseFunctionBody]. This method will report an unrecoverable error to the
-/// listener with the code [fasta.messageExpectedFunctionBody]. The listener can
+/// listener with the code [codes.codeExpectedFunctionBody]. The listener can
 /// then look at the error code and the token and use the methods in
 /// [native_support.dart](native_support.dart) to parse the native syntax.
 ///
@@ -4191,11 +4193,10 @@ class Parser {
     return token;
   }
 
-  /// If the next token is an opening curly brace, return it. Otherwise, use the
-  /// given [template] or [missingBlockName] to report an error, insert an
-  /// opening and a closing curly brace, and return the newly inserted opening
-  /// curly brace. If  [template] and [missingBlockName] are `null`, then use
-  /// a default error message instead.
+  /// If the next token is an opening curly brace, return it. Otherwise, use
+  /// [missingBlockKind] to report an error, insert an opening and a closing
+  /// curly brace, and return the newly inserted opening curly brace. If
+  /// [missingBlockKind] is `null`, then use a default error message instead.
   Token ensureBlock(Token token, BlockKind? missingBlockKind) {
     Token next = token.next!;
     if (optional('{', next)) return next;
@@ -5251,9 +5252,9 @@ class Parser {
         beforeName, start.next!, formals, /* isFunctionExpression = */ true);
   }
 
-  /// Parses the rest of a named function declaration starting from its [name]
-  /// but then skips any type parameters and continue parsing from [formals]
-  /// (the formal parameters).
+  /// Parses the rest of a named function declaration starting from its name
+  /// (the token following [beforeName]) but then skips any type parameters and
+  /// continue parsing from [formals] (the formal parameters).
   ///
   /// If [isFunctionExpression] is true, this method parses the rest of named
   /// function expression which isn't legal syntax in Dart.  Useful for
@@ -6143,7 +6144,7 @@ class Parser {
     return token;
   }
 
-  /// Attempt a recovery where [token.next] is replaced.
+  /// Attempt a recovery where [token].next is replaced.
   bool _attemptPrecedenceLevelRecovery(Token token, int precedence,
       int currentLevel, bool allowCascades, TypeParamOrArgInfo typeArg) {
     // Attempt recovery.
@@ -7983,7 +7984,7 @@ class Parser {
     return parseExpressionStatementOrDeclaration(start);
   }
 
-  /// This method has two modes based upon [onlyParseVariableDeclarationStart].
+  /// This method has two modes based upon [forPartsContext].
   ///
   /// If [forPartsContext] is `null` (the default), then the parser is currently
   /// processing a statement or declaration.  This method will parse a local

pkg/_fe_analyzer_shared/lib/src/parser/stack_listener.dart

@@ -422,16 +422,16 @@ abstract class StackListener extends Listener with StackChecker {
 
 abstract class Stack {
   /// Pops [count] elements from the stack and puts it into [list].
-  /// Returns [null] if a [ParserRecovery] value is found, or [list] otherwise.
+  /// Returns `null` if a [ParserRecovery] value is found, or [list] otherwise.
   List<T?>? popList<T>(int count, List<T?> list, NullValue? nullValue);
 
   /// Pops [count] elements from the stack and puts it into [list].
-  /// Returns [null] if a [ParserRecovery] value is found, or [list] otherwise.
+  /// Returns `null` if a [ParserRecovery] value is found, or [list] otherwise.
   List<T>? popNonNullableList<T>(int count, List<T> list);
 
   void push(Object value);
 
-  /// Will return [null] instead of [NullValue].
+  /// Will return `null` instead of [NullValue].
   Object? get last;
 
   bool get isNotEmpty;
@@ -442,7 +442,7 @@ abstract class Stack {
 
   int get length;
 
-  /// Raw, i.e. [NullValue]s will be returned instead of [null].
+  /// Raw, i.e. [NullValue]s will be returned instead of `null`.
   Object? operator [](int index);
 }
 

pkg/_fe_analyzer_shared/lib/src/parser/token_stream_rewriter.dart

@@ -24,7 +24,7 @@ abstract class TokenStreamRewriter {
   }
 
   /// Insert a synthetic open and close parenthesis and return the new synthetic
-  /// open parenthesis. If [insertIdentifier] is true, then a synthetic
+  /// open parenthesis. If [includeIdentifier] is true, then a synthetic
   /// identifier is included between the open and close parenthesis.
   Token insertParens(Token token, bool includeIdentifier) {
     // Throw if the token is eof, though allow an eof-token if the offset

pkg/_fe_analyzer_shared/lib/src/parser/top_level_parser.dart

@@ -2,6 +2,7 @@
 // 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.
 
+/// @docImport 'parser_impl.dart';
 library _fe_analyzer_shared.parser.top_level_parser;
 
 import '../scanner/token.dart' show Token;

pkg/_fe_analyzer_shared/lib/src/scanner/abstract_scanner.dart

@@ -2,6 +2,9 @@
 // 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.
 
+/// @docImport 'string_scanner.dart';
+/// @docImport 'utf8_bytes_scanner.dart';
+/// @docImport '../parser/class_member_parser.dart';
 library _fe_analyzer_shared.scanner.abstract_scanner;
 
 import 'dart:collection' show ListMixin;
@@ -660,7 +663,7 @@ abstract class AbstractScanner implements Scanner {
   /**
    * This method is called to discard '<' from the "grouping" stack.
    *
-   * [PartialParser.skipExpression] relies on the fact that we do not
+   * [ClassMemberParser.skipExpression] relies on the fact that we do not
    * create groups for stuff like:
    * [:a = b < c, d = e > f:].
    *

pkg/_fe_analyzer_shared/lib/src/scanner/token.dart

@@ -998,7 +998,7 @@ abstract class Token implements SyntacticEntity {
    * For symbol and keyword tokens, returns the string value represented by this
    * token. For [StringToken]s this method returns [:null:].
    *
-   * For [SymbolToken]s and [KeywordToken]s, the string value is a compile-time
+   * For symbol [Token]s and [KeywordToken]s, the string value is a compile-time
    * constant originating in the [TokenType] or in the [Keyword] instance.
    * This allows testing for keywords and symbols using [:identical:], e.g.,
    * [:identical('class', token.value):].

pkg/_fe_analyzer_shared/lib/src/scanner/utf8_bytes_scanner.dart

@@ -2,6 +2,7 @@
 // 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.
 
+/// @docImport 'package:compiler/src/io/source_file.dart';
 library _fe_analyzer_shared.scanner.utf8_bytes_scanner;
 
 import 'dart:typed_data' show Uint8List;