From a558d576b76f1f9dd80aaa93c71d1bd09eefd0fa Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Fri, 26 Jun 2020 18:46:25 +0000 Subject: [PATCH] Use ///-style doc comments in analyzer/tool Bug: https://github.com/dart-lang/sdk/issues/33892 Change-Id: I67094e84af2ec54ede00b248a2e67d3cebadc576 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/152702 Reviewed-by: Paul Berry Reviewed-by: Konstantin Shcheglov Commit-Queue: Samuel Rawlins --- .../tool/experiments/experiments_test.dart | 6 +- pkg/analyzer/tool/experiments/generate.dart | 6 +- pkg/analyzer/tool/messages/generate.dart | 26 ++-- .../tool/summary/build_sdk_summaries.dart | 8 +- pkg/analyzer/tool/summary/check_test.dart | 6 +- pkg/analyzer/tool/summary/idl_model.dart | 124 +++++------------- pkg/analyzer/tool/summary/stats.dart | 32 ++--- 7 files changed, 62 insertions(+), 146 deletions(-) diff --git a/pkg/analyzer/tool/experiments/experiments_test.dart b/pkg/analyzer/tool/experiments/experiments_test.dart index 167c033fc104..4f77ee3f3881 100644 --- a/pkg/analyzer/tool/experiments/experiments_test.dart +++ b/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 components = split(script); diff --git a/pkg/analyzer/tool/experiments/generate.dart b/pkg/analyzer/tool/experiments/generate.dart index 0ec1a0b8bcac..be73262c0d58 100644 --- a/pkg/analyzer/tool/experiments/generate.dart +++ b/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' diff --git a/pkg/analyzer/tool/messages/generate.dart b/pkg/analyzer/tool/messages/generate.dart index b38db34e9b5f..75fd2698d080 100644 --- a/pkg/analyzer/tool/messages/generate.dart +++ b/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'; diff --git a/pkg/analyzer/tool/summary/build_sdk_summaries.dart b/pkg/analyzer/tool/summary/build_sdk_summaries.dart index 5c0590b98ecf..1c9a82f0824e 100644 --- a/pkg/analyzer/tool/summary/build_sdk_summaries.dart +++ b/pkg/analyzer/tool/summary/build_sdk_summaries.dart @@ -48,9 +48,7 @@ void main(List 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:'); diff --git a/pkg/analyzer/tool/summary/check_test.dart b/pkg/analyzer/tool/summary/check_test.dart index 6c4e63511d21..e93bb335ed6c 100644 --- a/pkg/analyzer/tool/summary/check_test.dart +++ b/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')); diff --git a/pkg/analyzer/tool/summary/idl_model.dart b/pkg/analyzer/tool/summary/idl_model.dart index f90475c5c34f..968076068738 100644 --- a/pkg/analyzer/tool/summary/idl_model.dart +++ b/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 allFields = []; - /** - * 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 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 values = []; 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 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 classes = {}; - /** - * Enums defined in the IDL. - */ + /// Enums defined in the IDL. final Map enums = {}; } -/** - * 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 variants; LogicalProperty({ diff --git a/pkg/analyzer/tool/summary/stats.dart b/pkg/analyzer/tool/summary/stats.dart index 456fe74f615b..47f58b471f05 100644 --- a/pkg/analyzer/tool/summary/stats.dart +++ b/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 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> counts = >{}; - /** - * Print out statistics gathered so far. - */ + /// Print out statistics gathered so far. void dump() { counts.forEach((Type type, Map 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 typeCounts = counts.putIfAbsent(obj.runtimeType, () => {});