Use ///-style doc comments in analyzer/test

Bug: #33892
Change-Id: If61e07fda4d74b1e5171d22403b156855cd00596
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/152701
Reviewed-by: Paul Berry <[email protected]>
Reviewed-by: Konstantin Shcheglov <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>

pkg/analyzer/test/dart/ast/ast_test.dart

@@ -1053,12 +1053,11 @@ class SimpleIdentifierTest extends ParserTestCase {
     return identifier;
   }
 
-  /**
-   * Return the top-most node in the AST structure containing the given identifier.
-   *
-   * @param identifier the identifier in the AST structure being traversed
-   * @return the root of the AST structure containing the identifier
-   */
+  /// Return the top-most node in the AST structure containing the given
+  /// identifier.
+  ///
+  /// @param identifier the identifier in the AST structure being traversed
+  /// @return the root of the AST structure containing the identifier
   AstNode _topMostNode(SimpleIdentifier identifier) {
     AstNode child = identifier;
     AstNode parent = identifier.parent;

pkg/analyzer/test/dart/ast/visitor_test.dart

@@ -52,10 +52,8 @@ A f(var p) {
   }
 }
 
-/**
- * A helper class used to collect the nodes that were visited and to preserve
- * the order in which they were visited.
- */
+/// A helper class used to collect the nodes that were visited and to preserve
+/// the order in which they were visited.
 class _BreadthFirstVisitorTestHelper extends BreadthFirstVisitor<void> {
   List<AstNode> nodes;
 

pkg/analyzer/test/file_system/file_system_test_support.dart

@@ -617,9 +617,7 @@ mixin FolderTestMixin implements FileSystemTestSupport {
     expect(folder.toUri(), Uri.directory(defaultFolderPath));
   }
 
-  /**
-   * Verify that the [copy] has the same name and content as the [source].
-   */
+  /// Verify that the [copy] has the same name and content as the [source].
   void _verifyStructure(Folder copy, Folder source) {
     expect(copy.shortName, source.shortName);
     Map<String, File> sourceFiles = <String, File>{};

pkg/analyzer/test/file_system/overlay_file_system_test.dart

@@ -631,9 +631,7 @@ class FolderTest extends OverlayTestSupport {
     expect(folder.resolveSymbolicLinksSync(), folder);
   }
 
-  /**
-   * Verify that the [copy] has the same name and content as the [source].
-   */
+  /// Verify that the [copy] has the same name and content as the [source].
   void _verifyStructure(Folder copy, Folder source) {
     expect(copy.shortName, source.shortName);
     Map<String, File> sourceFiles = <String, File>{};

pkg/analyzer/test/generated/element_resolver_test.dart

@@ -297,29 +297,19 @@ class C {}
 
 @reflectiveTest
 class ElementResolverTest with ResourceProviderMixin, ElementsTypesMixin {
-  /**
-   * The error listener to which errors will be reported.
-   */
+  /// The error listener to which errors will be reported.
   GatheringErrorListener _listener;
 
-  /**
-   * The type provider used to access the types.
-   */
+  /// The type provider used to access the types.
   TypeProvider _typeProvider;
 
-  /**
-   * The library containing the code being resolved.
-   */
+  /// The library containing the code being resolved.
   LibraryElementImpl _definingLibrary;
 
-  /**
-   * The resolver visitor that maintains the state for the resolver.
-   */
+  /// The resolver visitor that maintains the state for the resolver.
   ResolverVisitor _visitor;
 
-  /**
-   * The resolver being used to resolve the test cases.
-   */
+  /// The resolver being used to resolve the test cases.
   ElementResolver _resolver;
 
   @override
@@ -960,9 +950,7 @@ class ElementResolverTest with ResourceProviderMixin, ElementsTypesMixin {
     _listener.assertNoErrors();
   }
 
-  /**
-   * Create and return the resolver used by the tests.
-   */
+  /// Create and return the resolver used by the tests.
   void _createResolver() {
     var context = TestAnalysisContext();
     _typeProvider = context.typeProviderLegacy;
@@ -991,56 +979,50 @@ class ElementResolverTest with ResourceProviderMixin, ElementsTypesMixin {
     }
   }
 
-  /**
-   * Return the element associated with the label of [statement] after the
-   * resolver has resolved it.  [labelElement] is the label element to be
-   * defined in the statement's label scope, and [labelTarget] is the statement
-   * the label resolves to.
-   */
+  /// Return the element associated with the label of [statement] after the
+  /// resolver has resolved it.  [labelElement] is the label element to be
+  /// defined in the statement's label scope, and [labelTarget] is the statement
+  /// the label resolves to.
   Element _resolveBreak(BreakStatement statement, LabelElementImpl labelElement,
       Statement labelTarget) {
     _resolveStatement(statement, labelElement, labelTarget);
     return statement.label.staticElement;
   }
 
-  /**
-   * Return the element associated with the label [statement] after the
-   * resolver has resolved it.  [labelElement] is the label element to be
-   * defined in the statement's label scope, and [labelTarget] is the AST node
-   * the label resolves to.
-   *
-   * @param statement the statement to be resolved
-   * @param labelElement the label element to be defined in the statement's label scope
-   * @return the element to which the statement's label was resolved
-   */
+  /// Return the element associated with the label [statement] after the
+  /// resolver has resolved it.  [labelElement] is the label element to be
+  /// defined in the statement's label scope, and [labelTarget] is the AST node
+  /// the label resolves to.
+  ///
+  /// @param statement the statement to be resolved
+  /// @param labelElement the label element to be defined in the statement's
+  ///          label scope
+  /// @return the element to which the statement's label was resolved
   Element _resolveContinue(ContinueStatement statement,
       LabelElementImpl labelElement, AstNode labelTarget) {
     _resolveStatement(statement, labelElement, labelTarget);
     return statement.label.staticElement;
   }
 
-  /**
-   * Return the element associated with the given identifier after the resolver has resolved the
-   * identifier.
-   *
-   * @param node the expression to be resolved
-   * @param definedElements the elements that are to be defined in the scope in which the element is
-   *          being resolved
-   * @return the element to which the expression was resolved
-   */
+  /// Return the element associated with the given identifier after the resolver
+  /// has resolved the identifier.
+  ///
+  /// @param node the expression to be resolved
+  /// @param definedElements the elements that are to be defined in the scope in
+  ///          which the element is being resolved
+  /// @return the element to which the expression was resolved
   Element _resolveIdentifier(Identifier node, [List<Element> definedElements]) {
     _resolveNode(node, definedElements);
     return node.staticElement;
   }
 
-  /**
-   * Return the element associated with the given identifier after the resolver has resolved the
-   * identifier.
-   *
-   * @param node the expression to be resolved
-   * @param enclosingClass the element representing the class enclosing the identifier
-   * @return the element to which the expression was resolved
-   */
+  /// Return the element associated with the given identifier after the resolver
+  /// has resolved the identifier.
+  ///
+  /// @param node the expression to be resolved
+  /// @param enclosingClass the element representing the class enclosing the
+  ///          identifier
+  /// @return the element to which the expression was resolved
   void _resolveInClass(AstNode node, ClassElement enclosingClass) {
     Scope outerScope = _visitor.nameScope;
     try {
@@ -1055,30 +1037,26 @@ class ElementResolverTest with ResourceProviderMixin, ElementsTypesMixin {
     }
   }
 
-  /**
-   * Return the element associated with the given expression after the resolver has resolved the
-   * expression.
-   *
-   * @param node the expression to be resolved
-   * @param definedElements the elements that are to be defined in the scope in which the element is
-   *          being resolved
-   * @return the element to which the expression was resolved
-   */
+  /// Return the element associated with the given expression after the resolver
+  /// has resolved the expression.
+  ///
+  /// @param node the expression to be resolved
+  /// @param definedElements the elements that are to be defined in the scope in
+  ///          which the element is being resolved
+  /// @return the element to which the expression was resolved
   Element _resolveIndexExpression(IndexExpression node,
       [List<Element> definedElements]) {
     _resolveNode(node, definedElements);
     return node.staticElement;
   }
 
-  /**
-   * Return the element associated with the given identifier after the resolver has resolved the
-   * identifier.
-   *
-   * @param node the expression to be resolved
-   * @param definedElements the elements that are to be defined in the scope in which the element is
-   *          being resolved
-   * @return the element to which the expression was resolved
-   */
+  /// Return the element associated with the given identifier after the resolver
+  /// has resolved the identifier.
+  ///
+  /// @param node the expression to be resolved
+  /// @param definedElements the elements that are to be defined in the scope in
+  ///          which the element is being resolved
+  /// @return the element to which the expression was resolved
   void _resolveNode(AstNode node, [List<Element> definedElements]) {
     Scope outerScope = _visitor.nameScope;
     try {
@@ -1095,14 +1073,13 @@ class ElementResolverTest with ResourceProviderMixin, ElementsTypesMixin {
     }
   }
 
-  /**
-   * Return the element associated with the label of the given statement after the resolver has
-   * resolved the statement.
-   *
-   * @param statement the statement to be resolved
-   * @param labelElement the label element to be defined in the statement's label scope
-   * @return the element to which the statement's label was resolved
-   */
+  /// Return the element associated with the label of the given statement after
+  /// the resolver has resolved the statement.
+  ///
+  /// @param statement the statement to be resolved
+  /// @param labelElement the label element to be defined in the statement's
+  ///          label scope
+  /// @return the element to which the statement's label was resolved
   void _resolveStatement(
       Statement statement, LabelElementImpl labelElement, AstNode labelTarget) {
     LabelScope outerScope = _visitor.labelScope;

pkg/analyzer/test/generated/parser_fasta_listener.dart

@@ -8,27 +8,25 @@ import 'package:_fe_analyzer_shared/src/parser/parser.dart';
 import 'package:_fe_analyzer_shared/src/scanner/token.dart';
 import 'package:test/test.dart';
 
-/**
- * Proxy implementation of the fasta parser listener that
- * asserts begin/end pairs of events and forwards all events
- * to the specified listener.
- *
- * When `parseUnit` is called, then all events are generated as expected.
- * When "lower level" parse methods are called, then some "higher level"
- * begin/end event pairs will not be generated. In this case,
- * construct a new listener and call `begin('higher-level-event')`
- * before calling the "lower level" parse method. Once the parse method returns,
- * call `end('higher-level-event')` to assert that the stack is in the
- * expected state.
- *
- * For example, when calling `parseTopLevelDeclaration`, the
- * [beginCompilationUnit] and [endCompilationUnit] event pair is not generated.
- * In this case, call `begin('CompilationUnit')` before calling
- * `parseTopLevelDeclaration`, and call `end('CompilationUnit')` afterward.
- *
- * When calling `parseUnit`, do not call `begin` or `end`,
- * but call `expectEmpty` after `parseUnit` returns.
- */
+/// Proxy implementation of the fasta parser listener that
+/// asserts begin/end pairs of events and forwards all events
+/// to the specified listener.
+///
+/// When `parseUnit` is called, then all events are generated as expected.
+/// When "lower level" parse methods are called, then some "higher level"
+/// begin/end event pairs will not be generated. In this case,
+/// construct a new listener and call `begin('higher-level-event')`
+/// before calling the "lower level" parse method. Once the parse method
+/// returns, call `end('higher-level-event')` to assert that the stack is in the
+/// expected state.
+///
+/// For example, when calling `parseTopLevelDeclaration`, the
+/// [beginCompilationUnit] and [endCompilationUnit] event pair is not generated.
+/// In this case, call `begin('CompilationUnit')` before calling
+/// `parseTopLevelDeclaration`, and call `end('CompilationUnit')` afterward.
+///
+/// When calling `parseUnit`, do not call `begin` or `end`,
+/// but call `expectEmpty` after `parseUnit` returns.
 class ForwardingTestListener extends ForwardingListener {
   final _stack = <String>[];