From 648b5e9c6860dca30a4111970ffe823435de7b94 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Fri, 26 Jun 2020 17:58:50 +0000 Subject: [PATCH] Use ///-style doc comments in analyzer/lib Bug: https://github.com/dart-lang/sdk/issues/33892 Change-Id: I573cb81dca6462c571bd6bf7bf309a46fd628967 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/152610 Reviewed-by: Paul Berry Reviewed-by: Konstantin Shcheglov Commit-Queue: Samuel Rawlins --- pkg/analyzer/lib/error/error.dart | 108 ++---- pkg/analyzer/lib/error/listener.dart | 162 +++------ pkg/analyzer/lib/exception/exception.dart | 79 ++-- pkg/analyzer/lib/file_system/file_system.dart | 287 ++++++--------- .../lib/file_system/memory_file_system.dart | 64 ++-- .../lib/file_system/overlay_file_system.dart | 159 +++----- .../lib/file_system/physical_file_system.dart | 80 ++--- pkg/analyzer/lib/source/line_info.dart | 66 ++-- pkg/analyzer/lib/source/source_range.dart | 79 ++-- .../analysis_options/error/option_codes.dart | 215 +++++------ .../lib/src/command_line/arguments.dart | 80 ++--- pkg/analyzer/lib/src/context/context.dart | 16 +- .../lib/src/context/context_root.dart | 46 +-- pkg/analyzer/lib/src/context/source.dart | 43 +-- .../src/error/bool_expression_verifier.dart | 11 +- .../error/duplicate_definition_verifier.dart | 4 +- .../src/error/type_arguments_verifier.dart | 22 +- .../lib/src/file_system/file_system.dart | 12 +- pkg/analyzer/lib/src/lint/config.dart | 18 +- .../lib/src/lint/options_rule_validator.dart | 50 +-- pkg/analyzer/lib/src/lint/registry.dart | 42 +-- .../lib/src/manifest/manifest_validator.dart | 34 +- .../src/manifest/manifest_warning_code.dart | 72 ++-- .../lib/src/pubspec/pubspec_validator.dart | 72 ++-- .../lib/src/pubspec/pubspec_warning_code.dart | 75 ++-- pkg/analyzer/lib/src/services/lint.dart | 4 +- .../lib/src/source/package_map_provider.dart | 40 +-- .../lib/src/source/package_map_resolver.dart | 34 +- .../lib/src/source/source_resource.dart | 66 ++-- pkg/analyzer/lib/src/string_source.dart | 14 +- .../lib/src/summary/api_signature.dart | 112 ++---- pkg/analyzer/lib/src/summary/base.dart | 90 ++--- .../lib/src/summary/flat_buffers.dart | 339 ++++++------------ pkg/analyzer/lib/src/summary/link.dart | 74 ++-- .../src/summary/package_bundle_reader.dart | 66 ++-- .../lib/src/summary/summarize_elements.dart | 10 +- .../lib/src/summary/summary_file_builder.dart | 12 +- pkg/analyzer/lib/src/summary/summary_sdk.dart | 18 +- pkg/analyzer/lib/src/task/api/model.dart | 24 +- pkg/analyzer/lib/src/task/options.dart | 5 +- pkg/analyzer/lib/src/task/strong_mode.dart | 101 ++---- .../resource_provider_mixin.dart | 8 +- pkg/analyzer/lib/src/util/asserts.dart | 8 +- pkg/analyzer/lib/src/util/glob.dart | 50 +-- pkg/analyzer/lib/src/util/lru_map.dart | 30 +- .../lib/src/util/utilities_timing.dart | 20 +- pkg/analyzer/lib/src/workspace/basic.dart | 40 +-- pkg/analyzer/lib/src/workspace/bazel.dart | 78 ++-- pkg/analyzer/lib/src/workspace/gn.dart | 90 ++--- .../lib/src/workspace/package_build.dart | 129 +++---- pkg/analyzer/lib/src/workspace/workspace.dart | 66 ++-- 51 files changed, 1200 insertions(+), 2224 deletions(-) diff --git a/pkg/analyzer/lib/error/error.dart b/pkg/analyzer/lib/error/error.dart index 3e905b12ecf5e..d675223ad99fd 100644 --- a/pkg/analyzer/lib/error/error.dart +++ b/pkg/analyzer/lib/error/error.dart @@ -844,16 +844,12 @@ const List errorCodeValues = [ TodoCode.TODO, ]; -/** - * The lazy initialized map from [ErrorCode.uniqueName] to the [ErrorCode] - * instance. - */ +/// The lazy initialized map from [ErrorCode.uniqueName] to the [ErrorCode] +/// instance. HashMap _uniqueNameToCodeMap; -/** - * Return the [ErrorCode] with the given [uniqueName], or `null` if not - * found. - */ +/// Return the [ErrorCode] with the given [uniqueName], or `null` if not +/// found. ErrorCode errorCodeByUniqueName(String uniqueName) { if (_uniqueNameToCodeMap == null) { _uniqueNameToCodeMap = HashMap(); @@ -864,29 +860,21 @@ ErrorCode errorCodeByUniqueName(String uniqueName) { return _uniqueNameToCodeMap[uniqueName]; } -/** - * An error discovered during the analysis of some Dart code. - * - * See [AnalysisErrorListener]. - */ +/// An error discovered during the analysis of some Dart code. +/// +/// See [AnalysisErrorListener]. class AnalysisError implements Diagnostic { - /** - * An empty array of errors used when no errors are expected. - */ + /// An empty array of errors used when no errors are expected. static const List NO_ERRORS = []; - /** - * A [Comparator] that sorts by the name of the file that the [AnalysisError] - * was found. - */ + /// A [Comparator] that sorts by the name of the file that the [AnalysisError] + /// was found. static Comparator FILE_COMPARATOR = (AnalysisError o1, AnalysisError o2) => o1.source.shortName.compareTo(o2.source.shortName); - /** - * A [Comparator] that sorts error codes first by their severity (errors - * first, warnings second), and then by the error code type. - */ + /// A [Comparator] that sorts error codes first by their severity (errors + /// first, warnings second), and then by the error code type. static Comparator ERROR_CODE_COMPARATOR = (AnalysisError o1, AnalysisError o2) { ErrorCode errorCode1 = o1.errorCode; @@ -902,40 +890,28 @@ class AnalysisError implements Diagnostic { } }; - /** - * The error code associated with the error. - */ + /// The error code associated with the error. final ErrorCode errorCode; - /** - * The message describing the problem. - */ + /// The message describing the problem. DiagnosticMessage _problemMessage; - /** - * The context messages associated with the problem. This list will be empty - * if there are no context messages. - */ + /// The context messages associated with the problem. This list will be empty + /// if there are no context messages. List _contextMessages; - /** - * The correction to be displayed for this error, or `null` if there is no - * correction information for this error. - */ + /// The correction to be displayed for this error, or `null` if there is no + /// correction information for this error. String _correction; - /** - * The source in which the error occurred, or `null` if unknown. - */ + /// The source in which the error occurred, or `null` if unknown. final Source source; - /** - * Initialize a newly created analysis error. The error is associated with the - * given [source] and is located at the given [offset] with the given - * [length]. The error will have the given [errorCode] and the list of - * [arguments] will be used to complete the message and correction. If any - * [contextMessages] are provided, they will be recorded with the error. - */ + /// Initialize a newly created analysis error. The error is associated with + /// the given [source] and is located at the given [offset] with the given + /// [length]. The error will have the given [errorCode] and the list of + /// [arguments] will be used to complete the message and correction. If any + /// [contextMessages] are provided, they will be recorded with the error. AnalysisError(this.source, int offset, int length, this.errorCode, [List arguments, List contextMessages = const []]) { @@ -952,9 +928,7 @@ class AnalysisError implements Diagnostic { _contextMessages = contextMessages; } - /** - * Initialize a newly created analysis error with given values. - */ + /// Initialize a newly created analysis error with given values. AnalysisError.forValues(this.source, int offset, int length, this.errorCode, String message, this._correction, {List contextMessages = const []}) { @@ -969,11 +943,9 @@ class AnalysisError implements Diagnostic { @override List get contextMessages => _contextMessages; - /** - * Return the template used to create the correction to be displayed for this - * error, or `null` if there is no correction information for this error. The - * correction should indicate how the user can fix the error. - */ + /// Return the template used to create the correction to be displayed for this + /// error, or `null` if there is no correction information for this error. The + /// correction should indicate how the user can fix the error. String get correction => _correction; @override @@ -987,22 +959,16 @@ class AnalysisError implements Diagnostic { return hashCode; } - /** - * The number of characters from the offset to the end of the source which - * encompasses the compilation error. - */ + /// The number of characters from the offset to the end of the source which + /// encompasses the compilation error. int get length => _problemMessage.length; - /** - * Return the message to be displayed for this error. The message should - * indicate what is wrong and why it is wrong. - */ + /// Return the message to be displayed for this error. The message should + /// indicate what is wrong and why it is wrong. String get message => _problemMessage.message; - /** - * The character offset from the beginning of the source (zero based) where - * the error occurred. - */ + /// The character offset from the beginning of the source (zero based) where + /// the error occurred. int get offset => _problemMessage.offset; @override @@ -1063,10 +1029,8 @@ class AnalysisError implements Diagnostic { return buffer.toString(); } - /** - * Merge all of the errors in the lists in the given list of [errorLists] into - * a single list of errors. - */ + /// Merge all of the errors in the lists in the given list of [errorLists] + /// into a single list of errors. static List mergeLists(List> errorLists) { Set errors = HashSet(); for (List errorList in errorLists) { diff --git a/pkg/analyzer/lib/error/listener.dart b/pkg/analyzer/lib/error/listener.dart index 975440869ec89..e95548f013ebc 100644 --- a/pkg/analyzer/lib/error/listener.dart +++ b/pkg/analyzer/lib/error/listener.dart @@ -16,36 +16,24 @@ import 'package:analyzer/src/diagnostic/diagnostic.dart'; import 'package:analyzer/src/generated/source.dart'; import 'package:source_span/source_span.dart'; -/** - * An object that listen for [AnalysisError]s being produced by the analysis - * engine. - */ +/// An object that listen for [AnalysisError]s being produced by the analysis +/// engine. abstract class AnalysisErrorListener { - /** - * An error listener that ignores errors that are reported to it. - */ + /// An error listener that ignores errors that are reported to it. static final AnalysisErrorListener NULL_LISTENER = _NullErrorListener(); - /** - * This method is invoked when an [error] has been found by the analysis - * engine. - */ + /// This method is invoked when an [error] has been found by the analysis + /// engine. void onError(AnalysisError error); } -/** - * An [AnalysisErrorListener] that keeps track of whether any error has been - * reported to it. - */ +/// An [AnalysisErrorListener] that keeps track of whether any error has been +/// reported to it. class BooleanErrorListener implements AnalysisErrorListener { - /** - * A flag indicating whether an error has been reported to this listener. - */ + /// A flag indicating whether an error has been reported to this listener. bool _errorReported = false; - /** - * Return `true` if an error has been reported to this listener. - */ + /// Return `true` if an error has been reported to this listener. bool get errorReported => _errorReported; @override @@ -54,36 +42,24 @@ class BooleanErrorListener implements AnalysisErrorListener { } } -/** - * An object used to create analysis errors and report then to an error - * listener. - */ +/// An object used to create analysis errors and report then to an error +/// listener. class ErrorReporter { - /** - * The error listener to which errors will be reported. - */ + /// The error listener to which errors will be reported. final AnalysisErrorListener _errorListener; - /** - * The default source to be used when reporting errors. - */ + /// The default source to be used when reporting errors. final Source _defaultSource; - /** - * Is `true` if the library being analyzed is non-nullable by default. - */ + /// Is `true` if the library being analyzed is non-nullable by default. final bool isNonNullableByDefault; - /** - * The source to be used when reporting errors. - */ + /// The source to be used when reporting errors. Source _source; - /** - * Initialize a newly created error reporter that will report errors to the - * given [_errorListener]. Errors will be reported against the - * [_defaultSource] unless another source is provided later. - */ + /// Initialize a newly created error reporter that will report errors to the + /// given [_errorListener]. Errors will be reported against the + /// [_defaultSource] unless another source is provided later. ErrorReporter(this._errorListener, this._defaultSource, {this.isNonNullableByDefault = false}) { if (_errorListener == null) { @@ -96,26 +72,20 @@ class ErrorReporter { Source get source => _source; - /** - * Set the source to be used when reporting errors to the given [source]. - * Setting the source to `null` will cause the default source to be used. - */ + /// Set the source to be used when reporting errors to the given [source]. + /// Setting the source to `null` will cause the default source to be used. @Deprecated('Create separate reporters for separate files') set source(Source source) { this._source = source ?? _defaultSource; } - /** - * Report the given [error]. - */ + /// Report the given [error]. void reportError(AnalysisError error) { _errorListener.onError(error); } - /** - * Report an error with the given [errorCode] and [arguments]. The [element] - * is used to compute the location of the error. - */ + /// Report an error with the given [errorCode] and [arguments]. The [element] + /// is used to compute the location of the error. void reportErrorForElement(ErrorCode errorCode, Element element, [List arguments]) { reportErrorForOffset( @@ -138,19 +108,15 @@ class ErrorReporter { } } - /** - * Report an error with the given [errorCode] and [arguments]. - * The [node] is used to compute the location of the error. - */ + /// Report an error with the given [errorCode] and [arguments]. + /// The [node] is used to compute the location of the error. void reportErrorForNode(ErrorCode errorCode, AstNode node, [List arguments]) { reportErrorForOffset(errorCode, node.offset, node.length, arguments); } - /** - * Report an error with the given [errorCode] and [arguments]. The location of - * the error is specified by the given [offset] and [length]. - */ + /// Report an error with the given [errorCode] and [arguments]. The location + /// of the error is specified by the given [offset] and [length]. void reportErrorForOffset(ErrorCode errorCode, int offset, int length, [List arguments]) { _convertElements(arguments); @@ -159,45 +125,37 @@ class ErrorReporter { AnalysisError(_source, offset, length, errorCode, arguments, messages)); } - /** - * Report an error with the given [errorCode] and [arguments]. The location of - * the error is specified by the given [span]. - */ + /// Report an error with the given [errorCode] and [arguments]. The location + /// of the error is specified by the given [span]. void reportErrorForSpan(ErrorCode errorCode, SourceSpan span, [List arguments]) { reportErrorForOffset(errorCode, span.start.offset, span.length, arguments); } - /** - * Report an error with the given [errorCode] and [arguments]. The [token] is - * used to compute the location of the error. - */ + /// Report an error with the given [errorCode] and [arguments]. The [token] is + /// used to compute the location of the error. void reportErrorForToken(ErrorCode errorCode, Token token, [List arguments]) { reportErrorForOffset(errorCode, token.offset, token.length, arguments); } - /** - * Report an error with the given [errorCode] and [message]. The location of - * the error is specified by the given [offset] and [length]. - */ + /// Report an error with the given [errorCode] and [message]. The location of + /// the error is specified by the given [offset] and [length]. void reportErrorMessage( ErrorCode errorCode, int offset, int length, Message message) { _errorListener.onError(AnalysisError.forValues( _source, offset, length, errorCode, message.message, message.tip)); } - /** - * Report an error with the given [errorCode] and [arguments]. The [node] is - * used to compute the location of the error. The arguments are expected to - * contain two or more types. Convert the types into strings by using the - * display names of the types, unless there are two or more types with the - * same names, in which case the extended display names of the types will be - * used in order to clarify the message. - * - * If there are not two or more types in the argument list, the method - * [reportErrorForNode] should be used instead. - */ + /// Report an error with the given [errorCode] and [arguments]. The [node] is + /// used to compute the location of the error. The arguments are expected to + /// contain two or more types. Convert the types into strings by using the + /// display names of the types, unless there are two or more types with the + /// same names, in which case the extended display names of the types will be + /// used in order to clarify the message. + /// + /// If there are not two or more types in the argument list, the method + /// [reportErrorForNode] should be used instead. @Deprecated('Use reportErrorForNode(), it will convert types as well') void reportTypeErrorForNode( ErrorCode errorCode, AstNode node, List arguments) { @@ -220,13 +178,11 @@ class ErrorReporter { } } - /** - * Given an array of [arguments] that is expected to contain two or more - * types, convert the types into strings by using the display names of the - * types, unless there are two or more types with the same names, in which - * case the extended display names of the types will be used in order to - * clarify the message. - */ + /// Given an array of [arguments] that is expected to contain two or more + /// types, convert the types into strings by using the display names of the + /// types, unless there are two or more types with the same names, in which + /// case the extended display names of the types will be used in order to + /// clarify the message. List _convertTypeNames(List arguments) { var messages = []; if (arguments == null) { @@ -295,16 +251,12 @@ class ErrorReporter { } } -/** - * An error listener that will record the errors that are reported to it in a - * way that is appropriate for caching those errors within an analysis context. - */ +/// An error listener that will record the errors that are reported to it in a +/// way that is appropriate for caching those errors within an analysis context. class RecordingErrorListener implements AnalysisErrorListener { Set _errors; - /** - * Return the errors collected by the listener. - */ + /// Return the errors collected by the listener. List get errors { if (_errors == null) { return const []; @@ -312,9 +264,7 @@ class RecordingErrorListener implements AnalysisErrorListener { return _errors.toList(); } - /** - * Return the errors collected by the listener for the given [source]. - */ + /// Return the errors collected by the listener for the given [source]. List getErrorsForSource(Source source) { if (_errors == null) { return const []; @@ -329,9 +279,7 @@ class RecordingErrorListener implements AnalysisErrorListener { } } -/** - * An [AnalysisErrorListener] that ignores error. - */ +/// An [AnalysisErrorListener] that ignores error. class _NullErrorListener implements AnalysisErrorListener { @override void onError(AnalysisError event) { @@ -339,10 +287,8 @@ class _NullErrorListener implements AnalysisErrorListener { } } -/** - * Used by `ErrorReporter._convertTypeNames` to keep track of a type that is - * being converted. - */ +/// Used by `ErrorReporter._convertTypeNames` to keep track of a type that is +/// being converted. class _TypeToConvert { final int index; final DartType type; diff --git a/pkg/analyzer/lib/exception/exception.dart b/pkg/analyzer/lib/exception/exception.dart index d00c9670ab614..6a2bd6c7e4138 100644 --- a/pkg/analyzer/lib/exception/exception.dart +++ b/pkg/analyzer/lib/exception/exception.dart @@ -2,25 +2,17 @@ // 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. -/** - * An exception that occurred during the analysis of one or more sources. - */ +/// An exception that occurred during the analysis of one or more sources. class AnalysisException implements Exception { - /** - * The message that explains why the exception occurred. - */ + /// The message that explains why the exception occurred. final String message; - /** - * The exception that caused this exception, or `null` if this exception was - * not caused by another exception. - */ + /// The exception that caused this exception, or `null` if this exception was + /// not caused by another exception. final CaughtException cause; - /** - * Initialize a newly created exception to have the given [message] and - * [cause]. - */ + /// Initialize a newly created exception to have the given [message] and + /// [cause]. AnalysisException([this.message = 'Exception', this.cause]); @override @@ -36,45 +28,31 @@ class AnalysisException implements Exception { } } -/** - * An exception that was caught and has an associated stack trace. - */ +/// An exception that was caught and has an associated stack trace. class CaughtException implements Exception { - /** - * The exception that was caught. - */ + /// The exception that was caught. final Object exception; - /** - * The message describing where/how/why this was caught. - */ + /// The message describing where/how/why this was caught. final String message; - /** - * The stack trace associated with the exception. - */ + /// The stack trace associated with the exception. StackTrace stackTrace; - /** - * Initialize a newly created caught exception to have the given [exception] - * and [stackTrace]. - */ + /// Initialize a newly created caught exception to have the given [exception] + /// and [stackTrace]. CaughtException(exception, stackTrace) : this.withMessage(null, exception, stackTrace); - /** - * Initialize a newly created caught exception to have the given [exception], - * [stackTrace], and [message]. - */ + /// Initialize a newly created caught exception to have the given [exception], + /// [stackTrace], and [message]. CaughtException.withMessage(this.message, this.exception, stackTrace) : this.stackTrace = stackTrace ?? StackTrace.current; - /** - * Recursively unwrap this [CaughtException] if it itself contains a - * [CaughtException]. - * - * If it does not contain a [CaughtException], simply return this instance. - */ + /// Recursively unwrap this [CaughtException] if it itself contains a + /// [CaughtException]. + /// + /// If it does not contain a [CaughtException], simply return this instance. CaughtException get rootCaughtException { if (exception is CaughtException) { return (exception as CaughtException).rootCaughtException; @@ -89,10 +67,8 @@ class CaughtException implements Exception { return buffer.toString(); } - /** - * Write a textual representation of the caught exception and its associated - * stack trace. - */ + /// Write a textual representation of the caught exception and its associated + /// stack trace. void _writeOn(StringBuffer buffer) { if (message != null) { buffer.writeln(message); @@ -117,19 +93,16 @@ class CaughtException implements Exception { } } -/** - * A form of [CaughtException] that should be silent to users. - * - * This is still considered an exceptional situation and will be sent to crash - * reporting. - */ +/// A form of [CaughtException] that should be silent to users. +/// +/// This is still considered an exceptional situation and will be sent to crash +/// reporting. class SilentException extends CaughtException { SilentException(String message, exception, stackTrace) : super.withMessage(message, exception, stackTrace); - /** - * Create a [SilentException] to wrap a [CaughtException], adding a [message]. - */ + /// Create a [SilentException] to wrap a [CaughtException], adding a + /// [message]. SilentException.wrapInMessage(String message, CaughtException exception) : this(message, exception, null); } diff --git a/pkg/analyzer/lib/file_system/file_system.dart b/pkg/analyzer/lib/file_system/file_system.dart index 61770a15587cf..6c8735b1ff0ca 100644 --- a/pkg/analyzer/lib/file_system/file_system.dart +++ b/pkg/analyzer/lib/file_system/file_system.dart @@ -10,79 +10,57 @@ import 'package:watcher/watcher.dart'; export 'package:analyzer/src/file_system/file_system.dart'; -/** - * [File]s are leaf [Resource]s which contain data. - */ +/// [File]s are leaf [Resource]s which contain data. abstract class File implements Resource { - /** - * Watch for changes to this file - */ + /// Watch for changes to this file Stream get changes; - /** - * Synchronously get the length of the file. - * Throws a [FileSystemException] if the operation fails. - */ + /// Synchronously get the length of the file. + /// Throws a [FileSystemException] if the operation fails. int get lengthSync; - /** - * Return the last-modified stamp of the file. - * Throws a [FileSystemException] if the file does not exist. - */ + /// Return the last-modified stamp of the file. + /// Throws a [FileSystemException] if the file does not exist. int get modificationStamp; @override File copyTo(Folder parentFolder); - /** - * Create a new [Source] instance that serves this file. - */ + /// Create a new [Source] instance that serves this file. Source createSource([Uri uri]); - /** - * Synchronously read the entire file contents as a list of bytes. - * Throws a [FileSystemException] if the operation fails. - */ + /// Synchronously read the entire file contents as a list of bytes. + /// Throws a [FileSystemException] if the operation fails. List readAsBytesSync(); - /** - * Synchronously read the entire file contents as a [String]. - * Throws [FileSystemException] if the file does not exist. - */ + /// Synchronously read the entire file contents as a [String]. + /// Throws [FileSystemException] if the file does not exist. String readAsStringSync(); - /** - * Synchronously rename this file. - * Return a [File] instance for the renamed file. - * - * The [newPath] must be absolute and normalized. - * - * If [newPath] identifies an existing file, that file is replaced. - * If [newPath] identifies an existing resource the operation might fail and - * an exception is thrown. - */ + /// Synchronously rename this file. + /// Return a [File] instance for the renamed file. + /// + /// The [newPath] must be absolute and normalized. + /// + /// If [newPath] identifies an existing file, that file is replaced. + /// If [newPath] identifies an existing resource the operation might fail and + /// an exception is thrown. File renameSync(String newPath); - /** - * Synchronously write the given [bytes] to the file. The new content will - * replace any existing content. - * - * Throws a [FileSystemException] if the operation fails. - */ + /// Synchronously write the given [bytes] to the file. The new content will + /// replace any existing content. + /// + /// Throws a [FileSystemException] if the operation fails. void writeAsBytesSync(List bytes); - /** - * Synchronously write the given [content] to the file. The new content will - * replace any existing content. - * - * Throws a [FileSystemException] if the operation fails. - */ + /// Synchronously write the given [content] to the file. The new content will + /// replace any existing content. + /// + /// Throws a [FileSystemException] if the operation fails. void writeAsStringSync(String content); } -/** - * Base class for all file system exceptions. - */ +/// Base class for all file system exceptions. class FileSystemException implements Exception { final String path; final String message; @@ -93,187 +71,136 @@ class FileSystemException implements Exception { String toString() => 'FileSystemException(path=$path; message=$message)'; } -/** - * [Folder]s are [Resource]s which may contain files and/or other folders. - */ +/// [Folder]s are [Resource]s which may contain files and/or other folders. abstract class Folder implements Resource { - /** - * Watch for changes to the files inside this folder (and in any nested - * folders, including folders reachable via links). - */ + /// Watch for changes to the files inside this folder (and in any nested + /// folders, including folders reachable via links). Stream get changes; - /** - * If the path [path] is a relative path, convert it to an absolute path - * by interpreting it relative to this folder. If it is already an absolute - * path, then don't change it. - * - * However, regardless of whether [path] is relative or absolute, normalize - * it by removing path components of the form '.' or '..'. - */ + /// If the path [path] is a relative path, convert it to an absolute path + /// by interpreting it relative to this folder. If it is already an absolute + /// path, then don't change it. + /// + /// However, regardless of whether [path] is relative or absolute, normalize + /// it by removing path components of the form '.' or '..'. String canonicalizePath(String path); - /** - * Return `true` if the [path] references a resource in this folder. - * - * The [path] must be absolute and normalized. - */ + /// Return `true` if the [path] references a resource in this folder. + /// + /// The [path] must be absolute and normalized. bool contains(String path); @override Folder copyTo(Folder parentFolder); - /** - * If this folder does not already exist, create it. - */ + /// If this folder does not already exist, create it. void create(); - /** - * Return an existing child [Resource] with the given [relPath]. - * Return a not existing [File] if no such child exist. - */ + /// Return an existing child [Resource] with the given [relPath]. + /// Return a not existing [File] if no such child exist. Resource getChild(String relPath); - /** - * Return a [File] representing a child [Resource] with the given - * [relPath]. This call does not check whether a file with the given name - * exists on the filesystem - client must call the [File]'s `exists` getter - * to determine whether the folder actually exists. - */ + /// Return a [File] representing a child [Resource] with the given + /// [relPath]. This call does not check whether a file with the given name + /// exists on the filesystem - client must call the [File]'s `exists` getter + /// to determine whether the folder actually exists. File getChildAssumingFile(String relPath); - /** - * Return a [Folder] representing a child [Resource] with the given - * [relPath]. This call does not check whether a folder with the given name - * exists on the filesystem--client must call the [Folder]'s `exists` getter - * to determine whether the folder actually exists. - */ + /// Return a [Folder] representing a child [Resource] with the given + /// [relPath]. This call does not check whether a folder with the given name + /// exists on the filesystem--client must call the [Folder]'s `exists` getter + /// to determine whether the folder actually exists. Folder getChildAssumingFolder(String relPath); - /** - * Return a list of existing direct children [Resource]s (folders and files) - * in this folder, in no particular order. - * - * On I/O errors, this will throw [FileSystemException]. - */ + /// Return a list of existing direct children [Resource]s (folders and files) + /// in this folder, in no particular order. + /// + /// On I/O errors, this will throw [FileSystemException]. List getChildren(); } -/** - * The abstract class [Resource] is an abstraction of file or folder. - */ +/// The abstract class [Resource] is an abstraction of file or folder. abstract class Resource { - /** - * Return `true` if this resource exists. - */ + /// Return `true` if this resource exists. bool get exists; - /** - * Return the [Folder] that contains this resource, or `null` if this resource - * is a root folder. - */ + /// Return the [Folder] that contains this resource, or `null` if this + /// resource is a root folder. Folder get parent; - /** - * Return the full path to this resource. - */ + /// Return the full path to this resource. String get path; - /** - * Return a short version of the name that can be displayed to the user to - * denote this resource. - */ + /// Return a short version of the name that can be displayed to the user to + /// denote this resource. String get shortName; - /** - * Copy this resource to a child of the [parentFolder] with the same kind and - * [shortName] as this resource. If this resource is a folder, then all of the - * contents of the folder will be recursively copied. - * - * The parent folder is created if it does not already exist. - * - * Existing files and folders will be overwritten. - * - * Return the resource corresponding to this resource in the parent folder. - */ + /// Copy this resource to a child of the [parentFolder] with the same kind and + /// [shortName] as this resource. If this resource is a folder, then all of + /// the contents of the folder will be recursively copied. + /// + /// The parent folder is created if it does not already exist. + /// + /// Existing files and folders will be overwritten. + /// + /// Return the resource corresponding to this resource in the parent folder. Resource copyTo(Folder parentFolder); - /** - * Synchronously deletes this resource and its children. - * - * Throws an exception if the resource cannot be deleted. - */ + /// Synchronously deletes this resource and its children. + /// + /// Throws an exception if the resource cannot be deleted. void delete(); - /** - * Return `true` if absolute [path] references this resource or a resource in - * this folder. - * - * The [path] must be absolute and normalized. - */ + /// Return `true` if absolute [path] references this resource or a resource in + /// this folder. + /// + /// The [path] must be absolute and normalized. bool isOrContains(String path); - /** - * Return a resource that refers to the same resource as this resource, but - * whose path does not contain any symbolic links. - */ + /// Return a resource that refers to the same resource as this resource, but + /// whose path does not contain any symbolic links. Resource resolveSymbolicLinksSync(); - /** - * Return a Uri representing this resource. - */ + /// Return a Uri representing this resource. Uri toUri(); } -/** - * Instances of the class [ResourceProvider] convert [String] paths into - * [Resource]s. - */ +/// Instances of the class [ResourceProvider] convert [String] paths into +/// [Resource]s. abstract class ResourceProvider { - /** - * Get the path context used by this resource provider. - */ + /// Get the path context used by this resource provider. Context get pathContext; - /** - * Return a [File] that corresponds to the given [path]. - * - * The [path] must be absolute and normalized. - * - * A file may or may not exist at this location. - */ + /// Return a [File] that corresponds to the given [path]. + /// + /// The [path] must be absolute and normalized. + /// + /// A file may or may not exist at this location. File getFile(String path); - /** - * Return a [Folder] that corresponds to the given [path]. - * - * The [path] must be absolute and normalized. - * - * A folder may or may not exist at this location. - */ + /// Return a [Folder] that corresponds to the given [path]. + /// + /// The [path] must be absolute and normalized. + /// + /// A folder may or may not exist at this location. Folder getFolder(String path); - /** - * Complete with a list of modification times for the given [sources]. - * - * If the file of a source is not managed by this provider, return `null`. - * If the file a source does not exist, return `-1`. - */ + /// Complete with a list of modification times for the given [sources]. + /// + /// If the file of a source is not managed by this provider, return `null`. + /// If the file a source does not exist, return `-1`. Future> getModificationTimes(List sources); - /** - * Return the [Resource] that corresponds to the given [path]. - * - * The [path] must be absolute and normalized. - */ + /// Return the [Resource] that corresponds to the given [path]. + /// + /// The [path] must be absolute and normalized. Resource getResource(String path); - /** - * Return the folder in which the plugin with the given [pluginId] can store - * state that will persist across sessions. The folder returned for a given id - * will not be returned for a different id, ensuring that plugins do not need - * to be concerned with file name collisions with other plugins, assuming that - * the plugin ids are unique. The plugin ids must be valid folder names. - */ + /// Return the folder in which the plugin with the given [pluginId] can store + /// state that will persist across sessions. The folder returned for a given + /// id will not be returned for a different id, ensuring that plugins do not + /// need to be concerned with file name collisions with other plugins, + /// assuming that the plugin ids are unique. The plugin ids must be valid + /// folder names. Folder getStateLocation(String pluginId); } diff --git a/pkg/analyzer/lib/file_system/memory_file_system.dart b/pkg/analyzer/lib/file_system/memory_file_system.dart index 6d6db84f580ba..08762ab83c802 100644 --- a/pkg/analyzer/lib/file_system/memory_file_system.dart +++ b/pkg/analyzer/lib/file_system/memory_file_system.dart @@ -13,10 +13,8 @@ import 'package:analyzer/src/source/source_resource.dart'; import 'package:path/path.dart' as pathos; import 'package:watcher/watcher.dart'; -/** - * An in-memory implementation of [ResourceProvider]. - * Use `/` as a path separator. - */ +/// An in-memory implementation of [ResourceProvider]. +/// Use `/` as a path separator. class MemoryResourceProvider implements ResourceProvider { final Map _pathToResource = HashMap(); @@ -40,12 +38,10 @@ class MemoryResourceProvider implements ResourceProvider { @override pathos.Context get pathContext => _pathContext; - /** - * Convert the given posix [path] to conform to this provider's path context. - * - * This is a utility method for testing; paths passed in to other methods in - * this class are never converted automatically. - */ + /// Convert the given posix [path] to conform to this provider's path context. + /// + /// This is a utility method for testing; paths passed in to other methods in + /// this class are never converted automatically. String convertPath(String path) { if (pathContext.style == pathos.windows.style) { if (path.startsWith(pathos.posix.separator)) { @@ -56,9 +52,7 @@ class MemoryResourceProvider implements ResourceProvider { return path; } - /** - * Delete the file with the given path. - */ + /// Delete the file with the given path. void deleteFile(String path) { _checkFileAtPath(path); _pathToResource.remove(path); @@ -67,10 +61,8 @@ class MemoryResourceProvider implements ResourceProvider { _notifyWatchers(path, ChangeType.REMOVE); } - /** - * Delete the folder with the given path - * and recursively delete nested files and folders. - */ + /// Delete the folder with the given path + /// and recursively delete nested files and folders. void deleteFolder(String path) { _checkFolderAtPath(path); _MemoryFolder folder = _pathToResource[path]; @@ -128,10 +120,8 @@ class MemoryResourceProvider implements ResourceProvider { _notifyWatchers(path, ChangeType.MODIFY); } - /** - * Create a resource representing a dummy link (that is, a File object which - * appears in its parent directory, but whose `exists` property is false) - */ + /// Create a resource representing a dummy link (that is, a File object which + /// appears in its parent directory, but whose `exists` property is false) File newDummyLink(String path) { _ensureAbsoluteAndNormalized(path); newFolder(pathContext.dirname(path)); @@ -197,9 +187,7 @@ class MemoryResourceProvider implements ResourceProvider { return file; } - /** - * Write a representation of the file system on the given [sink]. - */ + /// Write a representation of the file system on the given [sink]. void writeOn(StringSink sink) { List paths = _pathToResource.keys.toList(); paths.sort(); @@ -229,10 +217,8 @@ class MemoryResourceProvider implements ResourceProvider { } } - /** - * The file system abstraction supports only absolute and normalized paths. - * This method is used to validate any input paths to prevent errors later. - */ + /// The file system abstraction supports only absolute and normalized paths. + /// This method is used to validate any input paths to prevent errors later. void _ensureAbsoluteAndNormalized(String path) { if (!pathContext.isAbsolute(path)) { throw ArgumentError("Path must be absolute : $path"); @@ -242,9 +228,7 @@ class MemoryResourceProvider implements ResourceProvider { } } - /** - * Create a new [_MemoryFile] without any content. - */ + /// Create a new [_MemoryFile] without any content. _MemoryFile _newFile(String path) { String folderPath = pathContext.dirname(path); _MemoryResource folder = _pathToResource[folderPath]; @@ -301,10 +285,8 @@ class MemoryResourceProvider implements ResourceProvider { } } -/** - * An in-memory implementation of [File] which acts like a symbolic link to a - * non-existent file. - */ +/// An in-memory implementation of [File] which acts like a symbolic link to a +/// non-existent file. class _MemoryDummyLink extends _MemoryResource implements File { _MemoryDummyLink(MemoryResourceProvider provider, String path) : super(provider, path); @@ -382,9 +364,7 @@ class _MemoryDummyLink extends _MemoryResource implements File { } } -/** - * An in-memory implementation of [File]. - */ +/// An in-memory implementation of [File]. class _MemoryFile extends _MemoryResource implements File { _MemoryFile(MemoryResourceProvider provider, String path) : super(provider, path); @@ -467,9 +447,7 @@ class _MemoryFile extends _MemoryResource implements File { } } -/** - * An in-memory implementation of [Folder]. - */ +/// An in-memory implementation of [Folder]. class _MemoryFolder extends _MemoryResource implements Folder { _MemoryFolder(MemoryResourceProvider provider, String path) : super(provider, path); @@ -566,9 +544,7 @@ class _MemoryFolder extends _MemoryResource implements Folder { Uri toUri() => _provider.pathContext.toUri(path + '/'); } -/** - * An in-memory implementation of [Resource]. - */ +/// An in-memory implementation of [Resource]. abstract class _MemoryResource implements Resource { final MemoryResourceProvider _provider; @override diff --git a/pkg/analyzer/lib/file_system/overlay_file_system.dart b/pkg/analyzer/lib/file_system/overlay_file_system.dart index d1e636a6c9cfd..601b913994b48 100644 --- a/pkg/analyzer/lib/file_system/overlay_file_system.dart +++ b/pkg/analyzer/lib/file_system/overlay_file_system.dart @@ -14,38 +14,28 @@ import 'package:meta/meta.dart'; import 'package:path/path.dart' as pathos; import 'package:watcher/watcher.dart'; -/** - * A resource provider that allows clients to overlay the file system provided - * by a base resource provider. These overlays allow both the contents and - * modification stamps of files to be different than what the base resource - * provider would report. - * - * This provider does not report watch events when overlays are added, modified - * or removed. - */ +/// A resource provider that allows clients to overlay the file system provided +/// by a base resource provider. These overlays allow both the contents and +/// modification stamps of files to be different than what the base resource +/// provider would report. +/// +/// This provider does not report watch events when overlays are added, modified +/// or removed. class OverlayResourceProvider implements ResourceProvider { - /** - * The underlying resource provider used to access files and folders that - * do not have an overlay. - */ + /// The underlying resource provider used to access files and folders that + /// do not have an overlay. final ResourceProvider baseProvider; - /** - * A map from the paths of files for which there is an overlay to the contents - * of the files. - */ + /// A map from the paths of files for which there is an overlay to the + /// contents of the files. final Map _overlayContent = {}; - /** - * A map from the paths of files for which there is an overlay to the - * modification stamps of the files. - */ + /// A map from the paths of files for which there is an overlay to the + /// modification stamps of the files. final Map _overlayModificationStamps = {}; - /** - * Initialize a newly created resource provider to represent an overlay on the - * given [baseProvider]. - */ + /// Initialize a newly created resource provider to represent an overlay on + /// the given [baseProvider]. OverlayResourceProvider(this.baseProvider); @override @@ -81,16 +71,12 @@ class OverlayResourceProvider implements ResourceProvider { Folder getStateLocation(String pluginId) => _OverlayFolder(this, baseProvider.getStateLocation(pluginId)); - /** - * Return `true` if there is an overlay associated with the file at the given - * [path]. - */ + /// Return `true` if there is an overlay associated with the file at the given + /// [path]. bool hasOverlay(String path) => _overlayContent.containsKey(path); - /** - * Remove any overlay of the file at the given [path]. The state of the file - * in the base resource provider will not be affected. - */ + /// Remove any overlay of the file at the given [path]. The state of the file + /// in the base resource provider will not be affected. bool removeOverlay(String path) { bool hadOverlay = _overlayContent.containsKey(path); _overlayContent.remove(path); @@ -98,11 +84,9 @@ class OverlayResourceProvider implements ResourceProvider { return hadOverlay; } - /** - * Overlay the content of the file at the given [path]. The file will appear - * to have the given [content] and [modificationStamp] even if the file is - * modified in the base resource provider. - */ + /// Overlay the content of the file at the given [path]. The file will appear + /// to have the given [content] and [modificationStamp] even if the file is + /// modified in the base resource provider. void setOverlay(String path, {@required String content, @required int modificationStamp}) { if (content == null) { @@ -110,16 +94,15 @@ class OverlayResourceProvider implements ResourceProvider { 'OverlayResourceProvider.setOverlay: content cannot be null'); } else if (modificationStamp == null) { throw ArgumentError( - 'OverlayResourceProvider.setOverlay: modificationStamp cannot be null'); + 'OverlayResourceProvider.setOverlay: modificationStamp cannot be ' + 'null'); } _overlayContent[path] = content; _overlayModificationStamps[path] = modificationStamp; } - /** - * Copy any overlay for the file at the [oldPath] to be an overlay for the - * file with the [newPath]. - */ + /// Copy any overlay for the file at the [oldPath] to be an overlay for the + /// file with the [newPath]. void _copyOverlay(String oldPath, String newPath) { if (hasOverlay(oldPath)) { _overlayContent[newPath] = _overlayContent[oldPath]; @@ -127,45 +110,33 @@ class OverlayResourceProvider implements ResourceProvider { } } - /** - * Return the content of the overlay of the file at the given [path], or - * `null` if there is no overlay for the specified file. - */ + /// Return the content of the overlay of the file at the given [path], or + /// `null` if there is no overlay for the specified file. String _getOverlayContent(String path) { return _overlayContent[path]; } - /** - * Return the modification stamp of the overlay of the file at the given - * [path], or `null` if there is no overlay for the specified file. - */ + /// Return the modification stamp of the overlay of the file at the given + /// [path], or `null` if there is no overlay for the specified file. int _getOverlayModificationStamp(String path) { return _overlayModificationStamps[path]; } - /** - * Return `true` if there is an overlay associated with at least one file - * contained inside the folder with the given [folderPath]. - */ + /// Return `true` if there is an overlay associated with at least one file + /// contained inside the folder with the given [folderPath]. bool _hasOverlayIn(String folderPath) => _overlayContent.keys .any((filePath) => pathContext.isWithin(folderPath, filePath)); - /** - * Return the paths of all of the overlaid files that are children of the - * given [folder], either directly or indirectly. - */ + /// Return the paths of all of the overlaid files that are children of the + /// given [folder], either directly or indirectly. Iterable _overlaysInFolder(String folderPath) => _overlayContent.keys .where((filePath) => pathContext.isWithin(folderPath, filePath)); } -/** - * A file from an [OverlayResourceProvider]. - */ +/// A file from an [OverlayResourceProvider]. class _OverlayFile extends _OverlayResource implements File { - /** - * Initialize a newly created file to have the given [provider] and to - * correspond to the given [file] from the provider's base resource provider. - */ + /// Initialize a newly created file to have the given [provider] and to + /// correspond to the given [file] from the provider's base resource provider. _OverlayFile(OverlayResourceProvider provider, File file) : super(provider, file); @@ -193,10 +164,8 @@ class _OverlayFile extends _OverlayResource implements File { return _file.modificationStamp; } - /** - * Return the file from the base resource provider that corresponds to this - * folder. - */ + /// Return the file from the base resource provider that corresponds to this + /// folder. File get _file => _resource as File; @override @@ -271,15 +240,11 @@ class _OverlayFile extends _OverlayResource implements File { } } -/** - * A folder from an [OverlayResourceProvider]. - */ +/// A folder from an [OverlayResourceProvider]. class _OverlayFolder extends _OverlayResource implements Folder { - /** - * Initialize a newly created folder to have the given [provider] and to - * correspond to the given [folder] from the provider's base resource - * provider. - */ + /// Initialize a newly created folder to have the given [provider] and to + /// correspond to the given [folder] from the provider's base resource + /// provider. _OverlayFolder(OverlayResourceProvider provider, Folder folder) : super(provider, folder); @@ -289,10 +254,8 @@ class _OverlayFolder extends _OverlayResource implements Folder { @override bool get exists => _provider._hasOverlayIn(path) || _resource.exists; - /** - * Return the folder from the base resource provider that corresponds to this - * folder. - */ + /// Return the folder from the base resource provider that corresponds to this + /// folder. Folder get _folder => _resource as Folder; @override @@ -342,8 +305,8 @@ class _OverlayFolder extends _OverlayResource implements Folder { children[child.path] = _OverlayResource._from(_provider, child); } } on FileSystemException { - // We don't want to throw if we're a folder that only exists in the overlay - // and not on disk. + // We don't want to throw if we're a folder that only exists in the + // overlay and not on disk. } for (String overlayPath in _provider._overlaysInFolder(path)) { @@ -361,32 +324,22 @@ class _OverlayFolder extends _OverlayResource implements Folder { } } -/** - * The base class for resources from an [OverlayResourceProvider]. - */ +/// The base class for resources from an [OverlayResourceProvider]. abstract class _OverlayResource implements Resource { - /** - * The resource provider associated with this resource. - */ + /// The resource provider associated with this resource. final OverlayResourceProvider _provider; - /** - * The resource from the provider's base provider that corresponds to this - * resource. - */ + /// The resource from the provider's base provider that corresponds to this + /// resource. final Resource _resource; - /** - * Initialize a newly created instance of a resource to have the given - * [_provider] and to represent the [_resource] from the provider's base - * resource provider. - */ + /// Initialize a newly created instance of a resource to have the given + /// [_provider] and to represent the [_resource] from the provider's base + /// resource provider. _OverlayResource(this._provider, this._resource); - /** - * Return an instance of the subclass of this class corresponding to the given - * [resource] that is associated with the given [provider]. - */ + /// Return an instance of the subclass of this class corresponding to the + /// given [resource] that is associated with the given [provider]. factory _OverlayResource._from( OverlayResourceProvider provider, Resource resource) { if (resource is Folder) { diff --git a/pkg/analyzer/lib/file_system/physical_file_system.dart b/pkg/analyzer/lib/file_system/physical_file_system.dart index 2bd4343ecbcbb..2148dc7cca97a 100644 --- a/pkg/analyzer/lib/file_system/physical_file_system.dart +++ b/pkg/analyzer/lib/file_system/physical_file_system.dart @@ -12,19 +12,15 @@ import 'package:analyzer/src/source/source_resource.dart'; import 'package:path/path.dart'; import 'package:watcher/watcher.dart'; -/** - * The name of the directory containing plugin specific subfolders used to store - * data across sessions. - */ +/// The name of the directory containing plugin specific subfolders used to +/// store data across sessions. const String _SERVER_DIR = ".dartServer"; -/** - * Returns the path to default state location. - * - * Generally this is ~/.dartServer. It can be overridden via the - * ANALYZER_STATE_LOCATION_OVERRIDE environment variable, in which case this - * method will return the contents of that environment variable. - */ +/// Returns the path to default state location. +/// +/// Generally this is ~/.dartServer. It can be overridden via the +/// ANALYZER_STATE_LOCATION_OVERRIDE environment variable, in which case this +/// method will return the contents of that environment variable. String _getStandardStateLocation() { final Map env = io.Platform.environment; if (env.containsKey('ANALYZER_STATE_LOCATION_OVERRIDE')) { @@ -37,14 +33,12 @@ String _getStandardStateLocation() { : null; } -/** - * Return modification times for every file path in [paths]. - * - * If a path is `null`, the modification time is also `null`. - * - * If any exception happens, the file is considered as a not existing and - * `-1` is its modification time. - */ +/// Return modification times for every file path in [paths]. +/// +/// If a path is `null`, the modification time is also `null`. +/// +/// If any exception happens, the file is considered as a not existing and +/// `-1` is its modification time. List _pathsToTimes(List paths) { return paths.map((path) { if (path != null) { @@ -60,9 +54,7 @@ List _pathsToTimes(List paths) { }).toList(); } -/** - * A `dart:io` based implementation of [ResourceProvider]. - */ +/// A `dart:io` based implementation of [ResourceProvider]. class PhysicalResourceProvider implements ResourceProvider { static final String Function(String) NORMALIZE_EOL_ALWAYS = (String string) => string.replaceAll(RegExp('\r\n?'), '\n'); @@ -70,9 +62,7 @@ class PhysicalResourceProvider implements ResourceProvider { static final PhysicalResourceProvider INSTANCE = PhysicalResourceProvider(null); - /** - * The path to the base folder where state is stored. - */ + /// The path to the base folder where state is stored. final String _stateLocation; PhysicalResourceProvider(String Function(String) fileReadMode, @@ -124,10 +114,8 @@ class PhysicalResourceProvider implements ResourceProvider { return null; } - /** - * The file system abstraction supports only absolute and normalized paths. - * This method is used to validate any input paths to prevent errors later. - */ + /// The file system abstraction supports only absolute and normalized paths. + /// This method is used to validate any input paths to prevent errors later. void _ensureAbsoluteAndNormalized(String path) { assert(() { if (!pathContext.isAbsolute(path)) { @@ -141,9 +129,7 @@ class PhysicalResourceProvider implements ResourceProvider { } } -/** - * A `dart:io` based implementation of [File]. - */ +/// A `dart:io` based implementation of [File]. class _PhysicalFile extends _PhysicalResource implements File { _PhysicalFile(io.File file) : super(file); @@ -168,9 +154,7 @@ class _PhysicalFile extends _PhysicalResource implements File { } } - /** - * Return the underlying file being represented by this wrapper. - */ + /// Return the underlying file being represented by this wrapper. io.File get _file => _entry as io.File; @override @@ -251,9 +235,7 @@ class _PhysicalFile extends _PhysicalResource implements File { } } -/** - * A `dart:io` based implementation of [Folder]. - */ +/// A `dart:io` based implementation of [Folder]. class _PhysicalFolder extends _PhysicalResource implements Folder { _PhysicalFolder(io.Directory directory) : super(directory); @@ -267,9 +249,7 @@ class _PhysicalFolder extends _PhysicalResource implements Folder { !error.message .startsWith("Directory watcher closed unexpectedly")); - /** - * Return the underlying file being represented by this wrapper. - */ + /// Return the underlying file being represented by this wrapper. io.Directory get _directory => _entry as io.Directory; @override @@ -361,9 +341,7 @@ class _PhysicalFolder extends _PhysicalResource implements Folder { Uri toUri() => Uri.directory(path); } -/** - * A `dart:io` based implementation of [Resource]. - */ +/// A `dart:io` based implementation of [Resource]. abstract class _PhysicalResource implements Resource { final io.FileSystemEntity _entry; @@ -393,9 +371,7 @@ abstract class _PhysicalResource implements Resource { @override String get path => _entry.path; - /** - * Return the path context used by this resource provider. - */ + /// Return the path context used by this resource provider. Context get pathContext => io.Platform.isWindows ? windows : posix; @override @@ -421,12 +397,10 @@ abstract class _PhysicalResource implements Resource { @override String toString() => path; - /** - * If the operating system is Windows and the resource references one of the - * device drivers, throw a [FileSystemException]. - * - * https://support.microsoft.com/en-us/kb/74496 - */ + /// If the operating system is Windows and the resource references one of the + /// device drivers, throw a [FileSystemException]. + /// + /// https://support.microsoft.com/en-us/kb/74496 void _throwIfWindowsDeviceDriver() { if (io.Platform.isWindows) { String shortName = this.shortName.toUpperCase(); diff --git a/pkg/analyzer/lib/source/line_info.dart b/pkg/analyzer/lib/source/line_info.dart index da03c3b71dd05..c4126fe9bbd44 100644 --- a/pkg/analyzer/lib/source/line_info.dart +++ b/pkg/analyzer/lib/source/line_info.dart @@ -5,41 +5,29 @@ import 'package:analyzer/src/generated/java_engine.dart'; import 'package:analyzer/src/generated/source.dart'; -/** - * The location of a character represented as a line and column pair. - */ +/// The location of a character represented as a line and column pair. // ignore: deprecated_member_use_from_same_package class CharacterLocation extends LineInfo_Location { // TODO(brianwilkerson) Replace the body of this class with the body of // LineInfo_Location and remove LineInfo_Location. - /** - * Initialize a newly created location to represent the location of the - * character at the given [lineNumber] and [columnNumber]. - */ + /// Initialize a newly created location to represent the location of the + /// character at the given [lineNumber] and [columnNumber]. CharacterLocation(int lineNumber, int columnNumber) : super(lineNumber, columnNumber); } -/** - * Information about line and column information within a source file. - */ +/// Information about line and column information within a source file. class LineInfo { - /** - * A list containing the offsets of the first character of each line in the - * source code. - */ + /// A list containing the offsets of the first character of each line in the + /// source code. final List lineStarts; - /** - * The zero-based [lineStarts] index resulting from the last call to - * [getLocation]. - */ + /// The zero-based [lineStarts] index resulting from the last call to + /// [getLocation]. int _previousLine = 0; - /** - * Initialize a newly created set of line information to represent the data - * encoded in the given list of [lineStarts]. - */ + /// Initialize a newly created set of line information to represent the data + /// encoded in the given list of [lineStarts]. LineInfo(this.lineStarts) { if (lineStarts == null) { throw ArgumentError("lineStarts must be non-null"); @@ -48,25 +36,19 @@ class LineInfo { } } - /** - * Initialize a newly created set of line information corresponding to the - * given file [content]. - */ + /// Initialize a newly created set of line information corresponding to the + /// given file [content]. factory LineInfo.fromContent(String content) => LineInfo(StringUtilities.computeLineStarts(content)); - /** - * The number of lines. - */ + /// The number of lines. int get lineCount => lineStarts.length; - /** - * Return the location information for the character at the given [offset]. - * - * A future version of this API will return a [CharacterLocation] rather than - // ignore: deprecated_member_use_from_same_package - * a [LineInfo_Location]. - */ + /// Return the location information for the character at the given [offset]. + /// + /// A future version of this API will return a [CharacterLocation] rather than + /// // ignore: deprecated_member_use_from_same_package + /// a [LineInfo_Location]. // ignore: deprecated_member_use_from_same_package LineInfo_Location getLocation(int offset) { var min = 0; @@ -102,10 +84,8 @@ class LineInfo { return CharacterLocation(min + 1, offset - lineStarts[min] + 1); } - /** - * Return the offset of the first character on the line with the given - * [lineNumber]. - */ + /// Return the offset of the first character on the line with the given + /// [lineNumber]. int getOffsetOfLine(int lineNumber) { if (lineNumber < 0 || lineNumber >= lineCount) { throw ArgumentError( @@ -114,10 +94,8 @@ class LineInfo { return lineStarts[lineNumber]; } - /** - * Return the offset of the first character on the line following the line - * containing the given [offset]. - */ + /// Return the offset of the first character on the line following the line + /// containing the given [offset]. int getOffsetOfLineAfter(int offset) { return getOffsetOfLine(getLocation(offset).lineNumber); } diff --git a/pkg/analyzer/lib/source/source_range.dart b/pkg/analyzer/lib/source/source_range.dart index 4ac7a929786d0..d934abd21bb63 100644 --- a/pkg/analyzer/lib/source/source_range.dart +++ b/pkg/analyzer/lib/source/source_range.dart @@ -4,35 +4,23 @@ import "dart:math" as math; -/** - * A source range defines a range of characters within source code. - */ +/// A source range defines a range of characters within source code. class SourceRange { - /** - * An empty source range (a range with offset `0` and length `0`). - */ + /// An empty source range (a range with offset `0` and length `0`). static const SourceRange EMPTY = SourceRange(0, 0); - /** - * The 0-based index of the first character of the source range. - */ + /// The 0-based index of the first character of the source range. final int offset; - /** - * The number of characters in the source range. - */ + /// The number of characters in the source range. final int length; - /** - * Initialize a newly created source range using the given [offset] and - * [length]. - */ + /// Initialize a newly created source range using the given [offset] and + /// [length]. const SourceRange(this.offset, this.length); - /** - * Return the 0-based index of the character immediately after this source - * range. - */ + /// Return the 0-based index of the character immediately after this source + /// range. int get end => offset + length; @override @@ -45,57 +33,40 @@ class SourceRange { other.length == length; } - /** - * Return `true` if [x] is in the interval `[offset, offset + length]`. - */ + /// Return `true` if [x] is in the interval `[offset, offset + length]`. bool contains(int x) => offset <= x && x <= offset + length; - /** - * Return `true` if [x] is in the interval `(offset, offset + length)`. - */ + /// Return `true` if [x] is in the interval `(offset, offset + length)`. bool containsExclusive(int x) => offset < x && x < offset + length; - /** - * Return `true` if the [otherRange] covers this source range. - */ + /// Return `true` if the [otherRange] covers this source range. bool coveredBy(SourceRange otherRange) => otherRange.covers(this); - /** - * Return `true` if this source range covers the [otherRange]. - */ + /// Return `true` if this source range covers the [otherRange]. bool covers(SourceRange otherRange) => offset <= otherRange.offset && otherRange.end <= end; - /** - * Return `true` if this source range ends inside the [otherRange]. - */ + /// Return `true` if this source range ends inside the [otherRange]. bool endsIn(SourceRange otherRange) { int thisEnd = end; return otherRange.contains(thisEnd); } - /** - * Return a source range covering [delta] characters before the start of this - * source range and [delta] characters after the end of this source range. - */ + /// Return a source range covering [delta] characters before the start of this + /// source range and [delta] characters after the end of this source range. SourceRange getExpanded(int delta) => SourceRange(offset - delta, delta + length + delta); - /** - * Return a source range with the same offset as this source range but whose - * length is [delta] characters longer than this source range. - */ + /// Return a source range with the same offset as this source range but whose + /// length is [delta] characters longer than this source range. SourceRange getMoveEnd(int delta) => SourceRange(offset, length + delta); - /** - * Return a source range with the same length as this source range but whose - * offset is [delta] characters after the offset of this source range. - */ + /// Return a source range with the same length as this source range but whose + /// offset is [delta] characters after the offset of this source range. SourceRange getTranslated(int delta) => SourceRange(offset + delta, length); - /** - * Return the minimal source range that covers both this and the [otherRange]. - */ + /// Return the minimal source range that covers both this and the + /// [otherRange]. SourceRange getUnion(SourceRange otherRange) { int newOffset = math.min(offset, otherRange.offset); int newEnd = @@ -103,9 +74,7 @@ class SourceRange { return SourceRange(newOffset, newEnd - newOffset); } - /** - * Return `true` if this source range intersects the [otherRange]. - */ + /// Return `true` if this source range intersects the [otherRange]. bool intersects(SourceRange otherRange) { if (otherRange == null) { return false; @@ -119,9 +88,7 @@ class SourceRange { return true; } - /** - * Return `true` if this source range starts in the [otherRange]. - */ + /// Return `true` if this source range starts in the [otherRange]. bool startsIn(SourceRange otherRange) => otherRange.contains(offset); @override diff --git a/pkg/analyzer/lib/src/analysis_options/error/option_codes.dart b/pkg/analyzer/lib/src/analysis_options/error/option_codes.dart index 9977c0fc913b1..43ae068574b66 100644 --- a/pkg/analyzer/lib/src/analysis_options/error/option_codes.dart +++ b/pkg/analyzer/lib/src/analysis_options/error/option_codes.dart @@ -4,39 +4,31 @@ import 'package:analyzer/error/error.dart'; -/** - * The error codes used for errors in analysis options files. The convention for - * this class is for the name of the error code to indicate the problem that - * caused the error to be generated and for the error message to explain what is - * wrong and, when appropriate, how the problem can be corrected. - */ +/// The error codes used for errors in analysis options files. The convention +/// for this class is for the name of the error code to indicate the problem +/// that caused the error to be generated and for the error message to explain +/// what is wrong and, when appropriate, how the problem can be corrected. class AnalysisOptionsErrorCode extends ErrorCode { - /** - * An error code indicating that there is a syntactic error in the included - * file. - * - * Parameters: - * 0: the path of the file containing the error - * 1: the starting offset of the text in the file that contains the error - * 2: the ending offset of the text in the file that contains the error - * 3: the error message - */ + /// An error code indicating that there is a syntactic error in the included + /// file. + /// + /// Parameters: + /// 0: the path of the file containing the error + /// 1: the starting offset of the text in the file that contains the error + /// 2: the ending offset of the text in the file that contains the error + /// 3: the error message static const AnalysisOptionsErrorCode INCLUDED_FILE_PARSE_ERROR = AnalysisOptionsErrorCode( 'INCLUDED_FILE_PARSE_ERROR', '{3} in {0}({1}..{2})'); - /** - * An error code indicating that there is a syntactic error in the file. - * - * Parameters: - * 0: the error message from the parse error - */ + /// An error code indicating that there is a syntactic error in the file. + /// + /// Parameters: + /// 0: the error message from the parse error static const AnalysisOptionsErrorCode PARSE_ERROR = AnalysisOptionsErrorCode('PARSE_ERROR', '{0}'); - /** - * Initialize a newly created error code to have the given [name]. - */ + /// Initialize a newly created error code to have the given [name]. const AnalysisOptionsErrorCode(String name, String message, {String correction}) : super.temporary(name, message, correction: correction); @@ -49,48 +41,41 @@ class AnalysisOptionsErrorCode extends ErrorCode { } class AnalysisOptionsHintCode extends ErrorCode { - /** - * An error code indicating the analysis options file name is deprecated and - * the file should be renamed. - * - * Parameters: - * 0: the uri of the file which should be renamed - */ + /// An error code indicating the analysis options file name is deprecated and + /// the file should be renamed. + /// + /// Parameters: + /// 0: the uri of the file which should be renamed static const AnalysisOptionsHintCode DEPRECATED_ANALYSIS_OPTIONS_FILE_NAME = AnalysisOptionsHintCode( 'DEPRECATED_ANALYSIS_OPTIONS_FILE_NAME', "The name of the analysis options file {0} is deprecated;" " consider renaming it to analysis_options.yaml."); - /** - * An error code indicating that the enablePreviewDart2 setting is deprecated. - */ + /// An error code indicating that the enablePreviewDart2 setting is + /// deprecated. static const AnalysisOptionsHintCode PREVIEW_DART_2_SETTING_DEPRECATED = AnalysisOptionsHintCode('PREVIEW_DART_2_SETTING_DEPRECATED', "The 'enablePreviewDart2' setting is deprecated.", correction: "It is no longer necessary to explicitly enable Dart 2."); - /** - * An error code indicating that strong-mode: true is deprecated. - */ + /// An error code indicating that strong-mode: true is deprecated. static const AnalysisOptionsHintCode STRONG_MODE_SETTING_DEPRECATED = AnalysisOptionsHintCode('STRONG_MODE_SETTING_DEPRECATED', "The 'strong-mode: true' setting is deprecated.", correction: "It is no longer necessary to explicitly enable strong mode."); - /** - * An error code indicating that the enablePreviewDart2 setting is deprecated. - */ + /// An error code indicating that the enablePreviewDart2 setting is + /// deprecated. static const AnalysisOptionsHintCode SUPER_MIXINS_SETTING_DEPRECATED = AnalysisOptionsHintCode('SUPER_MIXINS_SETTING_DEPRECATED', "The 'enableSuperMixins' setting is deprecated.", correction: - "Support has been added to the language for 'mixin' based mixins."); + "Support has been added to the language for 'mixin' based " + 'mixins.'); - /** - * Initialize a newly created hint code to have the given [name]. - */ + /// Initialize a newly created hint code to have the given [name]. const AnalysisOptionsHintCode(String name, String message, {String correction}) : super.temporary(name, message, correction: correction); @@ -102,65 +87,51 @@ class AnalysisOptionsHintCode extends ErrorCode { ErrorType get type => ErrorType.HINT; } -/** - * The error codes used for warnings in analysis options files. The convention - * for this class is for the name of the error code to indicate the problem that - * caused the error to be generated and for the error message to explain what is - * wrong and, when appropriate, how the problem can be corrected. - */ +/// The error codes used for warnings in analysis options files. The convention +/// for this class is for the name of the error code to indicate the problem +/// that caused the error to be generated and for the error message to explain +/// what is wrong and, when appropriate, how the problem can be corrected. class AnalysisOptionsWarningCode extends ErrorCode { - /** - * An error code indicating that the given option is deprecated. - */ + /// An error code indicating that the given option is deprecated. static const AnalysisOptionsWarningCode ANALYSIS_OPTION_DEPRECATED = AnalysisOptionsWarningCode('ANALYSIS_OPTION_DEPRECATED', "The option '{0}' is no longer supported."); - /** - * An error code indicating a specified include file could not be found. - * - * Parameters: - * 0: the uri of the file to be included - * 1: the path of the file containing the include directive - */ + /// An error code indicating a specified include file could not be found. + /// + /// Parameters: + /// 0: the uri of the file to be included + /// 1: the path of the file containing the include directive static const AnalysisOptionsWarningCode INCLUDE_FILE_NOT_FOUND = AnalysisOptionsWarningCode('INCLUDE_FILE_NOT_FOUND', "The include file {0} in {1} cannot be found."); - /** - * An error code indicating a specified include file has a warning. - * - * Parameters: - * 0: the path of the file containing the warnings - * 1: the starting offset of the text in the file that contains the warning - * 2: the ending offset of the text in the file that contains the warning - * 3: the warning message - */ + /// An error code indicating a specified include file has a warning. + /// + /// Parameters: + /// 0: the path of the file containing the warnings + /// 1: the starting offset of the text in the file that contains the warning + /// 2: the ending offset of the text in the file that contains the warning + /// 3: the warning message static const AnalysisOptionsWarningCode INCLUDED_FILE_WARNING = AnalysisOptionsWarningCode('INCLUDED_FILE_WARNING', "Warning in the included options file {0}({1}..{2}): {3}"); - /** - * An error code indicating that a plugin is being configured with an invalid - * value for an option and a detail message is provided. - */ + /// An error code indicating that a plugin is being configured with an invalid + /// value for an option and a detail message is provided. static const AnalysisOptionsWarningCode INVALID_OPTION = AnalysisOptionsWarningCode( 'INVALID_OPTION', "Invalid option specified for '{0}': {1}"); - /** - * An error code indicating an invalid format for an options file section. - * - * Parameters: - * 0: the section name - */ + /// An error code indicating an invalid format for an options file section. + /// + /// Parameters: + /// 0: the section name static const AnalysisOptionsWarningCode INVALID_SECTION_FORMAT = AnalysisOptionsWarningCode( 'INVALID_SECTION_FORMAT', "Invalid format for the '{0}' section."); - /** - * An error code indicating that strong-mode: false is has been removed. - */ + /// An error code indicating that strong-mode: false is has been removed. static const AnalysisOptionsWarningCode SPEC_MODE_REMOVED = AnalysisOptionsWarningCode('SPEC_MODE_REMOVED', "The option 'strong-mode: false' is no longer supported.", @@ -168,77 +139,65 @@ class AnalysisOptionsWarningCode extends ErrorCode { "It's recommended to remove the 'strong-mode:' setting (and make " "your code Dart 2 compliant)."); - /** - * An error code indicating that an unrecognized error code is being used to - * specify an error filter. - * - * Parameters: - * 0: the unrecognized error code - */ + /// An error code indicating that an unrecognized error code is being used to + /// specify an error filter. + /// + /// Parameters: + /// 0: the unrecognized error code static const AnalysisOptionsWarningCode UNRECOGNIZED_ERROR_CODE = AnalysisOptionsWarningCode( 'UNRECOGNIZED_ERROR_CODE', "'{0}' isn't a recognized error code."); - /** - * An error code indicating that a plugin is being configured with an - * unsupported option where there is just one legal value. - * - * Parameters: - * 0: the plugin name - * 1: the unsupported option key - * 2: the legal value - */ + /// An error code indicating that a plugin is being configured with an + /// unsupported option where there is just one legal value. + /// + /// Parameters: + /// 0: the plugin name + /// 1: the unsupported option key + /// 2: the legal value static const AnalysisOptionsWarningCode UNSUPPORTED_OPTION_WITH_LEGAL_VALUE = AnalysisOptionsWarningCode( 'UNSUPPORTED_OPTION_WITH_LEGAL_VALUE', "The option '{1}' isn't supported by '{0}'. " "Try using the only supported option: '{2}'."); - /** - * An error code indicating that a plugin is being configured with an - * unsupported option and legal options are provided. - * - * Parameters: - * 0: the plugin name - * 1: the unsupported option key - * 2: legal values - */ + /// An error code indicating that a plugin is being configured with an + /// unsupported option and legal options are provided. + /// + /// Parameters: + /// 0: the plugin name + /// 1: the unsupported option key + /// 2: legal values static const AnalysisOptionsWarningCode UNSUPPORTED_OPTION_WITH_LEGAL_VALUES = AnalysisOptionsWarningCode('UNSUPPORTED_OPTION_WITH_LEGAL_VALUES', "The option '{1}' isn't supported by '{0}'.", correction: "Try using one of the supported options: {2}."); - /** - * An error code indicating that a plugin is being configured with an - * unsupported option and legal options are provided. - * - * Parameters: - * 0: the plugin name - * 1: the unsupported option key - */ + /// An error code indicating that a plugin is being configured with an + /// unsupported option and legal options are provided. + /// + /// Parameters: + /// 0: the plugin name + /// 1: the unsupported option key static const AnalysisOptionsWarningCode UNSUPPORTED_OPTION_WITHOUT_VALUES = AnalysisOptionsWarningCode( 'UNSUPPORTED_OPTION_WITHOUT_VALUES', "The option '{1}' isn't supported by '{0}'.", ); - /** - * An error code indicating that an option entry is being configured with an - * unsupported value. - * - * Parameters: - * 0: the option name - * 1: the unsupported value - * 2: legal values - */ + /// An error code indicating that an option entry is being configured with an + /// unsupported value. + /// + /// Parameters: + /// 0: the option name + /// 1: the unsupported value + /// 2: legal values static const AnalysisOptionsWarningCode UNSUPPORTED_VALUE = AnalysisOptionsWarningCode( 'UNSUPPORTED_VALUE', "The value '{1}' isn't supported by '{0}'.", correction: "Try using one of the supported options: {2}."); - /** - * Initialize a newly created warning code to have the given [name]. - */ + /// Initialize a newly created warning code to have the given [name]. const AnalysisOptionsWarningCode(String name, String message, {String correction}) : super.temporary(name, message, correction: correction); diff --git a/pkg/analyzer/lib/src/command_line/arguments.dart b/pkg/analyzer/lib/src/command_line/arguments.dart index 6678491d0fb8f..22734a45c22e9 100644 --- a/pkg/analyzer/lib/src/command_line/arguments.dart +++ b/pkg/analyzer/lib/src/command_line/arguments.dart @@ -55,9 +55,7 @@ void applyAnalysisOptionFlags(AnalysisOptionsImpl options, ArgResults args, } } -/** - * Use the command-line [args] to create a context builder. - */ +/// Use the command-line [args] to create a context builder. ContextBuilderOptions createContextBuilderOptions(ArgResults args) { ContextBuilderOptions builderOptions = ContextBuilderOptions(); builderOptions.argResults = args; @@ -101,11 +99,9 @@ ContextBuilderOptions createContextBuilderOptions(ArgResults args) { return builderOptions; } -/** - * Use the given [resourceProvider] and command-line [args] to create a Dart SDK - * manager. The manager will use summary information if [useSummaries] is `true` - * and if the summary information exists. - */ +/// Use the given [resourceProvider] and command-line [args] to create a Dart +/// SDK manager. The manager will use summary information if [useSummaries] is +/// `true` and if the summary information exists. DartSdkManager createDartSdkManager( ResourceProvider resourceProvider, bool useSummaries, ArgResults args) { String sdkPath = args[sdkPathOption]; @@ -121,14 +117,12 @@ DartSdkManager createDartSdkManager( canUseSummaries); } -/** - * Add the standard flags and options to the given [parser]. The standard flags - * are those that are typically used to control the way in which the code is - * analyzed. - * - * TODO(danrubel) Update DDC to support all the options defined in this method - * then remove the [ddc] named argument from this method. - */ +/// Add the standard flags and options to the given [parser]. The standard flags +/// are those that are typically used to control the way in which the code is +/// analyzed. +/// +/// TODO(danrubel) Update DDC to support all the options defined in this method +/// then remove the [ddc] named argument from this method. void defineAnalysisArguments(ArgParser parser, {bool hide = true, ddc = false}) { parser.addOption(sdkPathOption, @@ -160,8 +154,8 @@ void defineAnalysisArguments(ArgParser parser, parser.addMultiOption(defineVariableOption, abbr: 'D', help: - 'Define an environment declaration. For example, "-Dfoo=bar" defines an ' - 'environment declaration named "foo" whose value is "bar".', + 'Define an environment declaration. For example, "-Dfoo=bar" defines ' + 'an environment declaration named "foo" whose value is "bar".', hide: hide); parser.addOption(packagesOption, help: 'The path to the package resolution configuration file, which ' @@ -182,12 +176,10 @@ void defineAnalysisArguments(ArgParser parser, } } -/** - * Find arguments of the form -Dkey=value - * or argument pairs of the form -Dkey value - * and place those key/value pairs into [definedVariables]. - * Return a list of arguments with the key/value arguments removed. - */ +/// Find arguments of the form -Dkey=value +/// or argument pairs of the form -Dkey value +/// and place those key/value pairs into [definedVariables]. +/// Return a list of arguments with the key/value arguments removed. List extractDefinedVariables( List args, Map definedVariables) { //TODO(danrubel) extracting defined variables is already handled by the @@ -217,19 +209,17 @@ List extractDefinedVariables( return remainingArgs; } -/** - * Return a list of command-line arguments containing all of the given [args] - * that are defined by the given [parser]. An argument is considered to be - * defined by the parser if - * - it starts with '--' and the rest of the argument (minus any value - * introduced by '=') is the name of a known option, - * - it starts with '-' and the rest of the argument (minus any value - * introduced by '=') is the name of a known abbreviation, or - * - it starts with something other than '--' or '-'. - * - * This function allows command-line tools to implement the - * '--ignore-unrecognized-flags' option. - */ +/// Return a list of command-line arguments containing all of the given [args] +/// that are defined by the given [parser]. An argument is considered to be +/// defined by the parser if +/// - it starts with '--' and the rest of the argument (minus any value +/// introduced by '=') is the name of a known option, +/// - it starts with '-' and the rest of the argument (minus any value +/// introduced by '=') is the name of a known abbreviation, or +/// - it starts with something other than '--' or '-'. +/// +/// This function allows command-line tools to implement the +/// '--ignore-unrecognized-flags' option. List filterUnknownArguments(List args, ArgParser parser) { Set knownOptions = HashSet(); Set knownAbbreviations = HashSet(); @@ -269,10 +259,8 @@ List filterUnknownArguments(List args, ArgParser parser) { return filtered; } -/** - * Use the given [parser] to parse the given command-line [args], and return the - * result. - */ +/// Use the given [parser] to parse the given command-line [args], and return +/// the result. ArgResults parse( ResourceProvider provider, ArgParser parser, List args) { args = preprocessArgs(provider, args); @@ -282,12 +270,10 @@ ArgResults parse( return parser.parse(args); } -/** - * Preprocess the given list of command line [args]. - * If the final arg is `@file_path` (Bazel worker mode), - * then read in all the lines of that file and add those as args. - * Always returns a new modifiable list. - */ +/// Preprocess the given list of command line [args]. +/// If the final arg is `@file_path` (Bazel worker mode), +/// then read in all the lines of that file and add those as args. +/// Always returns a new modifiable list. List preprocessArgs(ResourceProvider provider, List args) { args = List.from(args); if (args.isEmpty) { diff --git a/pkg/analyzer/lib/src/context/context.dart b/pkg/analyzer/lib/src/context/context.dart index dcf313e38298b..ec731e7129139 100644 --- a/pkg/analyzer/lib/src/context/context.dart +++ b/pkg/analyzer/lib/src/context/context.dart @@ -11,9 +11,7 @@ import 'package:analyzer/src/generated/source.dart'; import 'package:analyzer/src/generated/type_system.dart' show TypeSystemImpl; import 'package:meta/meta.dart'; -/** - * An [AnalysisContext] in which analysis can be performed. - */ +/// An [AnalysisContext] in which analysis can be performed. class AnalysisContextImpl implements AnalysisContext { final SynchronousSession _synchronousSession; @@ -85,15 +83,11 @@ class AnalysisContextImpl implements AnalysisContext { } } -/** - * An [AnalysisContext] that only contains sources for a Dart SDK. - */ +/// An [AnalysisContext] that only contains sources for a Dart SDK. class SdkAnalysisContext extends AnalysisContextImpl { - /** - * Initialize a newly created SDK analysis context with the given [options]. - * Analysis options cannot be changed afterwards. If the given [options] are - * `null`, then default options are used. - */ + /// Initialize a newly created SDK analysis context with the given [options]. + /// Analysis options cannot be changed afterwards. If the given [options] are + /// `null`, then default options are used. SdkAnalysisContext(AnalysisOptions options, SourceFactory sourceFactory) : super(SynchronousSession(options, DeclaredVariables()), sourceFactory); } diff --git a/pkg/analyzer/lib/src/context/context_root.dart b/pkg/analyzer/lib/src/context/context_root.dart index 55747b1fe8060..2b058e58ab105 100644 --- a/pkg/analyzer/lib/src/context/context_root.dart +++ b/pkg/analyzer/lib/src/context/context_root.dart @@ -6,39 +6,27 @@ import 'package:analyzer/src/generated/utilities_general.dart'; import 'package:meta/meta.dart'; import 'package:path/path.dart' as path; -/** - * Information about the root directory associated with an analysis context. - * - * Clients may not extend, implement or mix-in this class. - */ +/// Information about the root directory associated with an analysis context. +/// +/// Clients may not extend, implement or mix-in this class. class ContextRoot { - /** - * The path context to use when manipulating paths. - */ + /// The path context to use when manipulating paths. final path.Context pathContext; - /** - * The absolute path of the root directory containing the files to be - * analyzed. - */ + /// The absolute path of the root directory containing the files to be + /// analyzed. final String root; - /** - * A list of the absolute paths of files and directories within the root - * directory that should not be analyzed. - */ + /// A list of the absolute paths of files and directories within the root + /// directory that should not be analyzed. final List exclude; - /** - * An informative value for the file path that the analysis options were read - * from. This value can be `null` if there is no analysis options file or if - * the location of the file has not yet been discovered. - */ + /// An informative value for the file path that the analysis options were read + /// from. This value can be `null` if there is no analysis options file or if + /// the location of the file has not yet been discovered. String optionsFilePath; - /** - * Initialize a newly created context root. - */ + /// Initialize a newly created context root. ContextRoot(this.root, this.exclude, {@required path.Context pathContext}) : pathContext = pathContext ?? path.context; @@ -59,12 +47,10 @@ class ContextRoot { return false; } - /** - * Return `true` if the file with the given [filePath] is contained within - * this context root. A file contained in a context root if it is within the - * context [root] neither explicitly excluded or within one of the excluded - * directories. - */ + /// Return `true` if the file with the given [filePath] is contained within + /// this context root. A file contained in a context root if it is within the + /// context [root] neither explicitly excluded or within one of the excluded + /// directories. bool containsFile(String filePath) { if (!pathContext.isWithin(root, filePath)) { return false; diff --git a/pkg/analyzer/lib/src/context/source.dart b/pkg/analyzer/lib/src/context/source.dart index 8f31594210c71..74a85dca2f8aa 100644 --- a/pkg/analyzer/lib/src/context/source.dart +++ b/pkg/analyzer/lib/src/context/source.dart @@ -13,25 +13,17 @@ import 'package:analyzer/src/generated/utilities_dart.dart' as utils; import 'package:analyzer/src/source/package_map_resolver.dart'; import 'package:analyzer/src/workspace/package_build.dart'; -/** - * Instances of the class `SourceFactory` resolve possibly relative URI's - * against an existing [Source]. - */ +/// Instances of the class `SourceFactory` resolve possibly relative URI's +/// against an existing [Source]. class SourceFactoryImpl implements SourceFactory { - /** - * The resolvers used to resolve absolute URI's. - */ + /// The resolvers used to resolve absolute URI's. final List resolvers; - /** - * Cache of mapping of absolute [Uri]s to [Source]s. - */ + /// Cache of mapping of absolute [Uri]s to [Source]s. final HashMap _absoluteUriToSourceCache = HashMap(); - /** - * Initialize a newly created source factory with the given absolute URI - * [resolvers]. - */ + /// Initialize a newly created source factory with the given absolute URI + /// [resolvers]. SourceFactoryImpl(this.resolvers); @override @@ -148,18 +140,17 @@ class SourceFactoryImpl implements SourceFactory { return null; } - /** - * Return a source object representing the URI that results from resolving - * the given (possibly relative) contained URI against the URI associated - * with an existing source object, or `null` if the URI could not be resolved. - * - * @param containingSource the source containing the given URI - * @param containedUri the (possibly relative) URI to be resolved against the - * containing source - * @return the source representing the contained URI - * @throws AnalysisException if either the contained URI is invalid or if it - * cannot be resolved against the source object's URI - */ + /// Return a source object representing the URI that results from resolving + /// the given (possibly relative) contained URI against the URI associated + /// with an existing source object, or `null` if the URI could not be + /// resolved. + /// + /// @param containingSource the source containing the given URI + /// @param containedUri the (possibly relative) URI to be resolved against the + /// containing source + /// @return the source representing the contained URI + /// @throws AnalysisException if either the contained URI is invalid or if it + /// cannot be resolved against the source object's URI Source _internalResolveUri(Source containingSource, Uri containedUri) { if (!containedUri.isAbsolute) { if (containingSource == null) { diff --git a/pkg/analyzer/lib/src/error/bool_expression_verifier.dart b/pkg/analyzer/lib/src/error/bool_expression_verifier.dart index 0acc357e7386b..9c21c567897a0 100644 --- a/pkg/analyzer/lib/src/error/bool_expression_verifier.dart +++ b/pkg/analyzer/lib/src/error/bool_expression_verifier.dart @@ -66,13 +66,10 @@ class BoolExpressionVerifier { ); } - /** - * Check for situations where the result of a method or function is used, when - * it returns 'void'. Or, in rare cases, when other types of expressions are - * void, such as identifiers. - * - * TODO(scheglov) Move this in a separate verifier. - */ + /// Check for situations where the result of a method or function is used, + /// when it returns 'void'. Or, in rare cases, when other types of expressions + /// are void, such as identifiers. + // TODO(scheglov) Move this in a separate verifier. bool _checkForUseOfVoidResult(Expression expression) { if (expression == null || !identical(expression.staticType, VoidTypeImpl.instance)) { diff --git a/pkg/analyzer/lib/src/error/duplicate_definition_verifier.dart b/pkg/analyzer/lib/src/error/duplicate_definition_verifier.dart index 9cabeb7209d5a..e90e5dedf931b 100644 --- a/pkg/analyzer/lib/src/error/duplicate_definition_verifier.dart +++ b/pkg/analyzer/lib/src/error/duplicate_definition_verifier.dart @@ -147,9 +147,7 @@ class DuplicateDefinitionVerifier { _checkClassMembers(node.declaredElement, node.members); } - /** - * Check that all of the parameters have unique names. - */ + /// Check that all of the parameters have unique names. void checkParameters(FormalParameterList node) { Map definedNames = HashMap(); for (FormalParameter parameter in node.parameters) { diff --git a/pkg/analyzer/lib/src/error/type_arguments_verifier.dart b/pkg/analyzer/lib/src/error/type_arguments_verifier.dart index 363543aa84bcb..b11c18d2be7eb 100644 --- a/pkg/analyzer/lib/src/error/type_arguments_verifier.dart +++ b/pkg/analyzer/lib/src/error/type_arguments_verifier.dart @@ -190,10 +190,8 @@ class TypeArgumentsVerifier { } } - /** - * Verify that the type arguments in the given [typeName] are all within - * their bounds. - */ + /// Verify that the type arguments in the given [typeName] are all within + /// their bounds. void _checkForTypeArgumentNotMatchingBounds(TypeName typeName) { var element = typeName.name.staticElement; var type = typeName.type; @@ -255,12 +253,10 @@ class TypeArgumentsVerifier { } } - /** - * Checks to ensure that the given list of type [arguments] does not have a - * type parameter as a type argument. The [errorCode] is either - * [CompileTimeErrorCode.INVALID_TYPE_ARGUMENT_IN_CONST_LIST] or - * [CompileTimeErrorCode.INVALID_TYPE_ARGUMENT_IN_CONST_MAP]. - */ + /// Checks to ensure that the given list of type [arguments] does not have a + /// type parameter as a type argument. The [errorCode] is either + /// [CompileTimeErrorCode.INVALID_TYPE_ARGUMENT_IN_CONST_LIST] or + /// [CompileTimeErrorCode.INVALID_TYPE_ARGUMENT_IN_CONST_MAP]. void _checkTypeArgumentConst( NodeList arguments, ErrorCode errorCode) { for (TypeAnnotation type in arguments) { @@ -288,10 +284,8 @@ class TypeArgumentsVerifier { } } - /** - * Verify that the given [typeArguments] are all within their bounds, as - * defined by the given [element]. - */ + /// Verify that the given [typeArguments] are all within their bounds, as + /// defined by the given [element]. void _checkTypeArguments(InvocationExpression node) { NodeList typeArgumentList = node.typeArguments?.arguments; if (typeArgumentList == null) { diff --git a/pkg/analyzer/lib/src/file_system/file_system.dart b/pkg/analyzer/lib/src/file_system/file_system.dart index a6f128f837d29..4709f040ef45c 100644 --- a/pkg/analyzer/lib/src/file_system/file_system.dart +++ b/pkg/analyzer/lib/src/file_system/file_system.dart @@ -6,13 +6,9 @@ import 'package:analyzer/file_system/file_system.dart'; import 'package:analyzer/src/generated/source.dart'; import 'package:analyzer/src/util/uri.dart'; -/** - * A [UriResolver] for [Resource]s. - */ +/// A [UriResolver] for [Resource]s. class ResourceUriResolver extends UriResolver { - /** - * The name of the `file` scheme. - */ + /// The name of the `file` scheme. static final String FILE_SCHEME = "file"; final ResourceProvider _provider; @@ -35,8 +31,6 @@ class ResourceUriResolver extends UriResolver { Uri restoreAbsolute(Source source) => _provider.pathContext.toUri(source.fullName); - /** - * Return `true` if the given [uri] is a `file` URI. - */ + /// Return `true` if the given [uri] is a `file` URI. static bool isFileUri(Uri uri) => uri.scheme == FILE_SCHEME; } diff --git a/pkg/analyzer/lib/src/lint/config.dart b/pkg/analyzer/lib/src/lint/config.dart index 159385c91bea0..b6c801c1b9b68 100644 --- a/pkg/analyzer/lib/src/lint/config.dart +++ b/pkg/analyzer/lib/src/lint/config.dart @@ -5,9 +5,7 @@ import 'package:analyzer/src/util/yaml.dart'; import 'package:yaml/yaml.dart'; -/** - * Parse the given map into a lint config. - */ +/// Parse the given map into a lint config. LintConfig parseConfig(YamlMap optionsMap) { if (optionsMap != null) { var options = getValue(optionsMap, 'linter'); @@ -19,10 +17,8 @@ LintConfig parseConfig(YamlMap optionsMap) { return null; } -/** - * Process the given option [fileContents] and produce a corresponding - * [LintConfig]. - */ +/// Process the given option [fileContents] and produce a corresponding +/// [LintConfig]. LintConfig processAnalysisOptionsFile(String fileContents, {String fileUrl}) { var yaml = loadYamlNode(fileContents, sourceUrl: fileUrl); if (yaml is YamlMap) { @@ -31,9 +27,7 @@ LintConfig processAnalysisOptionsFile(String fileContents, {String fileUrl}) { return null; } -/** - * The configuration of lint rules within an analysis options file. - */ +/// The configuration of lint rules within an analysis options file. abstract class LintConfig { factory LintConfig.parse(String source, {String sourceUrl}) => _LintConfig().._parse(source, sourceUrl: sourceUrl); @@ -45,9 +39,7 @@ abstract class LintConfig { List get ruleConfigs; } -/** - * The configuration of a single lint rule within an analysis options file. - */ +/// The configuration of a single lint rule within an analysis options file. abstract class RuleConfig { Map args = {}; String get group; diff --git a/pkg/analyzer/lib/src/lint/options_rule_validator.dart b/pkg/analyzer/lib/src/lint/options_rule_validator.dart index b0e7f64126483..ec7dc79a15637 100644 --- a/pkg/analyzer/lib/src/lint/options_rule_validator.dart +++ b/pkg/analyzer/lib/src/lint/options_rule_validator.dart @@ -11,57 +11,45 @@ import 'package:analyzer/src/plugin/options.dart'; import 'package:analyzer/src/util/yaml.dart'; import 'package:yaml/yaml.dart'; -/** - * A hint code indicating reference to a deprecated lint. - * - * Parameters: - * 0: the rule name - */ +/// A hint code indicating reference to a deprecated lint. +/// +/// Parameters: +/// 0: the rule name const AnalysisOptionsHintCode DEPRECATED_LINT_HINT = AnalysisOptionsHintCode( 'DEPRECATED_LINT_HINT', "'{0}' is a deprecated lint rule and should not be used"); -/** - * Duplicate rules. - * - * Parameters: - * 0: the rule name - */ +/// Duplicate rules. +/// +/// Parameters: +/// 0: the rule name const AnalysisOptionsHintCode DUPLICATE_RULE_HINT = AnalysisOptionsHintCode( 'DUPLICATE_RULE', "The rule {0} is already specified and doesn't need to be specified again.", correction: "Try removing all but one specification of the rule."); -/** - * An error code indicating an incompatible rule. - * - * Parameters: - * 0: the rule name - * 1: the incompatible rule - */ +/// An error code indicating an incompatible rule. +/// +/// Parameters: +/// 0: the rule name +/// 1: the incompatible rule const AnalysisOptionsWarningCode INCOMPATIBLE_LINT_WARNING = AnalysisOptionsWarningCode('INCOMPATIBLE_LINT_WARNING', "The rule '{0}' is incompatible with the rule '{1}'", correction: "Try removing one of the incompatible rules."); -/** - * An error code indicating an undefined lint rule. - * - * Parameters: - * 0: the rule name - */ +/// An error code indicating an undefined lint rule. +/// +/// Parameters: +/// 0: the rule name const AnalysisOptionsWarningCode UNDEFINED_LINT_WARNING = AnalysisOptionsWarningCode( 'UNDEFINED_LINT_WARNING', "'{0}' is not a recognized lint rule"); -/** - * Rule provider. - */ +/// Rule provider. typedef LintRuleProvider = Iterable Function(); -/** - * Validates `linter` rule configurations. - */ +/// Validates `linter` rule configurations. class LinterRuleOptionsValidator extends OptionsValidator { static const linter = 'linter'; static const rulesKey = 'rules'; diff --git a/pkg/analyzer/lib/src/lint/registry.dart b/pkg/analyzer/lib/src/lint/registry.dart index b6e23500a2de0..3fd2ff3b2682b 100644 --- a/pkg/analyzer/lib/src/lint/registry.dart +++ b/pkg/analyzer/lib/src/lint/registry.dart @@ -7,13 +7,9 @@ import 'dart:collection'; import 'package:analyzer/src/lint/config.dart'; import 'package:analyzer/src/lint/linter.dart'; -/** - * Registry of lint rules. - */ +/// Registry of lint rules. class Registry with IterableMixin { - /** - * The default registry to be used by clients. - */ + /// The default registry to be used by clients. static final Registry ruleRegistry = Registry(); /// A table mapping rule names to rules. @@ -22,37 +18,27 @@ class Registry with IterableMixin { @override Iterator get iterator => _ruleMap.values.iterator; - /** - * Return a list of the rules that are defined. - */ + /// Return a list of the rules that are defined. Iterable get rules => _ruleMap.values; - /** - * Return the lint rule with the given [name]. - */ + /// Return the lint rule with the given [name]. LintRule operator [](String name) => _ruleMap[name]; - /** - * Return a list of the lint rules explicitly enabled by the given [config]. - * - * For example: - * my_rule: true - * - * enables `my_rule`. - * - * Unspecified rules are treated as disabled by default. - */ + /// Return a list of the lint rules explicitly enabled by the given [config]. + /// + /// For example: + /// my_rule: true + /// + /// enables `my_rule`. + /// + /// Unspecified rules are treated as disabled by default. Iterable enabled(LintConfig config) => rules .where((rule) => config.ruleConfigs.any((rc) => rc.enables(rule.name))); - /** - * Return the lint rule with the given [name]. - */ + /// Return the lint rule with the given [name]. LintRule getRule(String name) => _ruleMap[name]; - /** - * Add the given lint [rule] to this registry. - */ + /// Add the given lint [rule] to this registry. void register(LintRule rule) { _ruleMap[rule.name] = rule; } diff --git a/pkg/analyzer/lib/src/manifest/manifest_validator.dart b/pkg/analyzer/lib/src/manifest/manifest_validator.dart index d7927e509d025..677e6806c480b 100644 --- a/pkg/analyzer/lib/src/manifest/manifest_validator.dart +++ b/pkg/analyzer/lib/src/manifest/manifest_validator.dart @@ -13,20 +13,14 @@ import 'manifest_values.dart'; import 'manifest_warning_code.dart'; class ManifestValidator { - /** - * The source representing the file being validated. - */ + /// The source representing the file being validated. final Source source; - /** - * Initialize a newly create validator to validate the content of the given - * [source]. - */ + /// Initialize a newly create validator to validate the content of the given + /// [source]. ManifestValidator(this.source); - /** - * Validate the [contents] of the Android Manifest file. - */ + /// Validate the [contents] of the Android Manifest file. List validate(String contents, bool checkManifest) { RecordingErrorListener recorder = RecordingErrorListener(); ErrorReporter reporter = ErrorReporter( @@ -70,9 +64,7 @@ class ManifestValidator { bool _hasFeatureCameraAutoFocus(List features) => features.any((f) => f.localName == HARDWARE_FEATURE_CAMERA_AUTOFOCUS); - /** - * Report an error for the given node. - */ + /// Report an error for the given node. void _reportErrorForNode( ErrorReporter reporter, Node node, dynamic key, ErrorCode errorCode, [List arguments]) { @@ -82,9 +74,7 @@ class ManifestValidator { errorCode, span.start.offset, span.length, arguments); } - /** - * Validate the 'activity' tags. - */ + /// Validate the 'activity' tags. _validateActivities(List activites, ErrorReporter reporter) { activites.forEach((activity) { var attributes = activity.attributes; @@ -104,9 +94,7 @@ class ManifestValidator { }); } - /** - * Validate the `uses-feature` tags. - */ + /// Validate the `uses-feature` tags. _validateFeatures(List features, ErrorReporter reporter) { var unsupported = features .where((element) => UNSUPPORTED_HARDWARE_FEATURES @@ -131,9 +119,7 @@ class ManifestValidator { }); } - /** - * Validate the `uses-permission` tags. - */ + /// Validate the `uses-permission` tags. _validatePermissions(List permissions, List features, ErrorReporter reporter) { permissions.forEach((permission) { @@ -158,9 +144,7 @@ class ManifestValidator { }); } - /** - * Validate the presence/absence of the touchscreen feature tag. - */ + /// Validate the presence/absence of the touchscreen feature tag. _validateTouchScreenFeature( List features, Element manifest, ErrorReporter reporter) { var feature = features.firstWhere( diff --git a/pkg/analyzer/lib/src/manifest/manifest_warning_code.dart b/pkg/analyzer/lib/src/manifest/manifest_warning_code.dart index 1987db01e1636..f4d5b8f058e98 100644 --- a/pkg/analyzer/lib/src/manifest/manifest_warning_code.dart +++ b/pkg/analyzer/lib/src/manifest/manifest_warning_code.dart @@ -4,54 +4,52 @@ import 'package:analyzer/error/error.dart'; -/** - * The error codes used for warnings in analysis options files. The convention - * for this class is for the name of the error code to indicate the problem that - * caused the error to be generated and for the error message to explain what is - * wrong and, when appropriate, how the problem can be corrected. - */ +/// The error codes used for warnings in analysis options files. The convention +/// for this class is for the name of the error code to indicate the problem +/// that caused the error to be generated and for the error message to explain +/// what is wrong and, when appropriate, how the problem can be corrected. class ManifestWarningCode extends ErrorCode { - /** - * A code indicating that a specified hardware feature is not supported on Chrome OS. - */ + /// A code indicating that a specified hardware feature is not supported on + /// Chrome OS. static const ManifestWarningCode UNSUPPORTED_CHROME_OS_HARDWARE = - ManifestWarningCode('UNSUPPORTED_CHROME_OS_HARDWARE', - "The feature {0} is not supported on Chrome OS, consider making it optional.", + ManifestWarningCode( + 'UNSUPPORTED_CHROME_OS_HARDWARE', + 'The feature {0} is not supported on Chrome OS, consider making it ' + 'optional.', correction: - "Try adding `android:required=\"false\"` for this feature."); + 'Try adding `android:required="false"` for this feature.'); - /** - * A code indicating that a specified feature is not supported on Chrome OS. - */ + /// A code indicating that a specified feature is not supported on Chrome OS. static const ManifestWarningCode UNSUPPORTED_CHROME_OS_FEATURE = - ManifestWarningCode('UNSUPPORTED_CHROME_OS_FEATURE', - 'The feature {0} is not supported on Chrome OS, consider making it optional.', + ManifestWarningCode( + 'UNSUPPORTED_CHROME_OS_FEATURE', + 'The feature {0} is not supported on Chrome OS, consider making it ' + 'optional.', correction: "Try changing to `android:required=\"false\"` for this " "feature."); - /** - * A code indicating that the touchscreen feature is not specified in the - * manifest. - */ + /// A code indicating that the touchscreen feature is not specified in the + /// manifest. static const ManifestWarningCode NO_TOUCHSCREEN_FEATURE = ManifestWarningCode( 'NO_TOUCHSCREEN_FEATURE', - "The default \"android.hardware.touchscreen\" needs to be optional for Chrome OS. ", + 'The default "android.hardware.touchscreen" needs to be optional for ' + 'Chrome OS. ', correction: "Consider adding " "" " to the manifest."); - /** - * A code indicating that a specified permission is not supported on Chrome OS. - */ + /// A code indicating that a specified permission is not supported on Chrome + /// OS. static const ManifestWarningCode PERMISSION_IMPLIES_UNSUPPORTED_HARDWARE = - ManifestWarningCode('PERMISSION_IMPLIES_UNSUPPORTED_HARDWARE', - "Permission makes app incompatible for Chrome OS, consider adding optional {0} feature tag, ", + ManifestWarningCode( + 'PERMISSION_IMPLIES_UNSUPPORTED_HARDWARE', + 'Permission makes app incompatible for Chrome OS, consider adding ' + 'optional {0} feature tag, ', correction: " Try adding ``."); - /** - * A code indicating that the camera permissions is not supported on Chrome OS. - */ + /// A code indicating that the camera permissions is not supported on Chrome + /// OS. static const ManifestWarningCode CAMERA_PERMISSIONS_INCOMPATIBLE = ManifestWarningCode( 'CAMERA_PERMISSIONS_INCOMPATIBLE', "Camera permissions make app incompatible for Chrome OS, consider adding " @@ -61,9 +59,7 @@ class ManifestWarningCode extends ErrorCode { "``."); - /** - * A code indicating that the activity is set to be non resizable. - */ + /// A code indicating that the activity is set to be non resizable. static const ManifestWarningCode NON_RESIZABLE_ACTIVITY = ManifestWarningCode( 'NON_RESIZABLE_ACTIVITY', "The `` element should be allowed to be resized to allow " @@ -71,9 +67,7 @@ class ManifestWarningCode extends ErrorCode { correction: "Consider declaring the corresponding " "activity element with `resizableActivity=\"true\"` attribute."); - /** - * A code indicating that the activity is locked to an orientation. - */ + /// A code indicating that the activity is locked to an orientation. static const ManifestWarningCode SETTING_ORIENTATION_ON_ACTIVITY = ManifestWarningCode( 'SETTING_ORIENTATION_ON_ACTIVITY', @@ -84,10 +78,8 @@ class ManifestWarningCode extends ErrorCode { "Consider declaring the corresponding activity element with" " `screenOrientation=\"unspecified\"` or `\"fullSensor\"` attribute."); - /** - * Initialize a newly created warning code to have the given [name], [message] - * and [correction]. - */ + /// Initialize a newly created warning code to have the given [name], + /// [message] and [correction]. const ManifestWarningCode(String name, String message, {String correction}) : super.temporary(name, message, correction: correction); diff --git a/pkg/analyzer/lib/src/pubspec/pubspec_validator.dart b/pkg/analyzer/lib/src/pubspec/pubspec_validator.dart index a7a0e3bd12087..d9cb6c6b92c15 100644 --- a/pkg/analyzer/lib/src/pubspec/pubspec_validator.dart +++ b/pkg/analyzer/lib/src/pubspec/pubspec_validator.dart @@ -12,52 +12,34 @@ import 'package:source_span/src/span.dart'; import 'package:yaml/yaml.dart'; class PubspecValidator { - /** - * The name of the sub-field (under `flutter`) whose value is a list of assets - * available to Flutter apps at runtime. - */ + /// The name of the sub-field (under `flutter`) whose value is a list of + /// assets available to Flutter apps at runtime. static const String ASSETS_FIELD = 'assets'; - /** - * The name of the field whose value is a map of dependencies. - */ + /// The name of the field whose value is a map of dependencies. static const String DEPENDENCIES_FIELD = 'dependencies'; - /** - * The name of the field whose value is a map of development dependencies. - */ + /// The name of the field whose value is a map of development dependencies. static const String DEV_DEPENDENCIES_FIELD = 'dev_dependencies'; - /** - * The name of the field whose value is a specification of Flutter-specific - * configuration data. - */ + /// The name of the field whose value is a specification of Flutter-specific + /// configuration data. static const String FLUTTER_FIELD = 'flutter'; - /** - * The name of the field whose value is the name of the package. - */ + /// The name of the field whose value is the name of the package. static const String NAME_FIELD = 'name'; - /** - * The resource provider used to access the file system. - */ + /// The resource provider used to access the file system. final ResourceProvider provider; - /** - * The source representing the file being validated. - */ + /// The source representing the file being validated. final Source source; - /** - * Initialize a newly create validator to validate the content of the given - * [source]. - */ + /// Initialize a newly create validator to validate the content of the given + /// [source]. PubspecValidator(this.provider, this.source); - /** - * Validate the given [contents]. - */ + /// Validate the given [contents]. List validate(Map contents) { RecordingErrorListener recorder = RecordingErrorListener(); ErrorReporter reporter = ErrorReporter( @@ -73,10 +55,8 @@ class PubspecValidator { return recorder.errors; } - /** - * Return `true` if an asset (file) exists at the given absolute, normalized - * [assetPath] or in a subdirectory of the parent of the file. - */ + /// Return `true` if an asset (file) exists at the given absolute, normalized + /// [assetPath] or in a subdirectory of the parent of the file. bool _assetExistsAtPath(String assetPath) { // Check for asset directories. Folder assetDirectory = provider.getFolder(assetPath); @@ -105,11 +85,9 @@ class PubspecValidator { return false; } - /** - * Return a map whose keys are the names of declared dependencies and whose - * values are the specifications of those dependencies. The map is extracted - * from the given [contents] using the given [key]. - */ + /// Return a map whose keys are the names of declared dependencies and whose + /// values are the specifications of those dependencies. The map is extracted + /// from the given [contents] using the given [key]. Map _getDeclaredDependencies( ErrorReporter reporter, Map contents, String key) { YamlNode field = contents[key]; @@ -123,9 +101,7 @@ class PubspecValidator { return {}; } - /** - * Report an error for the given node. - */ + /// Report an error for the given node. void _reportErrorForNode( ErrorReporter reporter, YamlNode node, ErrorCode errorCode, [List arguments]) { @@ -134,9 +110,7 @@ class PubspecValidator { errorCode, span.start.offset, span.length, arguments); } - /** - * Validate the value of the required `name` field. - */ + /// Validate the value of the required `name` field. void _validateDependencies( ErrorReporter reporter, Map contents) { Map declaredDependencies = @@ -152,9 +126,7 @@ class PubspecValidator { } } - /** - * Validate the value of the optional `flutter` field. - */ + /// Validate the value of the optional `flutter` field. void _validateFlutter( ErrorReporter reporter, Map contents) { YamlNode flutterField = contents[FLUTTER_FIELD]; @@ -211,9 +183,7 @@ class PubspecValidator { } } - /** - * Validate the value of the required `name` field. - */ + /// Validate the value of the required `name` field. void _validateName(ErrorReporter reporter, Map contents) { YamlNode nameField = contents[NAME_FIELD]; if (nameField == null) { diff --git a/pkg/analyzer/lib/src/pubspec/pubspec_warning_code.dart b/pkg/analyzer/lib/src/pubspec/pubspec_warning_code.dart index 12c8d467d8261..7e03b42cecf96 100644 --- a/pkg/analyzer/lib/src/pubspec/pubspec_warning_code.dart +++ b/pkg/analyzer/lib/src/pubspec/pubspec_warning_code.dart @@ -4,89 +4,70 @@ import 'package:analyzer/error/error.dart'; -/** - * The error codes used for warnings in analysis options files. The convention - * for this class is for the name of the error code to indicate the problem that - * caused the error to be generated and for the error message to explain what is - * wrong and, when appropriate, how the problem can be corrected. - */ +/// The error codes used for warnings in analysis options files. The convention +/// for this class is for the name of the error code to indicate the problem +/// that caused the error to be generated and for the error message to explain +/// what is wrong and, when appropriate, how the problem can be corrected. class PubspecWarningCode extends ErrorCode { - /** - * A code indicating that a specified asset does not exist. - * - * Parameters: - * 0: the path to the asset as given in the file. - */ + /// A code indicating that a specified asset does not exist. + /// + /// Parameters: + /// 0: the path to the asset as given in the file. static const PubspecWarningCode ASSET_DOES_NOT_EXIST = PubspecWarningCode( 'ASSET_DOES_NOT_EXIST', "The asset {0} does not exist.", correction: "Try creating the file or fixing the path to the file."); - /** - * A code indicating that a specified asset directory does not exist. - * - * Parameters: - * 0: the path to the asset directory as given in the file. - */ + /// A code indicating that a specified asset directory does not exist. + /// + /// Parameters: + /// 0: the path to the asset directory as given in the file. static const PubspecWarningCode ASSET_DIRECTORY_DOES_NOT_EXIST = PubspecWarningCode('ASSET_DIRECTORY_DOES_NOT_EXIST', "The asset directory {0} does not exist.", correction: "Try creating the directory or fixing the path to the " "directory."); - /** - * A code indicating that the value of the asset field is not a list. - */ + /// A code indicating that the value of the asset field is not a list. static const PubspecWarningCode ASSET_FIELD_NOT_LIST = PubspecWarningCode( 'ASSET_FIELD_NOT_LIST', - "The value of the 'asset' field is expected to be a list of relative file paths.", + "The value of the 'asset' field is expected to be a list of relative " + "file paths.", correction: "Try converting the value to be a list of relative file paths."); - /** - * A code indicating that an element in the asset list is not a string. - */ + /// A code indicating that an element in the asset list is not a string. static const PubspecWarningCode ASSET_NOT_STRING = PubspecWarningCode( 'ASSET_NOT_STRING', "Assets are expected to be a file paths (strings).", correction: "Try converting the value to be a string."); - /** - * A code indicating that the value of a dependencies field is not a map. - */ + /// A code indicating that the value of a dependencies field is not a map. static const PubspecWarningCode DEPENDENCIES_FIELD_NOT_MAP = PubspecWarningCode('DEPENDENCIES_FIELD_NOT_MAP', "The value of the '{0}' field is expected to be a map.", correction: "Try converting the value to be a map."); - /** - * A code indicating that the value of the flutter field is not a map. - */ + /// A code indicating that the value of the flutter field is not a map. static const PubspecWarningCode FLUTTER_FIELD_NOT_MAP = PubspecWarningCode( 'FLUTTER_FIELD_NOT_MAP', "The value of the 'flutter' field is expected to be a map.", correction: "Try converting the value to be a map."); - /** - * A code indicating that the name field is missing. - */ + /// A code indicating that the name field is missing. static const PubspecWarningCode MISSING_NAME = PubspecWarningCode( 'MISSING_NAME', "The name field is required but missing.", correction: "Try adding a field named 'name'."); - /** - * A code indicating that the name field is not a string. - */ + /// A code indicating that the name field is not a string. static const PubspecWarningCode NAME_NOT_STRING = PubspecWarningCode( 'NAME_NOT_STRING', "The value of the name field is expected to be a string.", correction: "Try converting the value to be a string."); - /** - * A code indicating that a package listed as a dev dependency is also listed - * as a normal dependency. - * - * Parameters: - * 0: the name of the package in the dev_dependency list. - */ + /// A code indicating that a package listed as a dev dependency is also listed + /// as a normal dependency. + /// + /// Parameters: + /// 0: the name of the package in the dev_dependency list. static const PubspecWarningCode UNNECESSARY_DEV_DEPENDENCY = PubspecWarningCode( 'UNNECESSARY_DEV_DEPENDENCY', @@ -94,10 +75,8 @@ class PubspecWarningCode extends ErrorCode { "normal dependency on that package.", correction: "Try removing the dev dependency."); - /** - * Initialize a newly created warning code to have the given [name], [message] - * and [correction]. - */ + /// Initialize a newly created warning code to have the given [name], + /// [message] and [correction]. const PubspecWarningCode(String name, String message, {String correction}) : super.temporary(name, message, correction: correction); diff --git a/pkg/analyzer/lib/src/services/lint.dart b/pkg/analyzer/lib/src/services/lint.dart index 2fdce7b8bc798..f65130ff480f2 100644 --- a/pkg/analyzer/lib/src/services/lint.dart +++ b/pkg/analyzer/lib/src/services/lint.dart @@ -35,9 +35,7 @@ abstract class Linter implements NodeLintRule { /// NOTE: this is set by the framework before visit begins. ErrorReporter reporter; - /** - * Return the lint code associated with this linter. - */ + /// Return the lint code associated with this linter. LintCode get lintCode => null; /// Linter name. diff --git a/pkg/analyzer/lib/src/source/package_map_provider.dart b/pkg/analyzer/lib/src/source/package_map_provider.dart index 69053ba0040e8..e4c93215b16c2 100644 --- a/pkg/analyzer/lib/src/source/package_map_provider.dart +++ b/pkg/analyzer/lib/src/source/package_map_provider.dart @@ -4,39 +4,29 @@ import 'package:analyzer/file_system/file_system.dart'; -/** - * Data structure output by PackageMapProvider. This contains both the package - * map and dependency information. - */ +/// Data structure output by PackageMapProvider. This contains both the package +/// map and dependency information. class PackageMapInfo { - /** - * The package map itself. This is a map from package name to a list of - * the folders containing source code for the package. - * - * `null` if an error occurred. - */ + /// The package map itself. This is a map from package name to a list of + /// the folders containing source code for the package. + /// + /// `null` if an error occurred. Map> packageMap; - /** - * Dependency information. This is a set of the paths which were consulted - * in order to generate the package map. If any of these files is - * modified, the package map will need to be regenerated. - */ + /// Dependency information. This is a set of the paths which were consulted + /// in order to generate the package map. If any of these files is + /// modified, the package map will need to be regenerated. Set dependencies; PackageMapInfo(this.packageMap, this.dependencies); } -/** - * A PackageMapProvider is an entity capable of determining the mapping from - * package name to source directory for a given folder. - */ +/// A PackageMapProvider is an entity capable of determining the mapping from +/// package name to source directory for a given folder. abstract class PackageMapProvider { - /** - * Compute a package map for the given folder, if possible. - * - * If a package map can't be computed (e.g. because an error occurred), a - * [PackageMapInfo] will still be returned, but its packageMap will be null. - */ + /// Compute a package map for the given folder, if possible. + /// + /// If a package map can't be computed (e.g. because an error occurred), a + /// [PackageMapInfo] will still be returned, but its packageMap will be null. PackageMapInfo computePackageMap(Folder folder); } diff --git a/pkg/analyzer/lib/src/source/package_map_resolver.dart b/pkg/analyzer/lib/src/source/package_map_resolver.dart index c618a29ac2c79..43d8ba4f6831d 100644 --- a/pkg/analyzer/lib/src/source/package_map_resolver.dart +++ b/pkg/analyzer/lib/src/source/package_map_resolver.dart @@ -9,33 +9,23 @@ import 'package:analyzer/src/generated/source.dart'; import 'package:analyzer/src/util/asserts.dart' as asserts; import 'package:path/path.dart' as pathos; -/** - * A [UriResolver] implementation for the `package:` scheme that uses a map of - * package names to their directories. - */ +/// A [UriResolver] implementation for the `package:` scheme that uses a map of +/// package names to their directories. class PackageMapUriResolver extends UriResolver { - /** - * The name of the `package` scheme. - */ + /// The name of the `package` scheme. static const String PACKAGE_SCHEME = "package"; - /** - * A table mapping package names to the path of the directories containing - * the package. - */ + /// A table mapping package names to the path of the directories containing + /// the package. final Map> packageMap; - /** - * The [ResourceProvider] for this resolver. - */ + /// The [ResourceProvider] for this resolver. final ResourceProvider resourceProvider; - /** - * Create a new [PackageMapUriResolver]. - * - * [packageMap] is a table mapping package names to the paths of the - * directories containing the package - */ + /// Create a new [PackageMapUriResolver]. + /// + /// [packageMap] is a table mapping package names to the paths of the + /// directories containing the package PackageMapUriResolver(this.resourceProvider, this.packageMap) { asserts.notNull(resourceProvider); asserts.notNull(packageMap); @@ -90,9 +80,7 @@ class PackageMapUriResolver extends UriResolver { return null; } - /** - * Returns `true` if [uri] is a `package` URI. - */ + /// Returns `true` if [uri] is a `package` URI. static bool isPackageUri(Uri uri) { return uri.scheme == PACKAGE_SCHEME; } diff --git a/pkg/analyzer/lib/src/source/source_resource.dart b/pkg/analyzer/lib/src/source/source_resource.dart index d450699c26622..e240e808293c5 100644 --- a/pkg/analyzer/lib/src/source/source_resource.dart +++ b/pkg/analyzer/lib/src/source/source_resource.dart @@ -13,55 +13,37 @@ import 'package:analyzer/src/generated/source.dart'; /// clients that convert all text to an internal format. typedef FileReadMode = String Function(String s); -/** - * A source that represents a file. - */ +/// A source that represents a file. class FileSource extends Source { - /** - * A function that changes the way that files are read off of disk. - */ + /// A function that changes the way that files are read off of disk. static FileReadMode fileReadMode = (String s) => s; - /** - * Map from encoded URI/filepath pair to a unique integer identifier. This - * identifier is used for equality tests and hash codes. - * - * The URI and filepath are joined into a pair by separating them with an '@' - * character. - */ + /// Map from encoded URI/filepath pair to a unique integer identifier. This + /// identifier is used for equality tests and hash codes. + /// + /// The URI and filepath are joined into a pair by separating them with an '@' + /// character. static final Map _idTable = HashMap(); - /** - * The URI from which this source was originally derived. - */ + /// The URI from which this source was originally derived. @override final Uri uri; - /** - * The unique ID associated with this source. - */ + /// The unique ID associated with this source. final int id; - /** - * The file represented by this source. - */ + /// The file represented by this source. final File file; - /** - * The cached absolute path of this source. - */ + /// The cached absolute path of this source. String _absolutePath; - /** - * The cached encoding for this source. - */ + /// The cached encoding for this source. String _encoding; - /** - * Initialize a newly created source object to represent the given [file]. If - * a [uri] is given, then it will be used as the URI from which the source was - * derived, otherwise a `file:` URI will be created based on the [file]. - */ + /// Initialize a newly created source object to represent the given [file]. If + /// a [uri] is given, then it will be used as the URI from which the source + /// was derived, otherwise a `file:` URI will be created based on the [file]. FileSource(File file, [Uri uri]) : this.uri = uri ?? file.toUri(), this.file = file, @@ -75,16 +57,14 @@ class FileSource extends Source { }); } - /** - * Get and return the contents and timestamp of the underlying file. - * - * Clients should consider using the method [AnalysisContext.getContents] - * because contexts can have local overrides of the content of a source that - * the source is not aware of. - * - * Throws an exception if the contents of this source could not be accessed. - * See [contents]. - */ + /// Get and return the contents and timestamp of the underlying file. + /// + /// Clients should consider using the method [AnalysisContext.getContents] + /// because contexts can have local overrides of the content of a source that + /// the source is not aware of. + /// + /// Throws an exception if the contents of this source could not be accessed. + /// See [contents]. TimestampedData get contentsFromFile { return TimestampedData( modificationStamp, fileReadMode(file.readAsStringSync())); diff --git a/pkg/analyzer/lib/src/string_source.dart b/pkg/analyzer/lib/src/string_source.dart index 811b493f546b4..df408cfd6f6da 100644 --- a/pkg/analyzer/lib/src/string_source.dart +++ b/pkg/analyzer/lib/src/string_source.dart @@ -5,13 +5,9 @@ import 'package:analyzer/src/generated/engine.dart' show TimestampedData; import 'package:analyzer/src/generated/source.dart'; -/** - * An implementation of [Source] that's based on an in-memory Dart string. - */ +/// An implementation of [Source] that's based on an in-memory Dart string. class StringSource extends Source { - /** - * The content of the source. - */ + /// The content of the source. final String _contents; @override @@ -47,10 +43,8 @@ class StringSource extends Source { @override UriKind get uriKind => UriKind.FILE_URI; - /** - * Return `true` if the given [object] is a string source that is equal to - * this source. - */ + /// Return `true` if the given [object] is a string source that is equal to + /// this source. @override bool operator ==(Object object) { return object is StringSource && diff --git a/pkg/analyzer/lib/src/summary/api_signature.dart b/pkg/analyzer/lib/src/summary/api_signature.dart index bfa5a20f5d3cd..4a6d40401a237 100644 --- a/pkg/analyzer/lib/src/summary/api_signature.dart +++ b/pkg/analyzer/lib/src/summary/api_signature.dart @@ -11,67 +11,51 @@ import 'package:convert/convert.dart'; import 'package:crypto/crypto.dart'; import 'package:pub_semver/pub_semver.dart'; -/** - * An instance of [ApiSignature] collects data in the form of primitive types - * (strings, ints, bools, etc.) from a summary "builder" object, and uses them - * to generate an MD5 signature of a the non-informative parts of the summary - * (i.e. those parts representing the API of the code being summarized). - * - * Note that the data passed to the MD5 signature algorithm is untyped. So, for - * instance, an API signature built from a sequence of `false` booleans is - * likely to match an API signature built from a sequence of zeros. The caller - * should take this into account; e.g. if a data structure may be represented - * either by a boolean or an int, the caller should encode a tag distinguishing - * the two representations before encoding the data. - */ +/// An instance of [ApiSignature] collects data in the form of primitive types +/// (strings, ints, bools, etc.) from a summary "builder" object, and uses them +/// to generate an MD5 signature of a the non-informative parts of the summary +/// (i.e. those parts representing the API of the code being summarized). +/// +/// Note that the data passed to the MD5 signature algorithm is untyped. So, +/// for instance, an API signature built from a sequence of `false` booleans is +/// likely to match an API signature built from a sequence of zeros. The caller +/// should take this into account; e.g. if a data structure may be represented +/// either by a boolean or an int, the caller should encode a tag distinguishing +/// the two representations before encoding the data. class ApiSignature { - /** - * Version number of the code in this class. Any time this class is changed - * in a way that affects the data collected in [_data], this version number - * should be incremented, so that a summary signed by a newer version of the - * signature algorithm won't accidentally have the same signature as a summary - * signed by an older version. - */ + /// Version number of the code in this class. Any time this class is changed + /// in a way that affects the data collected in [_data], this version number + /// should be incremented, so that a summary signed by a newer version of the + /// signature algorithm won't accidentally have the same signature as a + /// summary signed by an older version. static const int _VERSION = 0; - /** - * Data accumulated so far. - */ + /// Data accumulated so far. ByteData _data = ByteData(4096); - /** - * Offset into [_data] where the next byte should be written. - */ + /// Offset into [_data] where the next byte should be written. int _offset = 0; - /** - * Create an [ApiSignature] which is ready to accept data. - */ + /// Create an [ApiSignature] which is ready to accept data. ApiSignature() { addInt(_VERSION); } - /** - * For testing only: create an [ApiSignature] which doesn't include any - * version information. This makes it easier to unit tests, since the data - * is stable even if [_VERSION] is changed. - */ + /// For testing only: create an [ApiSignature] which doesn't include any + /// version information. This makes it easier to unit tests, since the data + /// is stable even if [_VERSION] is changed. ApiSignature.unversioned(); - /** - * Collect a boolean value. - */ + /// Collect a boolean value. void addBool(bool b) { _makeRoom(1); _data.setUint8(_offset, b ? 1 : 0); _offset++; } - /** - * Collect a sequence of arbitrary bytes. Note that the length is not - * collected, so for example `addBytes([1, 2]);` will have the same effect as - * `addBytes([1]); addBytes([2]);`. - */ + /// Collect a sequence of arbitrary bytes. Note that the length is not + /// collected, so for example `addBytes([1, 2]);` will have the same effect as + /// `addBytes([1]); addBytes([2]);`. void addBytes(List bytes) { int length = bytes.length; _makeRoom(length); @@ -81,18 +65,14 @@ class ApiSignature { _offset += length; } - /** - * Collect a double-precision floating point value. - */ + /// Collect a double-precision floating point value. void addDouble(double d) { _makeRoom(8); _data.setFloat64(_offset, d, Endian.little); _offset += 8; } - /** - * Collect a [FeatureSet]. - */ + /// Collect a [FeatureSet]. void addFeatureSet(FeatureSet featureSet) { var knownFeatures = ExperimentStatus.knownFeatures; addInt(knownFeatures.length); @@ -101,65 +81,49 @@ class ApiSignature { } } - /** - * Collect a 32-bit unsigned integer value. - */ + /// Collect a 32-bit unsigned integer value. void addInt(int i) { _makeRoom(4); _data.setUint32(_offset, i, Endian.little); _offset += 4; } - /** - * Collect a language version. - */ + /// Collect a language version. void addLanguageVersion(Version version) { addInt(version.major); addInt(version.minor); } - /** - * Collect a string. - */ + /// Collect a string. void addString(String s) { List bytes = utf8.encode(s); addInt(bytes.length); addBytes(bytes); } - /** - * Collect the given [Uint32List]. - */ + /// Collect the given [Uint32List]. void addUint32List(Uint32List data) { addBytes(data.buffer.asUint8List()); } - /** - * For testing only: retrieve the internal representation of the data that - * has been collected. - */ + /// For testing only: retrieve the internal representation of the data that + /// has been collected. List getBytes_forDebug() { return Uint8List.view(_data.buffer, 0, _offset).toList(); } - /** - * Return the bytes of the MD5 hash of the data collected so far. - */ + /// Return the bytes of the MD5 hash of the data collected so far. List toByteList() { return md5.convert(Uint8List.view(_data.buffer, 0, _offset)).bytes; } - /** - * Return a hex-encoded MD5 signature of the data collected so far. - */ + /// Return a hex-encoded MD5 signature of the data collected so far. String toHex() { return hex.encode(toByteList()); } - /** - * Ensure that [spaceNeeded] bytes can be added to [_data] at [_offset] - * (copying it to a larger object if necessary). - */ + /// Ensure that [spaceNeeded] bytes can be added to [_data] at [_offset] + /// (copying it to a larger object if necessary). void _makeRoom(int spaceNeeded) { int oldLength = _data.lengthInBytes; if (_offset + spaceNeeded > oldLength) { diff --git a/pkg/analyzer/lib/src/summary/base.dart b/pkg/analyzer/lib/src/summary/base.dart index 93215cf9960c9..0174fedcf2f39 100644 --- a/pkg/analyzer/lib/src/summary/base.dart +++ b/pkg/analyzer/lib/src/summary/base.dart @@ -2,86 +2,68 @@ // 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. -/** - * Base functionality which code generated summary classes are built upon. - */ +/// Base functionality which code generated summary classes are built upon. library analyzer.src.summary.base; -/** - * Annotation used in the summary IDL to indicate the id of a field. The set - * of ids used by a class must cover the contiguous range from 0 to N-1, where - * N is the number of fields. - * - * In order to preserve forwards and backwards compatibility, id numbers must - * be stable between releases. So when new fields are added they should take - * the next available id without renumbering other fields. - */ +/// Annotation used in the summary IDL to indicate the id of a field. The set +/// of ids used by a class must cover the contiguous range from 0 to N-1, where +/// N is the number of fields. +/// +/// In order to preserve forwards and backwards compatibility, id numbers must +/// be stable between releases. So when new fields are added they should take +/// the next available id without renumbering other fields. class Id { final int value; const Id(this.value); } -/** - * Instances of this class represent data that has been read from a summary. - */ +/// Instances of this class represent data that has been read from a summary. abstract class SummaryClass { - /** - * Translate the data in this class into a JSON map, whose keys are the names - * of fields and whose values are the data stored in those fields, - * recursively converted into JSON. - * - * Fields containing their default value are elided. - * - * Intended for testing and debugging only. - */ + /// Translate the data in this class into a JSON map, whose keys are the names + /// of fields and whose values are the data stored in those fields, + /// recursively converted into JSON. + /// + /// Fields containing their default value are elided. + /// + /// Intended for testing and debugging only. Map toJson(); - /** - * Translate the data in this class into a map whose keys are the names of - * fields and whose values are the data stored in those fields. - * - * Intended for testing and debugging only. - */ + /// Translate the data in this class into a map whose keys are the names of + /// fields and whose values are the data stored in those fields. + /// + /// Intended for testing and debugging only. Map toMap(); } -/** - * Annotation used in the summary IDL to indicate that a summary class can be - * the top level object in an encoded summary. - */ +/// Annotation used in the summary IDL to indicate that a summary class can be +/// the top level object in an encoded summary. class TopLevel { - /** - * If non-null, identifier that will be stored in bytes 4-7 of the file, - * prior all other file data. Must be exactly 4 Latin1 characters. - */ + /// If non-null, identifier that will be stored in bytes 4-7 of the file, + /// prior all other file data. Must be exactly 4 Latin1 characters. final String fileIdentifier; const TopLevel([this.fileIdentifier]); } -/** - * Annotation used in the summary IDL to indicate the field name that is used - * to distinguish variants, or logical views on the same physical layout of - * fields. - */ +/// Annotation used in the summary IDL to indicate the field name that is used +/// to distinguish variants, or logical views on the same physical layout of +/// fields. class Variant { final String fieldName; const Variant(this.fieldName); } -/** - * Annotation used in the summary IDL to indicate the id of a field that - * represents a logical field. The set of ids used by a class must cover the - * contiguous range from 0 to N-1, where N is the number of fields. All logical - * fields must have the same type, which will become the type of the actual - * field. - * - * In order to preserve forwards and backwards compatibility, id numbers must - * be stable between releases. So when new fields are added they should take - * the next available id without renumbering other fields. - */ +/// Annotation used in the summary IDL to indicate the id of a field that +/// represents a logical field. The set of ids used by a class must cover the +/// contiguous range from 0 to N-1, where N is the number of fields. All +/// logical fields must have the same type, which will become the type of the +/// actual field. +/// +/// In order to preserve forwards and backwards compatibility, id numbers must +/// be stable between releases. So when new fields are added they should take +/// the next available id without renumbering other fields. class VariantId { /// The ID of the actual field. final int value; diff --git a/pkg/analyzer/lib/src/summary/flat_buffers.dart b/pkg/analyzer/lib/src/summary/flat_buffers.dart index 40194dc7e7c90..b939bb9e7f70a 100644 --- a/pkg/analyzer/lib/src/summary/flat_buffers.dart +++ b/pkg/analyzer/lib/src/summary/flat_buffers.dart @@ -7,11 +7,9 @@ import 'dart:convert'; import 'dart:math'; import 'dart:typed_data'; -/** - * Reader of lists of boolean values. - * - * The returned unmodifiable lists lazily read values on access. - */ +/// Reader of lists of boolean values. +/// +/// The returned unmodifiable lists lazily read values on access. class BoolListReader extends Reader> { const BoolListReader(); @@ -23,9 +21,7 @@ class BoolListReader extends Reader> { _FbBoolList(bc, bc.derefObject(offset)); } -/** - * The reader of booleans. - */ +/// The reader of booleans. class BoolReader extends Reader { const BoolReader() : super(); @@ -36,9 +32,7 @@ class BoolReader extends Reader { bool read(BufferContext bc, int offset) => bc._getInt8(offset) != 0; } -/** - * Buffer with data and some context about it. - */ +/// Buffer with data and some context about it. class BufferContext { final ByteData _buffer; @@ -69,10 +63,8 @@ class BufferContext { int _getUint8(int offset) => _buffer.getUint8(offset); - /** - * If the [byteList] is already a [Uint8List] return it. - * Otherwise return a [Uint8List] copy of the [byteList]. - */ + /// If the [byteList] is already a [Uint8List] return it. + /// Otherwise return a [Uint8List] copy of the [byteList]. static Uint8List _asUint8List(List byteList) { if (byteList is Uint8List) { return byteList; @@ -82,46 +74,32 @@ class BufferContext { } } -/** - * Class that helps building flat buffers. - */ +/// Class that helps building flat buffers. class Builder { final int initialSize; - /** - * The list of field tails, reused by [_VTable] instances. - */ + /// The list of field tails, reused by [_VTable] instances. final Int32List _reusedFieldTails = Int32List(1024); - /** - * The list of field offsets, reused by [_VTable] instances. - */ + /// The list of field offsets, reused by [_VTable] instances. final Int32List _reusedFieldOffsets = Int32List(1024); - /** - * The list of existing VTable(s). - */ + /// The list of existing VTable(s). final List<_VTable> _vTables = <_VTable>[]; ByteData _buf; - /** - * The maximum alignment that has been seen so far. If [_buf] has to be - * reallocated in the future (to insert room at its start for more bytes) the - * reallocation will need to be a multiple of this many bytes. - */ + /// The maximum alignment that has been seen so far. If [_buf] has to be + /// reallocated in the future (to insert room at its start for more bytes) the + /// reallocation will need to be a multiple of this many bytes. int _maxAlign; - /** - * The number of bytes that have been written to the buffer so far. The - * most recently written byte is this many bytes from the end of [_buf]. - */ + /// The number of bytes that have been written to the buffer so far. The + /// most recently written byte is this many bytes from the end of [_buf]. int _tail; - /** - * The location of the end of the current table, measured in bytes from the - * end of [_buf], or `null` if a table is not currently being built. - */ + /// The location of the end of the current table, measured in bytes from the + /// end of [_buf], or `null` if a table is not currently being built. int _currentTableEndTail; _VTable _currentVTable; @@ -134,11 +112,9 @@ class Builder { reset(); } - /** - * Add the [field] with the given boolean [value]. The field is not added if - * the [value] is equal to [def]. Booleans are stored as 8-bit fields with - * `0` for `false` and `1` for `true`. - */ + /// Add the [field] with the given boolean [value]. The field is not added if + /// the [value] is equal to [def]. Booleans are stored as 8-bit fields with + /// `0` for `false` and `1` for `true`. void addBool(int field, bool value, [bool def]) { _ensureCurrentVTable(); if (value != null && value != def) { @@ -149,9 +125,7 @@ class Builder { } } - /** - * Add the [field] with the given 64-bit float [value]. - */ + /// Add the [field] with the given 64-bit float [value]. void addFloat64(int field, double value, [double def]) { _ensureCurrentVTable(); if (value != null && value != def) { @@ -162,10 +136,8 @@ class Builder { } } - /** - * Add the [field] with the given 32-bit signed integer [value]. The field is - * not added if the [value] is equal to [def]. - */ + /// Add the [field] with the given 32-bit signed integer [value]. The field + /// is not added if the [value] is equal to [def]. void addInt32(int field, int value, [int def]) { _ensureCurrentVTable(); if (value != null && value != def) { @@ -176,10 +148,8 @@ class Builder { } } - /** - * Add the [field] with the given 8-bit signed integer [value]. The field is - * not added if the [value] is equal to [def]. - */ + /// Add the [field] with the given 8-bit signed integer [value]. The field is + /// not added if the [value] is equal to [def]. void addInt8(int field, int value, [int def]) { _ensureCurrentVTable(); if (value != null && value != def) { @@ -190,9 +160,7 @@ class Builder { } } - /** - * Add the [field] referencing an object with the given [offset]. - */ + /// Add the [field] referencing an object with the given [offset]. void addOffset(int field, Offset offset) { _ensureCurrentVTable(); if (offset != null) { @@ -202,10 +170,8 @@ class Builder { } } - /** - * Add the [field] with the given 32-bit unsigned integer [value]. The field - * is not added if the [value] is equal to [def]. - */ + /// Add the [field] with the given 32-bit unsigned integer [value]. The field + /// is not added if the [value] is equal to [def]. void addUint32(int field, int value, [int def]) { _ensureCurrentVTable(); if (value != null && value != def) { @@ -216,10 +182,8 @@ class Builder { } } - /** - * Add the [field] with the given 8-bit unsigned integer [value]. The field - * is not added if the [value] is equal to [def]. - */ + /// Add the [field] with the given 8-bit unsigned integer [value]. The field + /// is not added if the [value] is equal to [def]. void addUint8(int field, int value, [int def]) { _ensureCurrentVTable(); if (value != null && value != def) { @@ -230,9 +194,7 @@ class Builder { } } - /** - * End the current table and return its offset. - */ + /// End the current table and return its offset. Offset endTable() { if (_currentVTable == null) { throw StateError('Start a table before ending it.'); @@ -271,13 +233,11 @@ class Builder { return Offset(tableTail); } - /** - * Finish off the creation of the buffer. The given [offset] is used as the - * root object offset, and usually references directly or indirectly every - * written object. If [fileIdentifier] is specified (and not `null`), it is - * interpreted as a 4-byte Latin-1 encoded string that should be placed at - * bytes 4-7 of the file. - */ + /// Finish off the creation of the buffer. The given [offset] is used as the + /// root object offset, and usually references directly or indirectly every + /// written object. If [fileIdentifier] is specified (and not `null`), it is + /// interpreted as a 4-byte Latin-1 encoded string that should be placed at + /// bytes 4-7 of the file. Uint8List finish(Offset offset, [String fileIdentifier]) { _prepare(max(4, _maxAlign), fileIdentifier == null ? 1 : 2); int alignedTail = _tail + ((-_tail) % _maxAlign); @@ -291,42 +251,32 @@ class Builder { return _buf.buffer.asUint8List(_buf.lengthInBytes - alignedTail); } - /** - * This is a low-level method, it should not be invoked by clients. - */ + /// This is a low-level method, it should not be invoked by clients. Uint8List lowFinish() { int alignedTail = _tail + ((-_tail) % _maxAlign); return _buf.buffer.asUint8List(_buf.lengthInBytes - alignedTail); } - /** - * This is a low-level method, it should not be invoked by clients. - */ + /// This is a low-level method, it should not be invoked by clients. void lowReset() { _buf = ByteData(initialSize); _maxAlign = 1; _tail = 0; } - /** - * This is a low-level method, it should not be invoked by clients. - */ + /// This is a low-level method, it should not be invoked by clients. void lowWriteUint32(int value) { _prepare(4, 1); _setUint32AtTail(_buf, _tail, value); } - /** - * This is a low-level method, it should not be invoked by clients. - */ + /// This is a low-level method, it should not be invoked by clients. void lowWriteUint8(int value) { _prepare(1, 1); _buf.setUint8(_buf.lengthInBytes - _tail, value); } - /** - * Reset the builder and make it ready for filling a new buffer. - */ + /// Reset the builder and make it ready for filling a new buffer. void reset() { _buf = ByteData(initialSize); _maxAlign = 1; @@ -334,9 +284,7 @@ class Builder { _currentVTable = null; } - /** - * Start a new table. Must be finished with [endTable] invocation. - */ + /// Start a new table. Must be finished with [endTable] invocation. void startTable() { if (_currentVTable != null) { throw StateError('Inline tables are not supported.'); @@ -345,9 +293,7 @@ class Builder { _currentTableEndTail = _tail; } - /** - * Write the given list of [values]. - */ + /// Write the given list of [values]. Offset writeList(List values) { _ensureNoVTable(); _prepare(4, 1 + values.length); @@ -362,9 +308,7 @@ class Builder { return result; } - /** - * Write the given list of boolean [values]. - */ + /// Write the given list of boolean [values]. Offset writeListBool(List values) { int bitLength = values.length; int padding = (-bitLength) % 8; @@ -394,9 +338,7 @@ class Builder { return writeListUint8(bytes); } - /** - * Write the given list of 64-bit float [values]. - */ + /// Write the given list of 64-bit float [values]. Offset writeListFloat64(List values) { _ensureNoVTable(); _prepare(8, 1 + values.length); @@ -411,9 +353,7 @@ class Builder { return result; } - /** - * Write the given list of signed 32-bit integer [values]. - */ + /// Write the given list of signed 32-bit integer [values]. Offset writeListInt32(List values) { _ensureNoVTable(); _prepare(4, 1 + values.length); @@ -428,9 +368,7 @@ class Builder { return result; } - /** - * Write the given list of unsigned 32-bit integer [values]. - */ + /// Write the given list of unsigned 32-bit integer [values]. Offset writeListUint32(List values) { _ensureNoVTable(); _prepare(4, 1 + values.length); @@ -445,9 +383,7 @@ class Builder { return result; } - /** - * Write the given list of unsigned 8-bit integer [values]. - */ + /// Write the given list of unsigned 8-bit integer [values]. Offset writeListUint8(List values) { _ensureNoVTable(); _prepare(4, 1, additionalBytes: values.length); @@ -462,10 +398,8 @@ class Builder { return result; } - /** - * Write the given string [value] and return its [Offset], or `null` if - * the [value] is equal to [def]. - */ + /// Write the given string [value] and return its [Offset], or `null` if + /// the [value] is equal to [def]. Offset writeString(String value, [String def]) { _ensureNoVTable(); if (value != def) { @@ -486,18 +420,14 @@ class Builder { return null; } - /** - * Throw an exception if there is not currently a vtable. - */ + /// Throw an exception if there is not currently a vtable. void _ensureCurrentVTable() { if (_currentVTable == null) { throw StateError('Start a table before adding values.'); } } - /** - * Throw an exception if there is currently a vtable. - */ + /// Throw an exception if there is currently a vtable. void _ensureNoVTable() { if (_currentVTable != null) { throw StateError( @@ -505,11 +435,9 @@ class Builder { } } - /** - * Prepare for writing the given [count] of scalars of the given [size]. - * Additionally allocate the specified [additionalBytes]. Update the current - * tail pointer to point at the allocated space. - */ + /// Prepare for writing the given [count] of scalars of the given [size]. + /// Additionally allocate the specified [additionalBytes]. Update the current + /// tail pointer to point at the allocated space. void _prepare(int size, int count, {int additionalBytes = 0}) { // Update the alignment. if (_maxAlign < size) { @@ -538,9 +466,7 @@ class Builder { _tail += bufSize; } - /** - * Record the offset of the given [field]. - */ + /// Record the offset of the given [field]. void _trackField(int field) { _currentVTable.addField(field, _tail); } @@ -562,11 +488,9 @@ class Builder { } } -/** - * The reader of lists of 64-bit float values. - * - * The returned unmodifiable lists lazily read values on access. - */ +/// The reader of lists of 64-bit float values. +/// +/// The returned unmodifiable lists lazily read values on access. class Float64ListReader extends Reader> { const Float64ListReader(); @@ -578,9 +502,7 @@ class Float64ListReader extends Reader> { _FbFloat64List(bc, bc.derefObject(offset)); } -/** - * The reader of 64-bit floats. - */ +/// The reader of 64-bit floats. class Float64Reader extends Reader { const Float64Reader() : super(); @@ -591,9 +513,7 @@ class Float64Reader extends Reader { double read(BufferContext bc, int offset) => bc._getFloat64(offset); } -/** - * The reader of signed 32-bit integers. - */ +/// The reader of signed 32-bit integers. class Int32Reader extends Reader { const Int32Reader() : super(); @@ -604,9 +524,7 @@ class Int32Reader extends Reader { int read(BufferContext bc, int offset) => bc._getInt32(offset); } -/** - * The reader of 8-bit signed integers. - */ +/// The reader of 8-bit signed integers. class Int8Reader extends Reader { const Int8Reader() : super(); @@ -617,11 +535,9 @@ class Int8Reader extends Reader { int read(BufferContext bc, int offset) => bc._getInt8(offset); } -/** - * The reader of lists of objects. - * - * The returned unmodifiable lists lazily read objects on access. - */ +/// The reader of lists of objects. +/// +/// The returned unmodifiable lists lazily read objects on access. class ListReader extends Reader> { final Reader _elementReader; @@ -635,34 +551,25 @@ class ListReader extends Reader> { _FbGenericList(_elementReader, bc, bc.derefObject(offset)); } -/** - * The offset from the end of the buffer to a serialized object of the type [T]. - */ +/// The offset from the end of the buffer to a serialized object of the type +/// [T]. class Offset { final int _tail; Offset(this._tail); } -/** - * Object that can read a value at a [BufferContext]. - */ +/// Object that can read a value at a [BufferContext]. abstract class Reader { const Reader(); - /** - * The size of the value in bytes. - */ + /// The size of the value in bytes. int get size; - /** - * Read the value at the given [offset] in [bc]. - */ + /// Read the value at the given [offset] in [bc]. T read(BufferContext bc, int offset); - /** - * Read the value of the given [field] in the given [object]. - */ + /// Read the value of the given [field] in the given [object]. T vTableGet(BufferContext object, int offset, int field, [T defaultValue]) { int vTableSOffset = object._getInt32(offset); int vTableOffset = offset - vTableSOffset; @@ -679,9 +586,7 @@ abstract class Reader { } } -/** - * The reader of string values. - */ +/// The reader of string values. class StringReader extends Reader { const StringReader() : super(); @@ -710,18 +615,14 @@ class StringReader extends Reader { } } -/** - * An abstract reader for tables. - */ +/// An abstract reader for tables. abstract class TableReader extends Reader { const TableReader(); @override int get size => 4; - /** - * Return the object at [offset]. - */ + /// Return the object at [offset]. T createObject(BufferContext bc, int offset); @override @@ -731,11 +632,9 @@ abstract class TableReader extends Reader { } } -/** - * Reader of lists of unsigned 32-bit integer values. - * - * The returned unmodifiable lists lazily read values on access. - */ +/// Reader of lists of unsigned 32-bit integer values. +/// +/// The returned unmodifiable lists lazily read values on access. class Uint32ListReader extends Reader> { const Uint32ListReader(); @@ -747,9 +646,7 @@ class Uint32ListReader extends Reader> { _FbUint32List(bc, bc.derefObject(offset)); } -/** - * The reader of unsigned 32-bit integers. - */ +/// The reader of unsigned 32-bit integers. class Uint32Reader extends Reader { const Uint32Reader() : super(); @@ -760,11 +657,9 @@ class Uint32Reader extends Reader { int read(BufferContext bc, int offset) => bc._getUint32(offset); } -/** - * Reader of lists of unsigned 8-bit integer values. - * - * The returned unmodifiable lists lazily read values on access. - */ +/// Reader of lists of unsigned 8-bit integer values. +/// +/// The returned unmodifiable lists lazily read values on access. class Uint8ListReader extends Reader> { const Uint8ListReader(); @@ -776,9 +671,7 @@ class Uint8ListReader extends Reader> { _FbUint8List(bc, bc.derefObject(offset)); } -/** - * The reader of unsigned 8-bit integers. - */ +/// The reader of unsigned 8-bit integers. class Uint8Reader extends Reader { const Uint8Reader() : super(); @@ -789,9 +682,7 @@ class Uint8Reader extends Reader { int read(BufferContext bc, int offset) => bc._getUint8(offset); } -/** - * List of booleans backed by 8-bit unsigned integers. - */ +/// List of booleans backed by 8-bit unsigned integers. class _FbBoolList with ListMixin implements List { final BufferContext bc; final int offset; @@ -825,9 +716,7 @@ class _FbBoolList with ListMixin implements List { int _getByte(int index) => bc._getUint8(offset + 4 + index); } -/** - * The list backed by 64-bit values - Uint64 length and Float64. - */ +/// The list backed by 64-bit values - Uint64 length and Float64. class _FbFloat64List extends _FbList { _FbFloat64List(BufferContext bc, int offset) : super(bc, offset); @@ -837,9 +726,7 @@ class _FbFloat64List extends _FbList { } } -/** - * List backed by a generic object which may have any size. - */ +/// List backed by a generic object which may have any size. class _FbGenericList extends _FbList { final Reader elementReader; @@ -860,9 +747,7 @@ class _FbGenericList extends _FbList { } } -/** - * The base class for immutable lists read from flat buffers. - */ +/// The base class for immutable lists read from flat buffers. abstract class _FbList with ListMixin implements List { final BufferContext bc; final int offset; @@ -884,9 +769,7 @@ abstract class _FbList with ListMixin implements List { throw StateError('Attempt to modify immutable list'); } -/** - * List backed by 32-bit unsigned integers. - */ +/// List backed by 32-bit unsigned integers. class _FbUint32List extends _FbList { _FbUint32List(BufferContext bc, int offset) : super(bc, offset); @@ -896,9 +779,7 @@ class _FbUint32List extends _FbList { } } -/** - * List backed by 8-bit unsigned integers. - */ +/// List backed by 8-bit unsigned integers. class _FbUint8List extends _FbList { _FbUint8List(BufferContext bc, int offset) : super(bc, offset); @@ -908,33 +789,23 @@ class _FbUint8List extends _FbList { } } -/** - * Class that describes the structure of a table. - */ +/// Class that describes the structure of a table. class _VTable { final Int32List _reusedFieldTails; final Int32List _reusedFieldOffsets; - /** - * The number of fields in [_reusedFieldTails]. - */ + /// The number of fields in [_reusedFieldTails]. int _fieldCount = 0; - /** - * The private copy of [_reusedFieldOffsets], which is made only when we - * find that this table is unique. - */ + /// The private copy of [_reusedFieldOffsets], which is made only when we + /// find that this table is unique. Int32List _fieldOffsets; - /** - * The size of the table that uses this VTable. - */ + /// The size of the table that uses this VTable. int tableSize; - /** - * The tail of this VTable. It is used to share the same VTable between - * multiple tables of identical structure. - */ + /// The tail of this VTable. It is used to share the same VTable between + /// multiple tables of identical structure. int tail; _VTable(this._reusedFieldTails, this._reusedFieldOffsets); @@ -948,9 +819,7 @@ class _VTable { _reusedFieldTails[field] = offset; } - /** - * Return `true` if the [existing] VTable can be used instead of this. - */ + /// Return `true` if the [existing] VTable can be used instead of this. bool canUseExistingVTable(_VTable existing) { assert(tail == null); assert(existing.tail != null); @@ -966,9 +835,7 @@ class _VTable { return false; } - /** - * Fill the [_reusedFieldOffsets] field. - */ + /// Fill the [_reusedFieldOffsets] field. void computeFieldOffsets(int tableTail) { for (int i = 0; i < _fieldCount; ++i) { int fieldTail = _reusedFieldTails[i]; @@ -976,10 +843,8 @@ class _VTable { } } - /** - * Outputs this VTable to [buf], which is is expected to be aligned to 16-bit - * and have at least [numOfUint16] 16-bit words available. - */ + /// Outputs this VTable to [buf], which is is expected to be aligned to 16-bit + /// and have at least [numOfUint16] 16-bit words available. void output(ByteData buf, int bufOffset) { // VTable size. buf.setUint16(bufOffset, numOfUint16 * 2, Endian.little); @@ -994,9 +859,7 @@ class _VTable { } } - /** - * Fill the [_fieldOffsets] field. - */ + /// Fill the [_fieldOffsets] field. void takeFieldOffsets() { assert(_fieldOffsets == null); _fieldOffsets = Int32List(_fieldCount); diff --git a/pkg/analyzer/lib/src/summary/link.dart b/pkg/analyzer/lib/src/summary/link.dart index d0bd24506c2e1..0d492d25514cc 100644 --- a/pkg/analyzer/lib/src/summary/link.dart +++ b/pkg/analyzer/lib/src/summary/link.dart @@ -2,33 +2,25 @@ // 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. -/** - * An instance of [DependencyWalker] contains the core algorithms for - * walking a dependency graph and evaluating nodes in a safe order. - */ +/// An instance of [DependencyWalker] contains the core algorithms for +/// walking a dependency graph and evaluating nodes in a safe order. abstract class DependencyWalker> { - /** - * Called by [walk] to evaluate a single non-cyclical node, after - * all that node's dependencies have been evaluated. - */ + /// Called by [walk] to evaluate a single non-cyclical node, after + /// all that node's dependencies have been evaluated. void evaluate(NodeType v); - /** - * Called by [walk] to evaluate a strongly connected component - * containing one or more nodes. All dependencies of the strongly - * connected component have been evaluated. - */ + /// Called by [walk] to evaluate a strongly connected component + /// containing one or more nodes. All dependencies of the strongly + /// connected component have been evaluated. void evaluateScc(List scc); - /** - * Walk the dependency graph starting at [startingPoint], finding - * strongly connected components and evaluating them in a safe order - * by calling [evaluate] and [evaluateScc]. - * - * This is an implementation of Tarjan's strongly connected - * components algorithm - * (https://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm). - */ + /// Walk the dependency graph starting at [startingPoint], finding + /// strongly connected components and evaluating them in a safe order + /// by calling [evaluate] and [evaluateScc]. + /// + /// This is an implementation of Tarjan's strongly connected + /// components algorithm + /// (https://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm). void walk(NodeType startingPoint) { // TODO(paulberry): consider rewriting in a non-recursive way so // that long dependency chains don't cause stack overflow. @@ -128,42 +120,30 @@ abstract class DependencyWalker> { } } -/** - * Instances of [Node] represent nodes in a dependency graph. The - * type parameter, [NodeType], is the derived type (this affords some - * extra type safety by making it difficult to accidentally construct - * bridges between unrelated dependency graphs). - */ +/// Instances of [Node] represent nodes in a dependency graph. The +/// type parameter, [NodeType], is the derived type (this affords some +/// extra type safety by making it difficult to accidentally construct +/// bridges between unrelated dependency graphs). abstract class Node { - /** - * Index used by Tarjan's strongly connected components algorithm. - * Zero means the node has not been visited yet; a nonzero value - * counts the order in which the node was visited. - */ + /// Index used by Tarjan's strongly connected components algorithm. + /// Zero means the node has not been visited yet; a nonzero value + /// counts the order in which the node was visited. int _index = 0; - /** - * Low link used by Tarjan's strongly connected components - * algorithm. This represents the smallest [_index] of all the nodes - * in the strongly connected component to which this node belongs. - */ + /// Low link used by Tarjan's strongly connected components + /// algorithm. This represents the smallest [_index] of all the nodes + /// in the strongly connected component to which this node belongs. int _lowLink = 0; List _dependencies; - /** - * Indicates whether this node has been evaluated yet. - */ + /// Indicates whether this node has been evaluated yet. bool get isEvaluated; - /** - * Compute the dependencies of this node. - */ + /// Compute the dependencies of this node. List computeDependencies(); - /** - * Gets the dependencies of the given node, computing them if necessary. - */ + /// Gets the dependencies of the given node, computing them if necessary. static List getDependencies(Node node) { return node._dependencies ??= node.computeDependencies(); } diff --git a/pkg/analyzer/lib/src/summary/package_bundle_reader.dart b/pkg/analyzer/lib/src/summary/package_bundle_reader.dart index d125f72442bb4..0aa30cd93d906 100644 --- a/pkg/analyzer/lib/src/summary/package_bundle_reader.dart +++ b/pkg/analyzer/lib/src/summary/package_bundle_reader.dart @@ -11,10 +11,8 @@ import 'package:analyzer/src/generated/source.dart'; import 'package:analyzer/src/generated/source_io.dart'; import 'package:analyzer/src/summary/idl.dart'; -/** - * A [ConflictingSummaryException] indicates that two different summaries - * provided to a [SummaryDataStore] conflict. - */ +/// A [ConflictingSummaryException] indicates that two different summaries +/// provided to a [SummaryDataStore] conflict. class ConflictingSummaryException implements Exception { final String duplicatedUri; final String summary1Uri; @@ -62,15 +60,11 @@ include the same source. } } -/** - * A placeholder of a source that is part of a package whose analysis results - * are served from its summary. This source uses its URI as [fullName] and has - * empty contents. - */ +/// A placeholder of a source that is part of a package whose analysis results +/// are served from its summary. This source uses its URI as [fullName] and has +/// empty contents. class InSummarySource extends BasicSource { - /** - * The summary file where this source was defined. - */ + /// The summary file where this source was defined. final String summaryPath; InSummarySource(Uri uri, this.summaryPath) : super(uri); @@ -91,10 +85,8 @@ class InSummarySource extends BasicSource { String toString() => uri.toString(); } -/** - * The [UriResolver] that knows about sources that are served from their - * summaries. - */ +/// The [UriResolver] that knows about sources that are served from their +/// summaries. class InSummaryUriResolver extends UriResolver { ResourceProvider resourceProvider; final SummaryDataStore _dataStore; @@ -113,37 +105,27 @@ class InSummaryUriResolver extends UriResolver { } } -/** - * A [SummaryDataStore] is a container for the data extracted from a set of - * summary package bundles. It contains maps which can be used to find linked - * and unlinked summaries by URI. - */ +/// A [SummaryDataStore] is a container for the data extracted from a set of +/// summary package bundles. It contains maps which can be used to find linked +/// and unlinked summaries by URI. class SummaryDataStore { - /** - * List of all [PackageBundle]s. - */ + /// List of all [PackageBundle]s. final List bundles = []; - /** - * Map from the URI of a unit to the summary path that contained it. - */ + /// Map from the URI of a unit to the summary path that contained it. final Map uriToSummaryPath = {}; final Set _libraryUris = {}; final Set _partUris = {}; - /** - * Create a [SummaryDataStore] and populate it with the summaries in - * [summaryPaths]. - */ + /// Create a [SummaryDataStore] and populate it with the summaries in + /// [summaryPaths]. SummaryDataStore(Iterable summaryPaths, {ResourceProvider resourceProvider}) { summaryPaths.forEach((String path) => _fillMaps(path, resourceProvider)); } - /** - * Add the given [bundle] loaded from the file with the given [path]. - */ + /// Add the given [bundle] loaded from the file with the given [path]. void addBundle(String path, PackageBundle bundle) { bundles.add(bundle); @@ -162,25 +144,19 @@ class SummaryDataStore { } } - /** - * Return `true` if the store contains the linked summary for the library - * with the given absolute [uri]. - */ + /// Return `true` if the store contains the linked summary for the library + /// with the given absolute [uri]. bool hasLinkedLibrary(String uri) { return _libraryUris.contains(uri); } - /** - * Return `true` if the store contains the unlinked summary for the unit - * with the given absolute [uri]. - */ + /// Return `true` if the store contains the unlinked summary for the unit + /// with the given absolute [uri]. bool hasUnlinkedUnit(String uri) { return uriToSummaryPath.containsKey(uri); } - /** - * Return `true` if the unit with the [uri] is a part unit in the store. - */ + /// Return `true` if the unit with the [uri] is a part unit in the store. bool isPartUnit(String uri) { return _partUris.contains(uri); } diff --git a/pkg/analyzer/lib/src/summary/summarize_elements.dart b/pkg/analyzer/lib/src/summary/summarize_elements.dart index 20b0456b507ae..508743debc6ed 100644 --- a/pkg/analyzer/lib/src/summary/summarize_elements.dart +++ b/pkg/analyzer/lib/src/summary/summarize_elements.dart @@ -4,16 +4,12 @@ import 'package:analyzer/src/summary/format.dart'; -/** - * Object that gathers information uses it to assemble a new - * [PackageBundleBuilder]. - */ +/// Object that gathers information uses it to assemble a new +/// [PackageBundleBuilder]. class PackageBundleAssembler { LinkedNodeBundleBuilder _bundle2; - /** - * Assemble a new [PackageBundleBuilder] using the gathered information. - */ + /// Assemble a new [PackageBundleBuilder] using the gathered information. PackageBundleBuilder assemble() { return PackageBundleBuilder(bundle2: _bundle2); } diff --git a/pkg/analyzer/lib/src/summary/summary_file_builder.dart b/pkg/analyzer/lib/src/summary/summary_file_builder.dart index 431ff50862e2d..e3c6edcf3b94f 100644 --- a/pkg/analyzer/lib/src/summary/summary_file_builder.dart +++ b/pkg/analyzer/lib/src/summary/summary_file_builder.dart @@ -79,9 +79,7 @@ class SummaryBuilder { /// TODO(scheglov) Remove it. AnalysisContext _context; - /** - * Create a summary builder for these [librarySources] and [context]. - */ + /// Create a summary builder for these [librarySources] and [context]. SummaryBuilder(Iterable librarySources, AnalysisContext context) : _librarySources = librarySources, _context = context, @@ -100,9 +98,7 @@ class SummaryBuilder { @required this.sdkPath, }); - /** - * Build the linked bundle and return its bytes. - */ + /// Build the linked bundle and return its bytes. List build({@deprecated FeatureSet featureSet}) { if (_librarySources != null) { return _build(); @@ -157,9 +153,7 @@ class _Builder { allowedExperiments = _parseAllowedExperiments(allowedExperimentsJson); } - /** - * Build the linked bundle and return its bytes. - */ + /// Build the linked bundle and return its bytes. List build() { librarySources.forEach(_addLibrary); diff --git a/pkg/analyzer/lib/src/summary/summary_sdk.dart b/pkg/analyzer/lib/src/summary/summary_sdk.dart index 15743d5b7e58f..3315a882c2a9f 100644 --- a/pkg/analyzer/lib/src/summary/summary_sdk.dart +++ b/pkg/analyzer/lib/src/summary/summary_sdk.dart @@ -11,21 +11,17 @@ import 'package:analyzer/src/generated/source.dart' import 'package:analyzer/src/summary/idl.dart'; import 'package:analyzer/src/summary/package_bundle_reader.dart'; -/** - * An implementation of [DartSdk] which provides analysis results for `dart:` - * libraries from the given summary file. This implementation is limited and - * suitable only for command-line tools, but not for IDEs - it does not - * implement [sdkLibraries], [sdkVersion], [uris] and [fromFileUri]. - */ +/// An implementation of [DartSdk] which provides analysis results for `dart:` +/// libraries from the given summary file. This implementation is limited and +/// suitable only for command-line tools, but not for IDEs - it does not +/// implement [sdkLibraries], [sdkVersion], [uris] and [fromFileUri]. class SummaryBasedDartSdk implements DartSdk { SummaryDataStore _dataStore; InSummaryUriResolver _uriResolver; PackageBundle _bundle; ResourceProvider resourceProvider; - /** - * The [AnalysisContext] which is used for all of the sources in this sdk. - */ + /// The [AnalysisContext] which is used for all of the sources in this sdk. SdkAnalysisContext _analysisContext; SummaryBasedDartSdk(String summaryPath, bool _, {this.resourceProvider}) { @@ -48,9 +44,7 @@ class SummaryBasedDartSdk implements DartSdk { return _bundle.sdk?.allowedExperimentsJson; } - /** - * Return the [PackageBundle] for this SDK, not `null`. - */ + /// Return the [PackageBundle] for this SDK, not `null`. PackageBundle get bundle => _bundle; @override diff --git a/pkg/analyzer/lib/src/task/api/model.dart b/pkg/analyzer/lib/src/task/api/model.dart index da0d3dbc1ac3f..d3d1fac4cb481 100644 --- a/pkg/analyzer/lib/src/task/api/model.dart +++ b/pkg/analyzer/lib/src/task/api/model.dart @@ -4,23 +4,17 @@ import 'package:analyzer/src/generated/source.dart'; -/** - * An object with which an analysis result can be associated. - * - * Clients may implement this class when creating new kinds of targets. - * Instances of this type are used in hashed data structures, so subtypes are - * required to correctly implement [==] and [hashCode]. - */ +/// An object with which an analysis result can be associated. +/// +/// Clients may implement this class when creating new kinds of targets. +/// Instances of this type are used in hashed data structures, so subtypes are +/// required to correctly implement [==] and [hashCode]. abstract class AnalysisTarget { - /** - * If this target is associated with a library, return the source of the - * library's defining compilation unit; otherwise return `null`. - */ + /// If this target is associated with a library, return the source of the + /// library's defining compilation unit; otherwise return `null`. Source get librarySource; - /** - * Return the source associated with this target, or `null` if this target is - * not associated with a source. - */ + /// Return the source associated with this target, or `null` if this target is + /// not associated with a source. Source get source; } diff --git a/pkg/analyzer/lib/src/task/options.dart b/pkg/analyzer/lib/src/task/options.dart index ddaf18a651a88..96d633fbdc8c9 100644 --- a/pkg/analyzer/lib/src/task/options.dart +++ b/pkg/analyzer/lib/src/task/options.dart @@ -577,9 +577,8 @@ class TrueOrFalseValueErrorBuilder extends ErrorBuilder { } class _OptionsProcessor { - /** - * Apply the options in the given [optionMap] to the given analysis [options]. - */ + /// Apply the options in the given [optionMap] to the given analysis + /// [options]. void applyToAnalysisOptions(AnalysisOptionsImpl options, YamlMap optionMap) { if (optionMap == null) { return; diff --git a/pkg/analyzer/lib/src/task/strong_mode.dart b/pkg/analyzer/lib/src/task/strong_mode.dart index 16e0810e4fdf3..b00b9ab4e438c 100644 --- a/pkg/analyzer/lib/src/task/strong_mode.dart +++ b/pkg/analyzer/lib/src/task/strong_mode.dart @@ -16,10 +16,8 @@ import 'package:analyzer/src/summary/format.dart'; import 'package:analyzer/src/summary/idl.dart'; import 'package:analyzer/src/summary2/lazy_ast.dart'; -/** - * An object used to infer the type of instance fields and the return types of - * instance methods within a single compilation unit. - */ +/// An object used to infer the type of instance fields and the return types of +/// instance methods within a single compilation unit. class InstanceMemberInferrer { final InheritanceManager3 inheritance; final Set elementsBeingInferred = HashSet(); @@ -28,17 +26,13 @@ class InstanceMemberInferrer { bool isNonNullableByDefault; ClassElement currentClassElement; - /** - * Initialize a newly create inferrer. - */ + /// Initialize a newly create inferrer. InstanceMemberInferrer(this.inheritance); DartType get _dynamicType => DynamicTypeImpl.instance; - /** - * Infer type information for all of the instance members in the given - * compilation [unit]. - */ + /// Infer type information for all of the instance members in the given + /// compilation [unit]. void inferCompilationUnit(CompilationUnitElement unit) { typeSystem = unit.library.typeSystem; isNonNullableByDefault = typeSystem.isNonNullableByDefault; @@ -46,10 +40,8 @@ class InstanceMemberInferrer { _inferClasses(unit.types); } - /** - * Return `true` if the elements corresponding to the [elements] have the same - * kind as the [element]. - */ + /// Return `true` if the elements corresponding to the [elements] have the + /// same kind as the [element]. bool _allSameElementKind( ExecutableElement element, List elements) { var elementKind = element.kind; @@ -61,12 +53,9 @@ class InstanceMemberInferrer { return true; } - /** - * Given a method, return the parameter in the method that corresponds to the - * given [parameter]. If the parameter is positional, then - * it appears at the given [index] in its enclosing element's list of - * parameters. - */ + /// Given a method, return the parameter in the method that corresponds to the + /// given [parameter]. If the parameter is positional, then it appears at the + /// given [index] in its enclosing element's list of parameters. ParameterElement _getCorrespondingParameter(ParameterElement parameter, int index, List methodParameters) { // @@ -95,13 +84,11 @@ class InstanceMemberInferrer { return null; } - /** - * If the given [accessor] represents a non-synthetic instance property - * accessor for which no type was provided, infer its types. - * - * If the given [field] represents a non-synthetic instance field for - * which no type was provided, infer the type of the field. - */ + /// If the given [accessor] represents a non-synthetic instance property + /// accessor for which no type was provided, infer its types. + /// + /// If the given [field] represents a non-synthetic instance field for + /// which no type was provided, infer the type of the field. void _inferAccessorOrField({ PropertyAccessorElementImpl accessor, FieldElementImpl field, @@ -319,10 +306,8 @@ class InstanceMemberInferrer { } } - /** - * Infer type information for all of the instance members in the given - * [classElement]. - */ + /// Infer type information for all of the instance members in the given + /// [classElement]. void _inferClass(ClassElement classElement) { if (classElement is ClassElementImpl) { if (classElement.hasBeenInferred) { @@ -393,11 +378,9 @@ class InstanceMemberInferrer { } } - /** - * If the given [element] represents a non-synthetic instance method, - * getter or setter, infer the return type and any parameter type(s) where - * they were not provided. - */ + /// If the given [element] represents a non-synthetic instance method, + /// getter or setter, infer the return type and any parameter type(s) where + /// they were not provided. void _inferExecutable(MethodElementImpl element) { if (element.isSynthetic || element.isStatic) { return; @@ -487,9 +470,7 @@ class InstanceMemberInferrer { _resetOperatorEqualParameterTypeToDynamic(element, overriddenElements); } - /** - * If a parameter is covariant, any parameters that override it are too. - */ + /// If a parameter is covariant, any parameters that override it are too. void _inferParameterCovariance(ParameterElementImpl parameter, int index, Iterable overridden) { parameter.inheritsCovariant = overridden.any((f) { @@ -498,11 +479,9 @@ class InstanceMemberInferrer { }); } - /** - * Set the type for the [parameter] at the given [index] from the given - * [combinedSignatureType], which might be `null` if there is no valid - * combined signature for signatures from direct superinterfaces. - */ + /// Set the type for the [parameter] at the given [index] from the given + /// [combinedSignatureType], which might be `null` if there is no valid + /// combined signature for signatures from direct superinterfaces. void _inferParameterType(ParameterElementImpl parameter, int index, FunctionType combinedSignatureType) { if (combinedSignatureType != null) { @@ -523,10 +502,8 @@ class InstanceMemberInferrer { } } - /** - * Infer type information for all of the instance members in the given - * interface [type]. - */ + /// Infer type information for all of the instance members in the given + /// interface [type]. void _inferType(InterfaceType type) { if (type != null) { ClassElement element = type.element; @@ -586,18 +563,16 @@ class InstanceMemberInferrer { element.isOperatorEqualWithParameterTypeFromObject = true; } - /** - * Return the [FunctionType] of the [overriddenElement] that [element] - * overrides. Return `null`, in case of type parameters inconsistency. - * - * The overridden element must have the same number of generic type - * parameters as the target element, or none. - * - * If we do have generic type parameters on the element we're inferring, - * we must express its parameter and return types in terms of its own - * parameters. For example, given `m(t)` overriding `m(S s)` we - * should infer this as `m(T t)`. - */ + /// Return the [FunctionType] of the [overriddenElement] that [element] + /// overrides. Return `null`, in case of type parameters inconsistency. + /// + /// The overridden element must have the same number of generic type + /// parameters as the target element, or none. + /// + /// If we do have generic type parameters on the element we're inferring, + /// we must express its parameter and return types in terms of its own + /// parameters. For example, given `m(t)` overriding `m(S s)` we + /// should infer this as `m(T t)`. FunctionType _toOverriddenFunctionType( ExecutableElement element, ExecutableElement overriddenElement) { var elementTypeParameters = element.typeParameters; @@ -624,7 +599,5 @@ class InstanceMemberInferrer { } } -/** - * A class of exception that is not used anywhere else. - */ +/// A class of exception that is not used anywhere else. class _CycleException implements Exception {} diff --git a/pkg/analyzer/lib/src/test_utilities/resource_provider_mixin.dart b/pkg/analyzer/lib/src/test_utilities/resource_provider_mixin.dart index 97b1c50c92d52..b02dfaf6fadd7 100644 --- a/pkg/analyzer/lib/src/test_utilities/resource_provider_mixin.dart +++ b/pkg/analyzer/lib/src/test_utilities/resource_provider_mixin.dart @@ -6,11 +6,9 @@ import 'package:analyzer/file_system/file_system.dart'; import 'package:analyzer/file_system/memory_file_system.dart'; import 'package:analyzer/src/dart/analysis/context_locator.dart'; -/** - * A mixin for test classes that adds a [ResourceProvider] and utility methods - * for manipulating the file system. The utility methods all take a posix style - * path and convert it as appropriate for the actual platform. - */ +/// A mixin for test classes that adds a [ResourceProvider] and utility methods +/// for manipulating the file system. The utility methods all take a posix style +/// path and convert it as appropriate for the actual platform. mixin ResourceProviderMixin { MemoryResourceProvider resourceProvider = MemoryResourceProvider(); diff --git a/pkg/analyzer/lib/src/util/asserts.dart b/pkg/analyzer/lib/src/util/asserts.dart index b5a215814fb8b..3c251d33b4574 100644 --- a/pkg/analyzer/lib/src/util/asserts.dart +++ b/pkg/analyzer/lib/src/util/asserts.dart @@ -2,11 +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. -/** - * Ensures that the given [value] is not null. - * Otherwise throws an [ArgumentError]. - * An optional [description] is used in the error message. - */ +/// Ensures that the given [value] is not null. +/// Otherwise throws an [ArgumentError]. +/// An optional [description] is used in the error message. void notNull(Object value, [String description]) { if (value == null) { if (description == null) { diff --git a/pkg/analyzer/lib/src/util/glob.dart b/pkg/analyzer/lib/src/util/glob.dart index 5af8f4691f416..2edfd898767fd 100644 --- a/pkg/analyzer/lib/src/util/glob.dart +++ b/pkg/analyzer/lib/src/util/glob.dart @@ -2,32 +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. -/** - * A pattern that matches against filesystem path-like strings with wildcards. - * - * The pattern matches strings as follows: - * * The pattern must use `/` as the path separator. - * * The whole string must match, not a substring. - * * Any non wildcard is matched as a literal. - * * '*' matches one or more characters except '/'. - * * '?' matches exactly one character except '/'. - * * '**' matches one or more characters including '/'. - */ +/// A pattern that matches against filesystem path-like strings with wildcards. +/// +/// The pattern matches strings as follows: +/// * The pattern must use `/` as the path separator. +/// * The whole string must match, not a substring. +/// * Any non wildcard is matched as a literal. +/// * '*' matches one or more characters except '/'. +/// * '?' matches exactly one character except '/'. +/// * '**' matches one or more characters including '/'. class Glob { - /** - * The special characters are: \ ^ $ . | + [ ] ( ) { } - * as defined here: http://ecma-international.org/ecma-262/5.1/#sec-15.10 - */ + /// The special characters are: \ ^ $ . | + [ ] ( ) { } + /// as defined here: http://ecma-international.org/ecma-262/5.1/#sec-15.10 static final RegExp _specialChars = RegExp(r'([\\\^\$\.\|\+\[\]\(\)\{\}])'); - /** - * The path separator used to separate components in file paths. - */ + /// The path separator used to separate components in file paths. final String _separator; - /** - * The pattern string. - */ + /// The pattern string. final String _pattern; String _suffix; @@ -49,10 +41,8 @@ class Glob { @override bool operator ==(other) => other is Glob && _pattern == other._pattern; - /** - * Return `true` if the given [path] matches this glob. - * The given [path] must use the same [_separator] as the glob. - */ + /// Return `true` if the given [path] matches this glob. + /// The given [path] must use the same [_separator] as the glob. bool matches(String path) { String posixPath = _toPosixPath(path); if (_suffix != null) { @@ -64,9 +54,7 @@ class Glob { @override String toString() => _pattern; - /** - * Return the Posix version of the given [path]. - */ + /// Return the Posix version of the given [path]. String _toPosixPath(String path) { if (_separator == '/') { return path; @@ -74,10 +62,8 @@ class Glob { return path.replaceAll(_separator, '/'); } - /** - * Return `true` if the [pattern] start with the given [prefix] and does - * not have `*` or `?` characters after the [prefix]. - */ + /// Return `true` if the [pattern] start with the given [prefix] and does + /// not have `*` or `?` characters after the [prefix]. static bool _hasJustPrefix(String pattern, String prefix) { if (pattern.startsWith(prefix)) { int prefixLength = prefix.length; diff --git a/pkg/analyzer/lib/src/util/lru_map.dart b/pkg/analyzer/lib/src/util/lru_map.dart index 7ac69e7e8d447..006b02c162834 100644 --- a/pkg/analyzer/lib/src/util/lru_map.dart +++ b/pkg/analyzer/lib/src/util/lru_map.dart @@ -7,12 +7,10 @@ import 'dart:collection'; /// This handler is notified when an item is evicted from the cache. typedef EvictionHandler = Function(K key, V value); -/** - * A hash-table based cache implementation. - * - * When it reaches the specified number of items, the item that has not been - * accessed (both get and put) recently is evicted. - */ +/// A hash-table based cache implementation. +/// +/// When it reaches the specified number of items, the item that has not been +/// accessed (both get and put) recently is evicted. class LRUMap { final LinkedHashMap _map = LinkedHashMap(); final int _maxSize; @@ -20,10 +18,8 @@ class LRUMap { LRUMap(this._maxSize, [this._handler]); - /** - * Returns the value for the given [key] or null if [key] is not - * in the cache. - */ + /// Returns the value for the given [key] or null if [key] is not + /// in the cache. V get(K key) { V value = _map.remove(key); if (value != null) { @@ -32,12 +28,10 @@ class LRUMap { return value; } - /** - * Associates the [key] with the given [value]. - * - * If the cache is full, an item that has not been accessed recently is - * evicted. - */ + /// Associates the [key] with the given [value]. + /// + /// If the cache is full, an item that has not been accessed recently is + /// evicted. void put(K key, V value) { _map.remove(key); _map[key] = value; @@ -50,9 +44,7 @@ class LRUMap { } } - /** - * Removes the association for the given [key]. - */ + /// Removes the association for the given [key]. void remove(K key) { _map.remove(key); } diff --git a/pkg/analyzer/lib/src/util/utilities_timing.dart b/pkg/analyzer/lib/src/util/utilities_timing.dart index 0ade45233ae2f..95a9a4443b273 100644 --- a/pkg/analyzer/lib/src/util/utilities_timing.dart +++ b/pkg/analyzer/lib/src/util/utilities_timing.dart @@ -2,25 +2,17 @@ // 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. -/** - * A `CountedStopwatch` is a [Stopwatch] that counts the number of times the - * stop method has been invoked. - */ +/// A `CountedStopwatch` is a [Stopwatch] that counts the number of times the +/// stop method has been invoked. class CountedStopwatch extends Stopwatch { - /** - * The number of times the [stop] method has been invoked. - */ + /// The number of times the [stop] method has been invoked. int stopCount = 0; - /** - * Initialize a newly created stopwatch. - */ + /// Initialize a newly created stopwatch. CountedStopwatch(); - /** - * The average number of millisecond that were recorded each time the [start] - * and [stop] methods were invoked. - */ + /// The average number of millisecond that were recorded each time the [start] + /// and [stop] methods were invoked. int get averageMilliseconds => elapsedMilliseconds ~/ stopCount; @override diff --git a/pkg/analyzer/lib/src/workspace/basic.dart b/pkg/analyzer/lib/src/workspace/basic.dart index f5ef805046a47..8b3e3c8b8cc45 100644 --- a/pkg/analyzer/lib/src/workspace/basic.dart +++ b/pkg/analyzer/lib/src/workspace/basic.dart @@ -8,17 +8,13 @@ import 'package:analyzer/src/generated/source.dart'; import 'package:analyzer/src/workspace/simple.dart'; import 'package:analyzer/src/workspace/workspace.dart'; -/** - * Information about a default Dart workspace. - * - * A BasicWorkspace should only be used when no other workspace type is valid. - */ +/// Information about a default Dart workspace. +/// +/// A BasicWorkspace should only be used when no other workspace type is valid. class BasicWorkspace extends SimpleWorkspace { - /** - * The singular package in this workspace. - * - * Each basic workspace is itself one package. - */ + /// The singular package in this workspace. + /// + /// Each basic workspace is itself one package. BasicWorkspacePackage _theOnlyPackage; BasicWorkspace._( @@ -38,13 +34,11 @@ class BasicWorkspace extends SimpleWorkspace { } } - /** - * Find the basic workspace that contains the given [path]. - * - * As a [BasicWorkspace] is not defined by any marker files or build - * artifacts, this simply creates a BasicWorkspace with [path] as the [root] - * (or [path]'s parent if [path] points to a file). - */ + /// Find the basic workspace that contains the given [path]. + /// + /// As a [BasicWorkspace] is not defined by any marker files or build + /// artifacts, this simply creates a BasicWorkspace with [path] as the [root] + /// (or [path]'s parent if [path] points to a file). static BasicWorkspace find( ResourceProvider provider, Map> packageMap, @@ -58,13 +52,11 @@ class BasicWorkspace extends SimpleWorkspace { } } -/** - * Information about a package defined in a [BasicWorkspace]. - * - * Separate from [Packages] or package maps, this class is designed to simply - * understand whether arbitrary file paths represent libraries declared within - * a given package in a [BasicWorkspace]. - */ +/// Information about a package defined in a [BasicWorkspace]. +/// +/// Separate from [Packages] or package maps, this class is designed to simply +/// understand whether arbitrary file paths represent libraries declared within +/// a given package in a [BasicWorkspace]. class BasicWorkspacePackage extends WorkspacePackage { @override final String root; diff --git a/pkg/analyzer/lib/src/workspace/bazel.dart b/pkg/analyzer/lib/src/workspace/bazel.dart index 2b009b822ad08..5b6bd923c20ec 100644 --- a/pkg/analyzer/lib/src/workspace/bazel.dart +++ b/pkg/analyzer/lib/src/workspace/bazel.dart @@ -15,11 +15,9 @@ import 'package:analyzer/src/util/uri.dart'; import 'package:analyzer/src/workspace/workspace.dart'; import 'package:path/path.dart' as path; -/** - * Instances of the class `BazelFileUriResolver` resolve `file` URI's by first - * resolving file uri's in the expected way, and then by looking in the - * corresponding generated directories. - */ +/// Instances of the class `BazelFileUriResolver` resolve `file` URI's by first +/// resolving file uri's in the expected way, and then by looking in the +/// corresponding generated directories. class BazelFileUriResolver extends ResourceUriResolver { final BazelWorkspace workspace; @@ -41,16 +39,12 @@ class BazelFileUriResolver extends ResourceUriResolver { } } -/** - * The [UriResolver] that can resolve `package` URIs in [BazelWorkspace]. - */ +/// The [UriResolver] that can resolve `package` URIs in [BazelWorkspace]. class BazelPackageUriResolver extends UriResolver { final BazelWorkspace _workspace; final path.Context _context; - /** - * The cache of absolute [Uri]s to [Source]s mappings. - */ + /// The cache of absolute [Uri]s to [Source]s mappings. final Map _sourceCache = HashMap(); BazelPackageUriResolver(BazelWorkspace workspace) @@ -145,42 +139,32 @@ class BazelPackageUriResolver extends UriResolver { } } -/** - * Information about a Bazel workspace. - */ +/// Information about a Bazel workspace. class BazelWorkspace extends Workspace implements WorkspaceWithDefaultAnalysisOptions { static const String _WORKSPACE = 'WORKSPACE'; static const String _READONLY = 'READONLY'; - /** - * The name of the file that identifies a set of Bazel Targets. - * - * For Dart package purposes, a BUILD file identifies a package. - */ + /// The name of the file that identifies a set of Bazel Targets. + /// + /// For Dart package purposes, a BUILD file identifies a package. static const String _buildFileName = 'BUILD'; - /** - * Default prefix for "-genfiles" and "-bin" that will be assumed if no build - * output symlinks are found. - */ + /// Default prefix for "-genfiles" and "-bin" that will be assumed if no build + /// output symlinks are found. static const defaultSymlinkPrefix = 'bazel'; final ResourceProvider provider; - /** - * The absolute workspace root path. - * - * It contains the `WORKSPACE` file or its parent contains the `READONLY` - * folder. - */ + /// The absolute workspace root path. + /// + /// It contains the `WORKSPACE` file or its parent contains the `READONLY` + /// folder. @override final String root; - /** - * The absolute path to the optional read only workspace root, in the - * `READONLY` folder if a git-based workspace, or `null`. - */ + /// The absolute path to the optional read only workspace root, in the + /// `READONLY` folder if a git-based workspace, or `null`. final String readonly; /// The absolute paths to all `bazel-bin` folders. @@ -189,9 +173,7 @@ class BazelWorkspace extends Workspace /// on distributed build systems. It is very rare to have more than two. final List binPaths; - /** - * The absolute path to the `bazel-genfiles` folder. - */ + /// The absolute path to the `bazel-genfiles` folder. final String genfiles; BazelWorkspace._( @@ -217,13 +199,11 @@ class BazelWorkspace extends Workspace return SourceFactory(resolvers); } - /** - * Return the file with the given [absolutePath], looking first into - * directories for generated files: `bazel-bin` and `bazel-genfiles`, and - * then into the workspace root. The file in the workspace root is returned - * even if it does not exist. Return `null` if the given [absolutePath] is - * not in the workspace [root]. - */ + /// Return the file with the given [absolutePath], looking first into + /// directories for generated files: `bazel-bin` and `bazel-genfiles`, and + /// then into the workspace root. The file in the workspace root is returned + /// even if it does not exist. Return `null` if the given [absolutePath] is + /// not in the workspace [root]. File findFile(String absolutePath) { path.Context context = provider.pathContext; try { @@ -455,13 +435,11 @@ class BazelWorkspace extends Workspace .firstWhere((folder) => folder.exists, orElse: () => null); } -/** - * Information about a package defined in a BazelWorkspace. - * - * Separate from [Packages] or package maps, this class is designed to simply - * understand whether arbitrary file paths represent libraries declared within - * a given package in a BazelWorkspace. - */ +/// Information about a package defined in a BazelWorkspace. +/// +/// Separate from [Packages] or package maps, this class is designed to simply +/// understand whether arbitrary file paths represent libraries declared within +/// a given package in a BazelWorkspace. class BazelWorkspacePackage extends WorkspacePackage { /// A prefix for any URI of a path in this package. final String _uriPrefix; diff --git a/pkg/analyzer/lib/src/workspace/gn.dart b/pkg/analyzer/lib/src/workspace/gn.dart index 62482bd1eec07..235418e217522 100644 --- a/pkg/analyzer/lib/src/workspace/gn.dart +++ b/pkg/analyzer/lib/src/workspace/gn.dart @@ -16,37 +16,25 @@ import 'package:analyzer/src/workspace/workspace.dart'; import 'package:meta/meta.dart'; import 'package:path/path.dart' as path; -/** - * Information about a Gn workspace. - */ +/// Information about a Gn workspace. class GnWorkspace extends Workspace { - /** - * The name of the directory that identifies the root of the workspace. - */ + /// The name of the directory that identifies the root of the workspace. static const String _jiriRootName = '.jiri_root'; - /** - * The name of the file that identifies a set of GN Targets. - * - * For Dart package purposes, a BUILD.gn file identifies a package. - */ + /// The name of the file that identifies a set of GN Targets. + /// + /// For Dart package purposes, a BUILD.gn file identifies a package. static const String _buildFileName = 'BUILD.gn'; - /** - * The resource provider used to access the file system. - */ + /// The resource provider used to access the file system. final ResourceProvider provider; - /** - * The absolute workspace root path (the directory containing the `.jiri_root` - * directory). - */ + /// The absolute workspace root path (the directory containing the + /// `.jiri_root` directory). @override final String root; - /** - * The map from a package name to the list of its `lib/` folders. - */ + /// The map from a package name to the list of its `lib/` folders. final Map> _packageMap; GnWorkspace._(this.provider, this.root, this._packageMap); @@ -73,11 +61,9 @@ class GnWorkspace extends Workspace { return SourceFactory(resolvers); } - /** - * Return the file with the given [absolutePath]. - * - * Return `null` if the given [absolutePath] is not in the workspace [root]. - */ + /// Return the file with the given [absolutePath]. + /// + /// Return `null` if the given [absolutePath] is not in the workspace [root]. File findFile(String absolutePath) { try { File writableFile = provider.getFile(absolutePath); @@ -112,13 +98,11 @@ class GnWorkspace extends Workspace { } } - /** - * Find the GN workspace that contains the given [filePath]. - * - * Return `null` if a workspace could not be found. For a workspace to be - * found, both a `.jiri_root` file must be found, and at least one "packages" - * file must be found in [filePath]'s output directory. - */ + /// Find the GN workspace that contains the given [filePath]. + /// + /// Return `null` if a workspace could not be found. For a workspace to be + /// found, both a `.jiri_root` file must be found, and at least one "packages" + /// file must be found in [filePath]'s output directory. static GnWorkspace find(ResourceProvider provider, String filePath) { Resource resource = provider.getResource(filePath); if (resource is File) { @@ -156,15 +140,13 @@ class GnWorkspace extends Workspace { } } - /** - * For a source at `$root/foo/bar`, the packages files are generated in - * `$root/out/-XYZ/dartlang/gen/foo/bar`. - * - * Note that in some cases multiple .packages files can be found at that - * location, for example if the package contains both a library and a binary - * target. For a complete view of the package, all of these files need to be - * taken into account. - */ + /// For a source at `$root/foo/bar`, the packages files are generated in + /// `$root/out/-XYZ/dartlang/gen/foo/bar`. + /// + /// Note that in some cases multiple .packages files can be found at that + /// location, for example if the package contains both a library and a binary + /// target. For a complete view of the package, all of these files need to be + /// taken into account. static List _findPackagesFile( ResourceProvider provider, String root, @@ -188,13 +170,11 @@ class GnWorkspace extends Workspace { .toList(); } - /** - * Returns the output directory of the build, or `null` if it could not be - * found. - * - * First attempts to read a config file at the root of the source tree. If - * that file cannot be found, looks for standard output directory locations. - */ + /// Returns the output directory of the build, or `null` if it could not be + /// found. + /// + /// First attempts to read a config file at the root of the source tree. If + /// that file cannot be found, looks for standard output directory locations. static Folder _getOutDirectory(String root, ResourceProvider provider) { const String fuchsiaDirConfigFile = '.fx-build-dir'; @@ -223,13 +203,11 @@ class GnWorkspace extends Workspace { } } -/** - * Information about a package defined in a GnWorkspace. - * - * Separate from [Packages] or package maps, this class is designed to simply - * understand whether arbitrary file paths represent libraries declared within - * a given package in a GnWorkspace. - */ +/// Information about a package defined in a GnWorkspace. +/// +/// Separate from [Packages] or package maps, this class is designed to simply +/// understand whether arbitrary file paths represent libraries declared within +/// a given package in a GnWorkspace. class GnWorkspacePackage extends WorkspacePackage { @override final String root; diff --git a/pkg/analyzer/lib/src/workspace/package_build.dart b/pkg/analyzer/lib/src/workspace/package_build.dart index effc784e447e5..d274ccbd34404 100644 --- a/pkg/analyzer/lib/src/workspace/package_build.dart +++ b/pkg/analyzer/lib/src/workspace/package_build.dart @@ -17,11 +17,9 @@ import 'package:analyzer/src/workspace/workspace.dart'; import 'package:path/path.dart' as path; import 'package:yaml/yaml.dart'; -/** - * Instances of the class `PackageBuildFileUriResolver` resolve `file` URI's by - * first resolving file uri's in the expected way, and then by looking in the - * corresponding generated directories. - */ +/// Instances of the class `PackageBuildFileUriResolver` resolve `file` URI's by +/// first resolving file uri's in the expected way, and then by looking in the +/// corresponding generated directories. class PackageBuildFileUriResolver extends ResourceUriResolver { final PackageBuildWorkspace workspace; @@ -47,9 +45,8 @@ class PackageBuildFileUriResolver extends ResourceUriResolver { } } -/** - * The [UriResolver] that can resolve `package` URIs in [PackageBuildWorkspace]. - */ +/// The [UriResolver] that can resolve `package` URIs in +/// [PackageBuildWorkspace]. class PackageBuildPackageUriResolver extends UriResolver { final PackageBuildWorkspace _workspace; final UriResolver _normalUriResolver; @@ -124,58 +121,40 @@ class PackageBuildPackageUriResolver extends UriResolver { } } -/** - * Information about a package:build workspace. - */ +/// Information about a package:build workspace. class PackageBuildWorkspace extends Workspace { - /** - * The name of the directory that identifies the root of the workspace. Note, - * the presence of this file does not show package:build is used. For that, - * the subdirectory [_dartToolBuildName] must exist. A `pub` subdirectory - * will usually exist in non-package:build projects too. - */ + /// The name of the directory that identifies the root of the workspace. Note, + /// the presence of this file does not show package:build is used. For that, + /// the subdirectory [_dartToolBuildName] must exist. A `pub` subdirectory + /// will usually exist in non-package:build projects too. static const String _dartToolRootName = '.dart_tool'; - /** - * The name of the subdirectory in [_dartToolName] that distinguishes projects - * built with package:build. - */ + /// The name of the subdirectory in [_dartToolName] that distinguishes + /// projects built with package:build. static const String _dartToolBuildName = 'build'; - /** - * We use pubspec.yaml to get the package name to be consistent with how - * package:build does it. - */ + /// We use pubspec.yaml to get the package name to be consistent with how + /// package:build does it. static const String _pubspecName = 'pubspec.yaml'; - /** - * The resource provider used to access the file system. - */ + /// The resource provider used to access the file system. final ResourceProvider provider; - /** - * The map from a package name to the list of its `lib/` folders. - */ + /// The map from a package name to the list of its `lib/` folders. final Map> _packageMap; - /** - * The absolute workspace root path (the directory containing the `.dart_tool` - * directory). - */ + /// The absolute workspace root path (the directory containing the + /// `.dart_tool` directory). @override final String root; - /** - * The name of the package under development as defined in pubspec.yaml. This - * matches the behavior of package:build. - */ + /// The name of the package under development as defined in pubspec.yaml. This + /// matches the behavior of package:build. final String projectPackageName; - /** - * The singular package in this workspace. - * - * Each "package:build" workspace is itself one package. - */ + /// The singular package in this workspace. + /// + /// Each "package:build" workspace is itself one package. PackageBuildWorkspacePackage _theOnlyPackage; PackageBuildWorkspace._( @@ -185,15 +164,13 @@ class PackageBuildWorkspace extends Workspace { UriResolver get packageUriResolver => PackageBuildPackageUriResolver( this, PackageMapUriResolver(provider, _packageMap)); - /** - * For some package file, which may or may not be a package source (it could - * be in `bin/`, `web/`, etc), find where its built counterpart will exist if - * its a generated source. - * - * To get a [builtPath] for a package source file to use in this method, - * use [builtPackageSourcePath]. For `bin/`, `web/`, etc, it must be relative - * to the project root. - */ + /// For some package file, which may or may not be a package source (it could + /// be in `bin/`, `web/`, etc), find where its built counterpart will exist if + /// its a generated source. + /// + /// To get a [builtPath] for a package source file to use in this method, + /// use [builtPackageSourcePath]. For `bin/`, `web/`, etc, it must be relative + /// to the project root. File builtFile(String builtPath, String packageName) { if (!_packageMap.containsKey(packageName)) { return null; @@ -204,13 +181,11 @@ class PackageBuildWorkspace extends Workspace { return provider.getFile(fullBuiltPath); } - /** - * Unlike the way that sources are resolved against `.packages` (if foo points - * to folder bar, then `foo:baz.dart` is found at `bar/baz.dart`), the built - * sources for a package require the `lib/` prefix first. This is because - * `bin/`, `web/`, and `test/` etc can all be built as well. This method - * exists to give a name to that prefix processing step. - */ + /// Unlike the way that sources are resolved against `.packages` (if foo + /// points to folder bar, then `foo:baz.dart` is found at `bar/baz.dart`), the + /// built sources for a package require the `lib/` prefix first. This is + /// because `bin/`, `web/`, and `test/` etc can all be built as well. This + /// method exists to give a name to that prefix processing step. String builtPackageSourcePath(String filePath) { path.Context context = provider.pathContext; assert(context.isRelative(filePath), 'Not a relative path: $filePath'); @@ -232,14 +207,12 @@ class PackageBuildWorkspace extends Workspace { return SourceFactory(resolvers); } - /** - * Return the file with the given [filePath], looking first in the generated - * directory `.dart_tool/build/generated/$projectPackageName/`, then in - * source directories. - * - * The file in the workspace [root] is returned even if it does not exist. - * Return `null` if the given [filePath] is not in the workspace root. - */ + /// Return the file with the given [filePath], looking first in the generated + /// directory `.dart_tool/build/generated/$projectPackageName/`, then in + /// source directories. + /// + /// The file in the workspace [root] is returned even if it does not exist. + /// Return `null` if the given [filePath] is not in the workspace root. File findFile(String filePath) { path.Context context = provider.pathContext; assert(context.isAbsolute(filePath), 'Not an absolute path: $filePath'); @@ -269,11 +242,9 @@ class PackageBuildWorkspace extends Workspace { } } - /** - * Find the package:build workspace that contains the given [filePath]. - * - * Return `null` if the filePath is not in a package:build workspace. - */ + /// Find the package:build workspace that contains the given [filePath]. + /// + /// Return `null` if the filePath is not in a package:build workspace. static PackageBuildWorkspace find(ResourceProvider provider, Map> packageMap, String filePath) { Folder folder = provider.getFolder(filePath); @@ -305,13 +276,11 @@ class PackageBuildWorkspace extends Workspace { } } -/** - * Information about a package defined in a PackageBuildWorkspace. - * - * Separate from [Packages] or package maps, this class is designed to simply - * understand whether arbitrary file paths represent libraries declared within - * a given package in a PackageBuildWorkspace. - */ +/// Information about a package defined in a PackageBuildWorkspace. +/// +/// Separate from [Packages] or package maps, this class is designed to simply +/// understand whether arbitrary file paths represent libraries declared within +/// a given package in a PackageBuildWorkspace. class PackageBuildWorkspacePackage extends WorkspacePackage { @override final String root; diff --git a/pkg/analyzer/lib/src/workspace/workspace.dart b/pkg/analyzer/lib/src/workspace/workspace.dart index 51b67b3fe26f0..5b64e10e16d9c 100644 --- a/pkg/analyzer/lib/src/workspace/workspace.dart +++ b/pkg/analyzer/lib/src/workspace/workspace.dart @@ -7,50 +7,36 @@ import 'package:analyzer/src/generated/source.dart'; import 'package:analyzer/src/summary/package_bundle_reader.dart'; import 'package:analyzer/src/workspace/bazel.dart'; -/** - * Abstract superclass of classes that provide information about the workspace - * in which analysis is being performed. - */ +/// Abstract superclass of classes that provide information about the workspace +/// in which analysis is being performed. abstract class Workspace { - /** - * Return true iff this [Workspace] is a [BazelWorkspace]. - */ + /// Return true iff this [Workspace] is a [BazelWorkspace]. bool get isBazel => false; - /** - * The [UriResolver] that can resolve `package` URIs. - */ + /// The [UriResolver] that can resolve `package` URIs. UriResolver get packageUriResolver; - /** - * The absolute workspace root path. - */ + /// The absolute workspace root path. String get root; - /** - * Create the source factory that should be used to resolve Uris to [Source]s. - * The [sdk] may be `null`. The [summaryData] can also be `null`. - */ + /// Create the source factory that should be used to resolve Uris to + /// [Source]s. The [sdk] may be `null`. The [summaryData] can also be `null`. SourceFactory createSourceFactory(DartSdk sdk, SummaryDataStore summaryData); - /** - * Find the [WorkspacePackage] where the library at [path] is defined. - * - * Separate from [Packages] or [packageMap], this method is designed to find - * the package, by its root, in which a library at an arbitrary path is - * defined. - */ + /// Find the [WorkspacePackage] where the library at [path] is defined. + /// + /// Separate from [Packages] or [packageMap], this method is designed to find + /// the package, by its root, in which a library at an arbitrary path is + /// defined. WorkspacePackage findPackageFor(String path); } -/** - * Abstract superclass of classes that provide information about a package - * defined in a Workspace. - * - * Separate from [Packages] or package maps, this class is designed to simply - * understand whether arbitrary file paths represent libraries declared within - * a given package in a Workspace. - */ +/// Abstract superclass of classes that provide information about a package +/// defined in a Workspace. +/// +/// Separate from [Packages] or package maps, this class is designed to simply +/// understand whether arbitrary file paths represent libraries declared within +/// a given package in a Workspace. abstract class WorkspacePackage { String get root; @@ -72,20 +58,14 @@ abstract class WorkspacePackage { } } -/** - * An interface for a workspace that contains a default analysis options file. - * Classes that provide information of such a workspace should implement this - * interface. - */ +/// An interface for a workspace that contains a default analysis options file. +/// Classes that provide information of such a workspace should implement this +/// interface. class WorkspaceWithDefaultAnalysisOptions { - /** - * The uri for the default analysis options file. - */ + /// The uri for the default analysis options file. static const String uri = 'package:dart.analysis_options/default.yaml'; - /** - * The uri for third_party analysis options file. - */ + /// The uri for third_party analysis options file. static const String thirdPartyUri = 'package:dart.analysis_options/third_party.yaml'; }