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

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

pkg/analyzer/tool/experiments/experiments_test.dart

@@ -9,10 +9,8 @@ import 'package:path/path.dart';
 
 import 'generate.dart';
 
-/**
- * Check that all targets have been code generated.  If they haven't tell the
- * user to run generate_all.dart.
- */
+/// Check that all targets have been code generated.  If they haven't tell the
+/// user to run generate_all.dart.
 main() async {
   String script = Platform.script.toFilePath(windows: Platform.isWindows);
   List<String> components = split(script);

pkg/analyzer/tool/experiments/generate.dart

@@ -1,7 +1,5 @@
-/**
- * This file contains code to generate experimental flags
- * based on the information in tools/experimental_features.yaml.
- */
+/// This file contains code to generate experimental flags
+/// based on the information in tools/experimental_features.yaml.
 import 'dart:io';
 
 import 'package:_fe_analyzer_shared/src/scanner/characters.dart'

pkg/analyzer/tool/messages/generate.dart

@@ -1,17 +1,15 @@
-/**
- * This file contains code to generate scanner and parser message
- * based on the information in pkg/front_end/messages.yaml.
- *
- * For each message in messages.yaml that contains an 'index:' field,
- * this tool generates an error with the name specified by the 'analyzerCode:'
- * field and an entry in the fastaAnalyzerErrorList for that generated error.
- * The text in the 'analyzerCode:' field must contain the name of the class
- * containing the error and the name of the error separated by a `.`
- * (e.g. ParserErrorCode.EQUALITY_CANNOT_BE_EQUALITY_OPERAND).
- *
- * It is expected that 'pkg/front_end/tool/fasta generate-messages'
- * has already been successfully run.
- */
+/// This file contains code to generate scanner and parser message
+/// based on the information in pkg/front_end/messages.yaml.
+///
+/// For each message in messages.yaml that contains an 'index:' field,
+/// this tool generates an error with the name specified by the 'analyzerCode:'
+/// field and an entry in the fastaAnalyzerErrorList for that generated error.
+/// The text in the 'analyzerCode:' field must contain the name of the class
+/// containing the error and the name of the error separated by a `.`
+/// (e.g. ParserErrorCode.EQUALITY_CANNOT_BE_EQUALITY_OPERAND).
+///
+/// It is expected that 'pkg/front_end/tool/fasta generate-messages'
+/// has already been successfully run.
 import 'dart:io';
 
 import 'package:_fe_analyzer_shared/src/scanner/scanner.dart';

pkg/analyzer/tool/summary/build_sdk_summaries.dart

@@ -48,9 +48,7 @@ void main(List<String> args) {
   }
 }
 
-/**
- * The name of the SDK summaries builder application.
- */
+/// The name of the SDK summaries builder application.
 const BINARY_NAME = "build_sdk_summaries";
 
 void _buildSummary(String sdkPath, String outPath) {
@@ -64,9 +62,7 @@ void _buildSummary(String sdkPath, String outPath) {
   print('\tDone in ${sw.elapsedMilliseconds} ms.');
 }
 
-/**
- * Print information about how to use the SDK summaries builder.
- */
+/// Print information about how to use the SDK summaries builder.
 void _printUsage() {
   print('Usage: $BINARY_NAME command arguments');
   print('Where command can be one of the following:');

pkg/analyzer/tool/summary/check_test.dart

@@ -8,10 +8,8 @@ import 'package:path/path.dart';
 import '../../test/utils/package_root.dart' as package_root;
 import 'generate.dart';
 
-/**
- * Check that the target file has been code generated.  If it hasn't tell the
- * user to run generate.dart.
- */
+/// Check that the target file has been code generated.  If it hasn't tell the
+/// user to run generate.dart.
 main() async {
   var idlFolderPath = normalize(
       join(package_root.packageRoot, 'analyzer', 'lib', 'src', 'summary'));

pkg/analyzer/tool/summary/idl_model.dart

@@ -2,36 +2,24 @@
 // 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.
 
-/**
- * This file contains a set of concrete classes representing an in-memory
- * semantic model of the IDL used to code generate summary serialization and
- * deserialization code.
- */
+/// This file contains a set of concrete classes representing an in-memory
+/// semantic model of the IDL used to code generate summary serialization and
+/// deserialization code.
 import 'package:meta/meta.dart';
 
-/**
- * Information about a single class defined in the IDL.
- */
+/// Information about a single class defined in the IDL.
 class ClassDeclaration extends Declaration {
-  /**
-   * All fields defined in the class, including deprecated ones.
-   */
+  /// All fields defined in the class, including deprecated ones.
   final List<FieldDeclaration> allFields = <FieldDeclaration>[];
 
-  /**
-   * Indicates whether the class has the `topLevel` annotation.
-   */
+  /// Indicates whether the class has the `topLevel` annotation.
   final bool isTopLevel;
 
-  /**
-   * If [isTopLevel] is `true` and a file identifier was specified for this
-   * class, the file identifier string.  Otherwise `null`.
-   */
+  /// If [isTopLevel] is `true` and a file identifier was specified for this
+  /// class, the file identifier string.  Otherwise `null`.
   final String fileIdentifier;
 
-  /**
-   * Indicates whether the class has the `deprecated` annotation.
-   */
+  /// Indicates whether the class has the `deprecated` annotation.
   final bool isDeprecated;
 
   final String variantField;
@@ -45,78 +33,52 @@ class ClassDeclaration extends Declaration {
     @required this.variantField,
   }) : super(documentation, name);
 
-  /**
-   * Get the non-deprecated fields defined in the class.
-   */
+  /// Get the non-deprecated fields defined in the class.
   Iterable<FieldDeclaration> get fields =>
       allFields.where((FieldDeclaration field) => !field.isDeprecated);
 }
 
-/**
- * Information about a declaration in the IDL.
- */
+/// Information about a declaration in the IDL.
 class Declaration {
-  /**
-   * The optional documentation, may be `null`.
-   */
+  /// The optional documentation, may be `null`.
   final String documentation;
 
-  /**
-   * The name of the declaration.
-   */
+  /// The name of the declaration.
   final String name;
 
   Declaration(this.documentation, this.name);
 }
 
-/**
- * Information about a single enum defined in the IDL.
- */
+/// Information about a single enum defined in the IDL.
 class EnumDeclaration extends Declaration {
-  /**
-   * List of enumerated values.
-   */
+  /// List of enumerated values.
   final List<EnumValueDeclaration> values = <EnumValueDeclaration>[];
 
   EnumDeclaration(String documentation, String name)
       : super(documentation, name);
 }
 
-/**
- * Information about a single enum value defined in the IDL.
- */
+/// Information about a single enum value defined in the IDL.
 class EnumValueDeclaration extends Declaration {
   EnumValueDeclaration(String documentation, String name)
       : super(documentation, name);
 }
 
-/**
- * Information about a single class field defined in the IDL.
- */
+/// Information about a single class field defined in the IDL.
 class FieldDeclaration extends Declaration {
-  /**
-   * The file of the field.
-   */
+  /// The file of the field.
   final FieldType type;
 
-  /**
-   * The id of the field.
-   */
+  /// The id of the field.
   final int id;
 
-  /**
-   * Indicates whether the field is deprecated.
-   */
+  /// Indicates whether the field is deprecated.
   final bool isDeprecated;
 
-  /**
-   * Indicates whether the field is informative.
-   */
+  /// Indicates whether the field is informative.
   final bool isInformative;
 
-  /**
-   * Maps logical property names to logical property.
-   */
+  /// Maps logical property names to logical property.
   final Map<String, LogicalProperty> logicalProperties;
 
   FieldDeclaration({
@@ -130,19 +92,13 @@ class FieldDeclaration extends Declaration {
   }) : super(documentation, name);
 }
 
-/**
- * Information about the type of a class field defined in the IDL.
- */
+/// Information about the type of a class field defined in the IDL.
 class FieldType {
-  /**
-   * Type of the field (e.g. 'int').
-   */
+  /// Type of the field (e.g. 'int').
   final String typeName;
 
-  /**
-   * Indicates whether this field contains a list of the type specified in
-   * [typeName].
-   */
+  /// Indicates whether this field contains a list of the type specified in
+  /// [typeName].
   final bool isList;
 
   FieldType(this.typeName, this.isList);
@@ -166,38 +122,24 @@ class FieldType {
   String toString() => isList ? 'List<$typeName>' : typeName;
 }
 
-/**
- * Top level representation of the summary IDL.
- */
+/// Top level representation of the summary IDL.
 class Idl {
-  /**
-   * Classes defined in the IDL.
-   */
+  /// Classes defined in the IDL.
   final Map<String, ClassDeclaration> classes = <String, ClassDeclaration>{};
 
-  /**
-   * Enums defined in the IDL.
-   */
+  /// Enums defined in the IDL.
   final Map<String, EnumDeclaration> enums = <String, EnumDeclaration>{};
 }
 
-/**
- * Information about a logical property mapped to a single data fields.
- */
+/// Information about a logical property mapped to a single data fields.
 class LogicalProperty {
-  /**
-   * Indicates whether the property is deprecated.
-   */
+  /// Indicates whether the property is deprecated.
   final bool isDeprecated;
 
-  /**
-   * Indicates whether the property is informative.
-   */
+  /// Indicates whether the property is informative.
   final bool isInformative;
 
-  /**
-   * Names of variants in which this property is available.
-   */
+  /// Names of variants in which this property is available.
   final List<String> variants;
 
   LogicalProperty({

pkg/analyzer/tool/summary/stats.dart

@@ -2,10 +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.
 
-/**
- * This file contains code for collecting statistics about the use of fields in
- * a summary file.
- */
+/// This file contains code for collecting statistics about the use of fields in
+/// a summary file.
 import 'dart:io';
 import 'dart:mirrors';
 
@@ -31,31 +29,21 @@ main(List<String> args) {
   stats.dump();
 }
 
-/**
- * The name of the stats tool.
- */
+/// The name of the stats tool.
 const String BINARY_NAME = "stats";
 
-/**
- * Print information about how to use the stats tool.
- */
+/// Print information about how to use the stats tool.
 void _printUsage() {
   print('Usage: $BINARY_NAME input_file_path');
 }
 
-/**
- * An instance of [Stats] keeps track of statistics about the use of fields in
- * summary objects.
- */
+/// An instance of [Stats] keeps track of statistics about the use of fields in
+/// summary objects.
 class Stats {
-  /**
-   * Map from type to field name to a count of how often the field is used.
-   */
+  /// Map from type to field name to a count of how often the field is used.
   Map<Type, Map<String, int>> counts = <Type, Map<String, int>>{};
 
-  /**
-   * Print out statistics gathered so far.
-   */
+  /// Print out statistics gathered so far.
   void dump() {
     counts.forEach((Type type, Map<String, int> typeCounts) {
       print(type);
@@ -68,9 +56,7 @@ class Stats {
     });
   }
 
-  /**
-   * Record statistics for [obj] and all objects it refers to.
-   */
+  /// Record statistics for [obj] and all objects it refers to.
   void record(SummaryClass obj) {
     Map<String, int> typeCounts =
         counts.putIfAbsent(obj.runtimeType, () => <String, int>{});