| Index: pkg/analyzer/lib/src/generated/engine.dart
|
| diff --git a/pkg/analyzer/lib/src/generated/engine.dart b/pkg/analyzer/lib/src/generated/engine.dart
|
| index bfb1f09b5d11d81961cf154ad5231eeea4ba40ef..f2f12c60282f4a9f0653caa106b9a31c1a6ad0f6 100644
|
| --- a/pkg/analyzer/lib/src/generated/engine.dart
|
| +++ b/pkg/analyzer/lib/src/generated/engine.dart
|
| @@ -59,42 +59,36 @@ typedef bool AnalyzeFunctionBodiesPredicate(Source source);
|
| typedef T PendingFutureComputer<T>(SourceEntry sourceEntry);
|
|
|
| /**
|
| - * Instances of the class `AnalysisCache` implement an LRU cache of information related to
|
| - * analysis.
|
| + * An LRU cache of information related to analysis.
|
| */
|
| class AnalysisCache {
|
| /**
|
| - * A flag used to control whether trace information should be produced when the content of the
|
| - * cache is modified.
|
| + * A flag used to control whether trace information should be produced when
|
| + * the content of the cache is modified.
|
| */
|
| static bool _TRACE_CHANGES = false;
|
|
|
| /**
|
| - * An array containing the partitions of which this cache is comprised.
|
| + * A list containing the partitions of which this cache is comprised.
|
| */
|
| final List<CachePartition> _partitions;
|
|
|
| /**
|
| - * Initialize a newly created cache to have the given partitions. The partitions will be searched
|
| - * in the order in which they appear in the array, so the most specific partition (usually an
|
| - * [SdkCachePartition]) should be first and the most general (usually a
|
| - * [UniversalCachePartition]) last.
|
| - *
|
| - * @param partitions the partitions for the newly created cache
|
| + * Initialize a newly created cache to have the given [_partitions]. The
|
| + * partitions will be searched in the order in which they appear in the list,
|
| + * so the most specific partition (usually an [SdkCachePartition]) should be
|
| + * first and the most general (usually a [UniversalCachePartition]) last.
|
| */
|
| AnalysisCache(this._partitions);
|
|
|
| /**
|
| - * Return the number of entries in this cache that have an AST associated with them.
|
| - *
|
| - * @return the number of entries in this cache that have an AST associated with them
|
| + * Return the number of entries in this cache that have an AST associated with
|
| + * them.
|
| */
|
| int get astSize => _partitions[_partitions.length - 1].astSize;
|
|
|
| /**
|
| * Return information about each of the partitions in this cache.
|
| - *
|
| - * @return information about each of the partitions in this cache
|
| */
|
| List<AnalysisContextStatistics_PartitionData> get partitionData {
|
| int count = _partitions.length;
|
| @@ -109,9 +103,8 @@ class AnalysisCache {
|
| }
|
|
|
| /**
|
| - * Record that the AST associated with the given source was just read from the cache.
|
| - *
|
| - * @param source the source whose AST was accessed
|
| + * Record that the AST associated with the given [source] was just read from
|
| + * the cache.
|
| */
|
| void accessedAst(Source source) {
|
| int count = _partitions.length;
|
| @@ -124,10 +117,7 @@ class AnalysisCache {
|
| }
|
|
|
| /**
|
| - * Return the entry associated with the given source.
|
| - *
|
| - * @param source the source whose entry is to be returned
|
| - * @return the entry associated with the given source
|
| + * Return the entry associated with the given [source].
|
| */
|
| SourceEntry get(Source source) {
|
| int count = _partitions.length;
|
| @@ -145,10 +135,7 @@ class AnalysisCache {
|
| }
|
|
|
| /**
|
| - * Return context that owns the given source.
|
| - *
|
| - * @param source the source whose context is to be returned
|
| - * @return the context that owns the partition that contains the source
|
| + * Return context that owns the given [source].
|
| */
|
| InternalAnalysisContext getContextFor(Source source) {
|
| int count = _partitions.length;
|
| @@ -169,9 +156,8 @@ class AnalysisCache {
|
| }
|
|
|
| /**
|
| - * Return an iterator returning all of the map entries mapping sources to cache entries.
|
| - *
|
| - * @return an iterator returning all of the map entries mapping sources to cache entries
|
| + * Return an iterator returning all of the map entries mapping sources to
|
| + * cache entries.
|
| */
|
| MapIterator<Source, SourceEntry> iterator() {
|
| int count = _partitions.length;
|
| @@ -183,10 +169,7 @@ class AnalysisCache {
|
| }
|
|
|
| /**
|
| - * Associate the given entry with the given source.
|
| - *
|
| - * @param source the source with which the entry is to be associated
|
| - * @param entry the entry to be associated with the source
|
| + * Associate the given [entry] with the given [source].
|
| */
|
| void put(Source source, SourceEntry entry) {
|
| entry.fixExceptionState();
|
| @@ -215,9 +198,7 @@ class AnalysisCache {
|
| }
|
|
|
| /**
|
| - * Remove all information related to the given source from this cache.
|
| - *
|
| - * @param source the source to be removed
|
| + * Remove all information related to the given [source] from this cache.
|
| */
|
| void remove(Source source) {
|
| int count = _partitions.length;
|
| @@ -239,9 +220,8 @@ class AnalysisCache {
|
| }
|
|
|
| /**
|
| - * Record that the AST associated with the given source was just removed from the cache.
|
| - *
|
| - * @param source the source whose AST was removed
|
| + * Record that the AST associated with the given [source] was just removed
|
| + * from the cache.
|
| */
|
| void removedAst(Source source) {
|
| int count = _partitions.length;
|
| @@ -255,8 +235,6 @@ class AnalysisCache {
|
|
|
| /**
|
| * Return the number of sources that are mapped to cache entries.
|
| - *
|
| - * @return the number of sources that are mapped to cache entries
|
| */
|
| int size() {
|
| int size = 0;
|
| @@ -268,9 +246,8 @@ class AnalysisCache {
|
| }
|
|
|
| /**
|
| - * Record that the AST associated with the given source was just stored to the cache.
|
| - *
|
| - * @param source the source whose AST was stored
|
| + * Record that the AST associated with the given [source] was just stored to
|
| + * the cache.
|
| */
|
| void storedAst(Source source) {
|
| int count = _partitions.length;
|
| @@ -284,126 +261,113 @@ class AnalysisCache {
|
| }
|
|
|
| /**
|
| - * The interface `AnalysisContext` defines the behavior of objects that represent a context in
|
| - * which a single analysis can be performed and incrementally maintained. The context includes such
|
| - * information as the version of the SDK being analyzed against as well as the package-root used to
|
| - * resolve 'package:' URI's. (Both of which are known indirectly through the [SourceFactory
|
| - ].)
|
| + * A context in which a single analysis can be performed and incrementally
|
| + * maintained. The context includes such information as the version of the SDK
|
| + * being analyzed against as well as the package-root used to resolve 'package:'
|
| + * URI's. (Both of which are known indirectly through the [SourceFactory].)
|
| *
|
| - * An analysis context also represents the state of the analysis, which includes knowing which
|
| - * sources have been included in the analysis (either directly or indirectly) and the results of the
|
| - * analysis. Sources must be added and removed from the context using the method
|
| - * [applyChanges], which is also used to notify the context when sources have been
|
| - * modified and, consequently, previously known results might have been invalidated.
|
| + * An analysis context also represents the state of the analysis, which includes
|
| + * knowing which sources have been included in the analysis (either directly or
|
| + * indirectly) and the results of the analysis. Sources must be added and
|
| + * removed from the context using the method [applyChanges], which is also used
|
| + * to notify the context when sources have been modified and, consequently,
|
| + * previously known results might have been invalidated.
|
| *
|
| - * There are two ways to access the results of the analysis. The most common is to use one of the
|
| - * 'get' methods to access the results. The 'get' methods have the advantage that they will always
|
| - * return quickly, but have the disadvantage that if the results are not currently available they
|
| - * will return either nothing or in some cases an incomplete result. The second way to access
|
| - * results is by using one of the 'compute' methods. The 'compute' methods will always attempt to
|
| - * compute the requested results but might block the caller for a significant period of time.
|
| + * There are two ways to access the results of the analysis. The most common is
|
| + * to use one of the 'get' methods to access the results. The 'get' methods have
|
| + * the advantage that they will always return quickly, but have the disadvantage
|
| + * that if the results are not currently available they will return either
|
| + * nothing or in some cases an incomplete result. The second way to access
|
| + * results is by using one of the 'compute' methods. The 'compute' methods will
|
| + * always attempt to compute the requested results but might block the caller
|
| + * for a significant period of time.
|
| *
|
| - * When results have been invalidated, have never been computed (as is the case for newly added
|
| - * sources), or have been removed from the cache, they are <b>not</b> automatically recreated. They
|
| - * will only be recreated if one of the 'compute' methods is invoked.
|
| + * When results have been invalidated, have never been computed (as is the case
|
| + * for newly added sources), or have been removed from the cache, they are
|
| + * <b>not</b> automatically recreated. They will only be recreated if one of the
|
| + * 'compute' methods is invoked.
|
| *
|
| - * However, this is not always acceptable. Some clients need to keep the analysis results
|
| - * up-to-date. For such clients there is a mechanism that allows them to incrementally perform
|
| - * needed analysis and get notified of the consequent changes to the analysis results. This
|
| - * mechanism is realized by the method [performAnalysisTask].
|
| + * However, this is not always acceptable. Some clients need to keep the
|
| + * analysis results up-to-date. For such clients there is a mechanism that
|
| + * allows them to incrementally perform needed analysis and get notified of the
|
| + * consequent changes to the analysis results. This mechanism is realized by the
|
| + * method [performAnalysisTask].
|
| *
|
| - * Analysis engine allows for having more than one context. This can be used, for example, to
|
| - * perform one analysis based on the state of files on disk and a separate analysis based on the
|
| - * state of those files in open editors. It can also be used to perform an analysis based on a
|
| - * proposed future state, such as the state after a refactoring.
|
| + * Analysis engine allows for having more than one context. This can be used,
|
| + * for example, to perform one analysis based on the state of files on disk and
|
| + * a separate analysis based on the state of those files in open editors. It can
|
| + * also be used to perform an analysis based on a proposed future state, such as
|
| + * the state after a refactoring.
|
| */
|
| abstract class AnalysisContext {
|
| -
|
| /**
|
| * An empty list of contexts.
|
| */
|
| static const List<AnalysisContext> EMPTY_LIST = const <AnalysisContext>[];
|
|
|
| /**
|
| - * Return the set of analysis options controlling the behavior of this context. Clients should not
|
| - * modify the returned set of options. The options should only be set by invoking the method
|
| - * [setAnalysisOptions].
|
| - *
|
| - * @return the set of analysis options controlling the behavior of this context
|
| + * Return the set of analysis options controlling the behavior of this
|
| + * context. Clients should not modify the returned set of options. The options
|
| + * should only be set by invoking the method [setAnalysisOptions].
|
| */
|
| AnalysisOptions get analysisOptions;
|
|
|
| /**
|
| - * Set the set of analysis options controlling the behavior of this context to the given options.
|
| - * Clients can safely assume that all necessary analysis results have been invalidated.
|
| - *
|
| - * @param options the set of analysis options that will control the behavior of this context
|
| + * Set the set of analysis options controlling the behavior of this context to
|
| + * the given [options]. Clients can safely assume that all necessary analysis
|
| + * results have been invalidated.
|
| */
|
| void set analysisOptions(AnalysisOptions options);
|
|
|
| /**
|
| - * Set the order in which sources will be analyzed by [performAnalysisTask] to match the
|
| - * order of the sources in the given list. If a source that needs to be analyzed is not contained
|
| - * in the list, then it will be treated as if it were at the end of the list. If the list is empty
|
| - * (or `null`) then no sources will be given priority over other sources.
|
| + * Set the order in which sources will be analyzed by [performAnalysisTask] to
|
| + * match the order of the sources in the given list of [sources]. If a source
|
| + * that needs to be analyzed is not contained in the list, then it will be
|
| + * treated as if it were at the end of the list. If the list is empty (or
|
| + * `null`) then no sources will be given priority over other sources.
|
| *
|
| - * Changes made to the list after this method returns will <b>not</b> be reflected in the priority
|
| - * order.
|
| - *
|
| - * @param sources the sources to be given priority over other sources
|
| + * Changes made to the list after this method returns will <b>not</b> be
|
| + * reflected in the priority order.
|
| */
|
| void set analysisPriorityOrder(List<Source> sources);
|
|
|
| /**
|
| * Return the set of declared variables used when computing constant values.
|
| - *
|
| - * @return the set of declared variables used when computing constant values
|
| */
|
| DeclaredVariables get declaredVariables;
|
|
|
| /**
|
| - * Return an array containing all of the sources known to this context that represent HTML files.
|
| - * The contents of the array can be incomplete.
|
| - *
|
| - * @return the sources known to this context that represent HTML files
|
| + * Return a list containing all of the sources known to this context that
|
| + * represent HTML files. The contents of the list can be incomplete.
|
| */
|
| List<Source> get htmlSources;
|
|
|
| /**
|
| * Returns `true` if this context was disposed using [dispose].
|
| - *
|
| - * @return `true` if this context was disposed
|
| */
|
| bool get isDisposed;
|
|
|
| /**
|
| - * Return an array containing all of the sources known to this context that represent the defining
|
| - * compilation unit of a library that can be run within a browser. The sources that are returned
|
| - * represent libraries that have a 'main' method and are either referenced by an HTML file or
|
| - * import, directly or indirectly, a client-only library. The contents of the array can be
|
| + * Return a list containing all of the sources known to this context that
|
| + * represent the defining compilation unit of a library that can be run within
|
| + * a browser. The sources that are returned represent libraries that have a
|
| + * 'main' method and are either referenced by an HTML file or import, directly
|
| + * or indirectly, a client-only library. The contents of the list can be
|
| * incomplete.
|
| - *
|
| - * @return the sources known to this context that represent the defining compilation unit of a
|
| - * library that can be run within a browser
|
| */
|
| List<Source> get launchableClientLibrarySources;
|
|
|
| /**
|
| - * Return an array containing all of the sources known to this context that represent the defining
|
| - * compilation unit of a library that can be run outside of a browser. The contents of the array
|
| - * can be incomplete.
|
| - *
|
| - * @return the sources known to this context that represent the defining compilation unit of a
|
| - * library that can be run outside of a browser
|
| + * Return a list containing all of the sources known to this context that
|
| + * represent the defining compilation unit of a library that can be run
|
| + * outside of a browser. The contents of the list can be incomplete.
|
| */
|
| List<Source> get launchableServerLibrarySources;
|
|
|
| /**
|
| - * Return an array containing all of the sources known to this context that represent the defining
|
| - * compilation unit of a library. The contents of the array can be incomplete.
|
| - *
|
| - * @return the sources known to this context that represent the defining compilation unit of a
|
| - * library
|
| + * Return a list containing all of the sources known to this context that
|
| + * represent the defining compilation unit of a library. The contents of the
|
| + * list can be incomplete.
|
| */
|
| List<Source> get librarySources;
|
|
|
| @@ -426,157 +390,141 @@ abstract class AnalysisContext {
|
| Stream<SourcesChangedEvent> get onSourcesChanged;
|
|
|
| /**
|
| - * Return an array containing all of the sources known to this context and their resolution state
|
| - * is not valid or flush. So, these sources are not safe to update during refactoring, because we
|
| - * may be don't know all the references in them.
|
| - *
|
| - * @return the sources known to this context and are not safe for refactoring
|
| + * Return a list containing all of the sources known to this context whose
|
| + * state is neither valid or flushed. These sources are not safe to update
|
| + * during refactoring, because we might not know all the references in them.
|
| */
|
| List<Source> get refactoringUnsafeSources;
|
|
|
| /**
|
| - * Return the source factory used to create the sources that can be analyzed in this context.
|
| - *
|
| - * @return the source factory used to create the sources that can be analyzed in this context
|
| + * Return the source factory used to create the sources that can be analyzed
|
| + * in this context.
|
| */
|
| SourceFactory get sourceFactory;
|
|
|
| /**
|
| - * Set the source factory used to create the sources that can be analyzed in this context to the
|
| - * given source factory. Clients can safely assume that all analysis results have been
|
| - * invalidated.
|
| - *
|
| - * @param factory the source factory used to create the sources that can be analyzed in this
|
| - * context
|
| + * Set the source factory used to create the sources that can be analyzed in
|
| + * this context to the given source [factory]. Clients can safely assume that
|
| + * all analysis results have been invalidated.
|
| */
|
| void set sourceFactory(SourceFactory factory);
|
|
|
| /**
|
| - * Return an array containing all of the sources known to this context.
|
| - *
|
| - * @return all of the sources known to this context
|
| + * Return a list containing all of the sources known to this context.
|
| */
|
| List<Source> get sources;
|
|
|
| /**
|
| - * Returns a type provider for this context or throws [AnalysisException] if
|
| - * `dart:core` or `dart:async` cannot be resolved.
|
| + * Return a type provider for this context or throw [AnalysisException] if
|
| + * either `dart:core` or `dart:async` cannot be resolved.
|
| */
|
| TypeProvider get typeProvider;
|
|
|
| /**
|
| - * Add the given listener to the list of objects that are to be notified when various analysis
|
| - * results are produced in this context.
|
| - *
|
| - * @param listener the listener to be added
|
| + * Add the given [listener] to the list of objects that are to be notified
|
| + * when various analysis results are produced in this context.
|
| */
|
| void addListener(AnalysisListener listener);
|
|
|
| /**
|
| - * Apply the given delta to change the level of analysis that will be performed for the sources
|
| - * known to this context.
|
| - *
|
| - * @param delta a description of the level of analysis that should be performed for some sources
|
| + * Apply the given [delta] to change the level of analysis that will be
|
| + * performed for the sources known to this context.
|
| */
|
| void applyAnalysisDelta(AnalysisDelta delta);
|
|
|
| /**
|
| - * Apply the changes specified by the given change set to this context. Any analysis results that
|
| - * have been invalidated by these changes will be removed.
|
| - *
|
| - * @param changeSet a description of the changes that are to be applied
|
| + * Apply the changes specified by the given [changeSet] to this context. Any
|
| + * analysis results that have been invalidated by these changes will be
|
| + * removed.
|
| */
|
| void applyChanges(ChangeSet changeSet);
|
|
|
| /**
|
| - * Return the documentation comment for the given element as it appears in the original source
|
| - * (complete with the beginning and ending delimiters) for block documentation comments, or lines
|
| - * starting with `"///"` and separated with `"\n"` characters for end-of-line
|
| - * documentation comments, or `null` if the element does not have a documentation comment
|
| - * associated with it. This can be a long-running operation if the information needed to access
|
| - * the comment is not cached.
|
| + * Return the documentation comment for the given [element] as it appears in
|
| + * the original source (complete with the beginning and ending delimiters) for
|
| + * block documentation comments, or lines starting with `"///"` and separated
|
| + * with `"\n"` characters for end-of-line documentation comments, or `null` if
|
| + * the element does not have a documentation comment associated with it. This
|
| + * can be a long-running operation if the information needed to access the
|
| + * comment is not cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if the documentation comment could not be
|
| + * determined because the analysis could not be performed.
|
| *
|
| - * @param element the element whose documentation comment is to be returned
|
| - * @return the element's documentation comment
|
| - * @throws AnalysisException if the documentation comment could not be determined because the
|
| - * analysis could not be performed
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| String computeDocumentationComment(Element element);
|
|
|
| /**
|
| - * Return an array containing all of the errors associated with the given source. If the errors
|
| - * are not already known then the source will be analyzed in order to determine the errors
|
| - * associated with it.
|
| + * Return a list containing all of the errors associated with the given
|
| + * [source]. If the errors are not already known then the source will be
|
| + * analyzed in order to determine the errors associated with it.
|
| + *
|
| + * Throws an [AnalysisException] if the errors could not be determined because
|
| + * the analysis could not be performed.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| *
|
| - * @param source the source whose errors are to be returned
|
| - * @return all of the errors associated with the given source
|
| - * @throws AnalysisException if the errors could not be determined because the analysis could not
|
| - * be performed
|
| * See [getErrors].
|
| */
|
| List<AnalysisError> computeErrors(Source source);
|
|
|
| /**
|
| - * Return the element model corresponding to the HTML file defined by the given source. If the
|
| - * element model does not yet exist it will be created. The process of creating an element model
|
| - * for an HTML file can be long-running, depending on the size of the file and the number of
|
| - * libraries that are defined in it (via script tags) that also need to have a model built for
|
| - * them.
|
| + * Return the element model corresponding to the HTML file defined by the
|
| + * given [source]. If the element model does not yet exist it will be created.
|
| + * The process of creating an element model for an HTML file can be
|
| + * long-running, depending on the size of the file and the number of libraries
|
| + * that are defined in it (via script tags) that also need to have a model
|
| + * built for them.
|
| + *
|
| + * Throws AnalysisException if the element model could not be determined
|
| + * because the analysis could not be performed.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| *
|
| - * @param source the source defining the HTML file whose element model is to be returned
|
| - * @return the element model corresponding to the HTML file defined by the given source
|
| - * @throws AnalysisException if the element model could not be determined because the analysis
|
| - * could not be performed
|
| * See [getHtmlElement].
|
| */
|
| HtmlElement computeHtmlElement(Source source);
|
|
|
| /**
|
| - * Return the kind of the given source, computing it's kind if it is not already known. Return
|
| - * [SourceKind.UNKNOWN] if the source is not contained in this context.
|
| + * Return the kind of the given [source], computing it's kind if it is not
|
| + * already known. Return [SourceKind.UNKNOWN] if the source is not contained
|
| + * in this context.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| *
|
| - * @param source the source whose kind is to be returned
|
| - * @return the kind of the given source
|
| * See [getKindOf].
|
| */
|
| SourceKind computeKindOf(Source source);
|
|
|
| /**
|
| - * Return the element model corresponding to the library defined by the given source. If the
|
| - * element model does not yet exist it will be created. The process of creating an element model
|
| - * for a library can long-running, depending on the size of the library and the number of
|
| - * libraries that are imported into it that also need to have a model built for them.
|
| + * Return the element model corresponding to the library defined by the given
|
| + * [source]. If the element model does not yet exist it will be created. The
|
| + * process of creating an element model for a library can long-running,
|
| + * depending on the size of the library and the number of libraries that are
|
| + * imported into it that also need to have a model built for them.
|
| + *
|
| + * Throws an [AnalysisException] if the element model could not be determined
|
| + * because the analysis could not be performed.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| *
|
| - * @param source the source defining the library whose element model is to be returned
|
| - * @return the element model corresponding to the library defined by the given source
|
| - * @throws AnalysisException if the element model could not be determined because the analysis
|
| - * could not be performed
|
| * See [getLibraryElement].
|
| */
|
| LibraryElement computeLibraryElement(Source source);
|
|
|
| /**
|
| - * Return the line information for the given source, or `null` if the source is not of a
|
| - * recognized kind (neither a Dart nor HTML file). If the line information was not previously
|
| - * known it will be created. The line information is used to map offsets from the beginning of the
|
| - * source to line and column pairs.
|
| + * Return the line information for the given [source], or `null` if the source
|
| + * is not of a recognized kind (neither a Dart nor HTML file). If the line
|
| + * information was not previously known it will be created. The line
|
| + * information is used to map offsets from the beginning of the source to line
|
| + * and column pairs.
|
| + *
|
| + * Throws an [AnalysisException] if the line information could not be
|
| + * determined because the analysis could not be performed.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| *
|
| - * @param source the source whose line information is to be returned
|
| - * @return the line information for the given source
|
| - * @throws AnalysisException if the line information could not be determined because the analysis
|
| - * could not be performed
|
| * See [getLineInfo].
|
| */
|
| LineInfo computeLineInfo(Source source);
|
| @@ -601,146 +549,117 @@ abstract class AnalysisContext {
|
| void dispose();
|
|
|
| /**
|
| - * Return `true` if the given source exists.
|
| + * Return `true` if the given [source] exists.
|
| *
|
| - * This method should be used rather than the method [Source.exists] because contexts can
|
| - * have local overrides of the content of a source that the source is not aware of and a source
|
| - * with local content is considered to exist even if there is no file on disk.
|
| - *
|
| - * @param source the source whose modification stamp is to be returned
|
| - * @return `true` if the source exists
|
| + * This method should be used rather than the method [Source.exists] because
|
| + * contexts can have local overrides of the content of a source that the
|
| + * source is not aware of and a source with local content is considered to
|
| + * exist even if there is no file on disk.
|
| */
|
| bool exists(Source source);
|
|
|
| /**
|
| - * Return the element model corresponding to the compilation unit defined by the given source in
|
| - * the library defined by the given source, or `null` if the element model does not
|
| - * currently exist or if the library cannot be analyzed for some reason.
|
| - *
|
| - * @param unitSource the source of the compilation unit
|
| - * @param librarySource the source of the defining compilation unit of the library containing the
|
| - * compilation unit
|
| - * @return the element model corresponding to the compilation unit defined by the given source
|
| + * Return the element model corresponding to the compilation unit defined by
|
| + * the given [unitSource] in the library defined by the given [librarySource],
|
| + * or `null` if the element model does not currently exist or if the library
|
| + * cannot be analyzed for some reason.
|
| */
|
| CompilationUnitElement getCompilationUnitElement(
|
| Source unitSource, Source librarySource);
|
|
|
| /**
|
| - * Get the contents and timestamp of the given source.
|
| - *
|
| - * This method should be used rather than the method [Source.getContents] because contexts
|
| - * can have local overrides of the content of a source that the source is not aware of.
|
| + * Return the contents and timestamp of the given [source].
|
| *
|
| - * @param source the source whose content is to be returned
|
| - * @return the contents and timestamp of the source
|
| - * @throws Exception if the contents of the source could not be accessed
|
| + * This method should be used rather than the method [Source.getContents]
|
| + * because contexts can have local overrides of the content of a source that
|
| + * the source is not aware of.
|
| */
|
| TimestampedData<String> getContents(Source source);
|
|
|
| /**
|
| - * Return the element referenced by the given location, or `null` if the element is not
|
| - * immediately available or if there is no element with the given location. The latter condition
|
| - * can occur, for example, if the location describes an element from a different context or if the
|
| - * element has been removed from this context as a result of some change since it was originally
|
| - * obtained.
|
| - *
|
| - * @param location the reference describing the element to be returned
|
| - * @return the element referenced by the given location
|
| + * Return the element referenced by the given [location], or `null` if the
|
| + * element is not immediately available or if there is no element with the
|
| + * given location. The latter condition can occur, for example, if the
|
| + * location describes an element from a different context or if the element
|
| + * has been removed from this context as a result of some change since it was
|
| + * originally obtained.
|
| */
|
| Element getElement(ElementLocation location);
|
|
|
| /**
|
| - * Return an analysis error info containing the array of all of the errors and the line info
|
| - * associated with the given source. The array of errors will be empty if the source is not known
|
| - * to this context or if there are no errors in the source. The errors contained in the array can
|
| - * be incomplete.
|
| + * Return an analysis error info containing the list of all of the errors and
|
| + * the line info associated with the given [source]. The list of errors will
|
| + * be empty if the source is not known to this context or if there are no
|
| + * errors in the source. The errors contained in the list can be incomplete.
|
| *
|
| - * @param source the source whose errors are to be returned
|
| - * @return all of the errors associated with the given source and the line info
|
| * See [computeErrors].
|
| */
|
| AnalysisErrorInfo getErrors(Source source);
|
|
|
| /**
|
| - * Return the element model corresponding to the HTML file defined by the given source, or
|
| - * `null` if the source does not represent an HTML file, the element representing the file
|
| - * has not yet been created, or the analysis of the HTML file failed for some reason.
|
| + * Return the element model corresponding to the HTML file defined by the
|
| + * given [source], or `null` if the source does not represent an HTML file,
|
| + * the element representing the file has not yet been created, or the analysis
|
| + * of the HTML file failed for some reason.
|
| *
|
| - * @param source the source defining the HTML file whose element model is to be returned
|
| - * @return the element model corresponding to the HTML file defined by the given source
|
| * See [computeHtmlElement].
|
| */
|
| HtmlElement getHtmlElement(Source source);
|
|
|
| /**
|
| - * Return the sources for the HTML files that reference the given compilation unit. If the source
|
| - * does not represent a Dart source or is not known to this context, the returned array will be
|
| - * empty. The contents of the array can be incomplete.
|
| - *
|
| - * @param source the source referenced by the returned HTML files
|
| - * @return the sources for the HTML files that reference the given compilation unit
|
| + * Return the sources for the HTML files that reference the compilation unit
|
| + * with the given [source]. If the source does not represent a Dart source or
|
| + * is not known to this context, the returned list will be empty. The contents
|
| + * of the list can be incomplete.
|
| */
|
| List<Source> getHtmlFilesReferencing(Source source);
|
|
|
| /**
|
| - * Return the kind of the given source, or `null` if the kind is not known to this context.
|
| + * Return the kind of the given [source], or `null` if the kind is not known
|
| + * to this context.
|
| *
|
| - * @param source the source whose kind is to be returned
|
| - * @return the kind of the given source
|
| * See [computeKindOf].
|
| */
|
| SourceKind getKindOf(Source source);
|
|
|
| /**
|
| - * Return the sources for the defining compilation units of any libraries of which the given
|
| - * source is a part. The array will normally contain a single library because most Dart sources
|
| - * are only included in a single library, but it is possible to have a part that is contained in
|
| - * multiple identically named libraries. If the source represents the defining compilation unit of
|
| - * a library, then the returned array will contain the given source as its only element. If the
|
| - * source does not represent a Dart source or is not known to this context, the returned array
|
| - * will be empty. The contents of the array can be incomplete.
|
| - *
|
| - * @param source the source contained in the returned libraries
|
| - * @return the sources for the libraries containing the given source
|
| + * Return the sources for the defining compilation units of any libraries of
|
| + * which the given [source] is a part. The list will normally contain a single
|
| + * library because most Dart sources are only included in a single library,
|
| + * but it is possible to have a part that is contained in multiple identically
|
| + * named libraries. If the source represents the defining compilation unit of
|
| + * a library, then the returned list will contain the given source as its only
|
| + * element. If the source does not represent a Dart source or is not known to
|
| + * this context, the returned list will be empty. The contents of the list can
|
| + * be incomplete.
|
| */
|
| List<Source> getLibrariesContaining(Source source);
|
|
|
| /**
|
| - * Return the sources for the defining compilation units of any libraries that depend on the given
|
| - * library. One library depends on another if it either imports or exports that library.
|
| - *
|
| - * @param librarySource the source for the defining compilation unit of the library being depended
|
| - * on
|
| - * @return the sources for the libraries that depend on the given library
|
| + * Return the sources for the defining compilation units of any libraries that
|
| + * depend on the library defined by the given [librarySource]. One library
|
| + * depends on another if it either imports or exports that library.
|
| */
|
| List<Source> getLibrariesDependingOn(Source librarySource);
|
|
|
| /**
|
| - * Return the sources for the defining compilation units of any libraries that are referenced from
|
| - * the given HTML file.
|
| - *
|
| - * @param htmlSource the source for the HTML file
|
| - * @return the sources for the libraries that are referenced by the given HTML file
|
| + * Return the sources for the defining compilation units of any libraries that
|
| + * are referenced from the HTML file defined by the given [htmlSource].
|
| */
|
| List<Source> getLibrariesReferencedFromHtml(Source htmlSource);
|
|
|
| /**
|
| - * Return the element model corresponding to the library defined by the given source, or
|
| - * `null` if the element model does not currently exist or if the library cannot be analyzed
|
| - * for some reason.
|
| - *
|
| - * @param source the source defining the library whose element model is to be returned
|
| - * @return the element model corresponding to the library defined by the given source
|
| + * Return the element model corresponding to the library defined by the given
|
| + * [source], or `null` if the element model does not currently exist or if the
|
| + * library cannot be analyzed for some reason.
|
| */
|
| LibraryElement getLibraryElement(Source source);
|
|
|
| /**
|
| - * Return the line information for the given source, or `null` if the line information is
|
| - * not known. The line information is used to map offsets from the beginning of the source to line
|
| - * and column pairs.
|
| + * Return the line information for the given [source], or `null` if the line
|
| + * information is not known. The line information is used to map offsets from
|
| + * the beginning of the source to line and column pairs.
|
| *
|
| - * @param source the source whose line information is to be returned
|
| - * @return the line information for the given source
|
| * See [computeLineInfo].
|
| */
|
| LineInfo getLineInfo(Source source);
|
| @@ -760,36 +679,29 @@ abstract class AnalysisContext {
|
| int getModificationStamp(Source source);
|
|
|
| /**
|
| - * Return a fully resolved AST for a single compilation unit within the given library, or
|
| - * `null` if the resolved AST is not already computed.
|
| + * Return a fully resolved AST for the compilation unit defined by the given
|
| + * [unitSource] within the given [library], or `null` if the resolved AST is
|
| + * not already computed.
|
| *
|
| - * @param unitSource the source of the compilation unit
|
| - * @param library the library containing the compilation unit
|
| - * @return a fully resolved AST for the compilation unit
|
| * See [resolveCompilationUnit].
|
| */
|
| CompilationUnit getResolvedCompilationUnit(
|
| Source unitSource, LibraryElement library);
|
|
|
| /**
|
| - * Return a fully resolved AST for a single compilation unit within the given library, or
|
| + * Return a fully resolved AST for the compilation unit defined by the given
|
| + * [unitSource] within the library defined by the given [librarySource], or
|
| * `null` if the resolved AST is not already computed.
|
| *
|
| - * @param unitSource the source of the compilation unit
|
| - * @param librarySource the source of the defining compilation unit of the library containing the
|
| - * compilation unit
|
| - * @return a fully resolved AST for the compilation unit
|
| - * See [resolveCompilationUnit].
|
| + * See [resolveCompilationUnit2].
|
| */
|
| CompilationUnit getResolvedCompilationUnit2(
|
| Source unitSource, Source librarySource);
|
|
|
| /**
|
| - * Return a fully resolved HTML unit, or `null` if the resolved unit is not already
|
| - * computed.
|
| + * Return the fully resolved HTML unit defined by the given [htmlSource], or
|
| + * `null` if the resolved unit is not already computed.
|
| *
|
| - * @param htmlSource the source of the HTML unit
|
| - * @return a fully resolved HTML unit
|
| * See [resolveHtmlUnit].
|
| */
|
| ht.HtmlUnit getResolvedHtmlUnit(Source htmlSource);
|
| @@ -801,159 +713,133 @@ abstract class AnalysisContext {
|
| List<Source> getSourcesWithFullName(String path);
|
|
|
| /**
|
| - * Return `true` if the given source is known to be the defining compilation unit of a
|
| - * library that can be run on a client (references 'dart:html', either directly or indirectly).
|
| - *
|
| - * <b>Note:</b> In addition to the expected case of returning `false` if the source is known
|
| - * to be a library that cannot be run on a client, this method will also return `false` if
|
| - * the source is not known to be a library or if we do not know whether it can be run on a client.
|
| + * Return `true` if the given [librarySource] is known to be the defining
|
| + * compilation unit of a library that can be run on a client (references
|
| + * 'dart:html', either directly or indirectly).
|
| *
|
| - * @param librarySource the source being tested
|
| - * @return `true` if the given source is known to be a library that can be run on a client
|
| + * <b>Note:</b> In addition to the expected case of returning `false` if the
|
| + * source is known to be a library that cannot be run on a client, this method
|
| + * will also return `false` if the source is not known to be a library or if
|
| + * we do not know whether it can be run on a client.
|
| */
|
| bool isClientLibrary(Source librarySource);
|
|
|
| /**
|
| - * Return `true` if the given source is known to be the defining compilation unit of a
|
| - * library that can be run on the server (does not reference 'dart:html', either directly or
|
| - * indirectly).
|
| + * Return `true` if the given [librarySource] is known to be the defining
|
| + * compilation unit of a library that can be run on the server (does not
|
| + * reference 'dart:html', either directly or indirectly).
|
| *
|
| - * <b>Note:</b> In addition to the expected case of returning `false` if the source is known
|
| - * to be a library that cannot be run on the server, this method will also return `false` if
|
| - * the source is not known to be a library or if we do not know whether it can be run on the
|
| - * server.
|
| - *
|
| - * @param librarySource the source being tested
|
| - * @return `true` if the given source is known to be a library that can be run on the server
|
| + * <b>Note:</b> In addition to the expected case of returning `false` if the
|
| + * source is known to be a library that cannot be run on the server, this
|
| + * method will also return `false` if the source is not known to be a library
|
| + * or if we do not know whether it can be run on the server.
|
| */
|
| bool isServerLibrary(Source librarySource);
|
|
|
| /**
|
| - * Parse a single source to produce an AST structure. The resulting AST structure may or may not
|
| - * be resolved, and may have a slightly different structure depending upon whether it is resolved.
|
| + * Parse the content of the given [source] to produce an AST structure. The
|
| + * resulting AST structure may or may not be resolved, and may have a slightly
|
| + * different structure depending upon whether it is resolved.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if the analysis could not be performed
|
| *
|
| - * @param source the source to be parsed
|
| - * @return the AST structure representing the content of the source
|
| - * @throws AnalysisException if the analysis could not be performed
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| CompilationUnit parseCompilationUnit(Source source);
|
|
|
| /**
|
| - * Parse a single HTML source to produce an AST structure. The resulting HTML AST structure may or
|
| - * may not be resolved, and may have a slightly different structure depending upon whether it is
|
| - * resolved.
|
| + * Parse a single HTML [source] to produce an AST structure. The resulting
|
| + * HTML AST structure may or may not be resolved, and may have a slightly
|
| + * different structure depending upon whether it is resolved.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if the analysis could not be performed
|
| *
|
| - * @param source the HTML source to be parsed
|
| - * @return the parse result (not `null`)
|
| - * @throws AnalysisException if the analysis could not be performed
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| ht.HtmlUnit parseHtmlUnit(Source source);
|
|
|
| /**
|
| - * Perform the next unit of work required to keep the analysis results up-to-date and return
|
| - * information about the consequent changes to the analysis results. This method can be long
|
| - * running.
|
| - *
|
| - * @return the results of performing the analysis
|
| + * Perform the next unit of work required to keep the analysis results
|
| + * up-to-date and return information about the consequent changes to the
|
| + * analysis results. This method can be long running.
|
| */
|
| AnalysisResult performAnalysisTask();
|
|
|
| /**
|
| - * Remove the given listener from the list of objects that are to be notified when various
|
| - * analysis results are produced in this context.
|
| - *
|
| - * @param listener the listener to be removed
|
| + * Remove the given [listener] from the list of objects that are to be
|
| + * notified when various analysis results are produced in this context.
|
| */
|
| void removeListener(AnalysisListener listener);
|
|
|
| /**
|
| - * Parse and resolve a single source within the given context to produce a fully resolved AST.
|
| + * Return a fully resolved AST for the compilation unit defined by the given
|
| + * [unitSource] within the given [library].
|
| + *
|
| + * Throws an [AnalysisException] if the analysis could not be performed.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| *
|
| - * @param unitSource the source to be parsed and resolved
|
| - * @param library the library containing the source to be resolved
|
| - * @return the result of resolving the AST structure representing the content of the source in the
|
| - * context of the given library
|
| - * @throws AnalysisException if the analysis could not be performed
|
| * See [getResolvedCompilationUnit].
|
| */
|
| CompilationUnit resolveCompilationUnit(
|
| Source unitSource, LibraryElement library);
|
|
|
| /**
|
| - * Parse and resolve a single source within the given context to produce a fully resolved AST.
|
| - * Return the resolved AST structure, or `null` if the source could not be either parsed or
|
| - * resolved.
|
| + * Return a fully resolved AST for the compilation unit defined by the given
|
| + * [unitSource] within the library defined by the given [librarySource].
|
| + *
|
| + * Throws an [AnalysisException] if the analysis could not be performed.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| *
|
| - * @param unitSource the source to be parsed and resolved
|
| - * @param librarySource the source of the defining compilation unit of the library containing the
|
| - * source to be resolved
|
| - * @return the result of resolving the AST structure representing the content of the source in the
|
| - * context of the given library
|
| - * @throws AnalysisException if the analysis could not be performed
|
| - * See [getResolvedCompilationUnit].
|
| + * See [getResolvedCompilationUnit2].
|
| */
|
| CompilationUnit resolveCompilationUnit2(
|
| Source unitSource, Source librarySource);
|
|
|
| /**
|
| - * Parse and resolve a single source within the given context to produce a fully resolved AST.
|
| + * Parse and resolve a single [htmlSource] within the given context to produce
|
| + * a fully resolved AST.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if the analysis could not be performed.
|
| *
|
| - * @param htmlSource the source to be parsed and resolved
|
| - * @return the result of resolving the AST structure representing the content of the source
|
| - * @throws AnalysisException if the analysis could not be performed
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| ht.HtmlUnit resolveHtmlUnit(Source htmlSource);
|
|
|
| /**
|
| - * Set the contents of the given source to the given contents and mark the source as having
|
| - * changed. The additional offset and length information is used by the context to determine what
|
| - * reanalysis is necessary.
|
| - *
|
| - * @param source the source whose contents are being overridden
|
| - * @param contents the text to replace the range in the current contents
|
| - * @param offset the offset into the current contents
|
| - * @param oldLength the number of characters in the original contents that were replaced
|
| - * @param newLength the number of characters in the replacement text
|
| + * Set the contents of the given [source] to the given [contents] and mark the
|
| + * source as having changed. The additional [offset] and [length] information
|
| + * is used by the context to determine what reanalysis is necessary.
|
| */
|
| void setChangedContents(
|
| Source source, String contents, int offset, int oldLength, int newLength);
|
|
|
| /**
|
| - * Set the contents of the given source to the given contents and mark the source as having
|
| - * changed. This has the effect of overriding the default contents of the source. If the contents
|
| - * are `null` the override is removed so that the default contents will be returned.
|
| - *
|
| - * @param source the source whose contents are being overridden
|
| - * @param contents the new contents of the source
|
| + * Set the contents of the given [source] to the given [contents] and mark the
|
| + * source as having changed. This has the effect of overriding the default
|
| + * contents of the source. If the contents are `null` the override is removed
|
| + * so that the default contents will be returned.
|
| */
|
| void setContents(Source source, String contents);
|
| }
|
|
|
| /**
|
| - * Instances of the class `AnalysisContextImpl` implement an [AnalysisContext].
|
| + * An [AnalysisContext].
|
| */
|
| class AnalysisContextImpl implements InternalAnalysisContext {
|
| /**
|
| - * The difference between the maximum cache size and the maximum priority order size. The priority
|
| - * list must be capped so that it is less than the cache size. Failure to do so can result in an
|
| - * infinite loop in performAnalysisTask() because re-caching one AST structure can cause another
|
| - * priority source's AST structure to be flushed.
|
| + * The difference between the maximum cache size and the maximum priority
|
| + * order size. The priority list must be capped so that it is less than the
|
| + * cache size. Failure to do so can result in an infinite loop in
|
| + * performAnalysisTask() because re-caching one AST structure can cause
|
| + * another priority source's AST structure to be flushed.
|
| */
|
| static int _PRIORITY_ORDER_SIZE_DELTA = 4;
|
|
|
| /**
|
| - * A flag indicating whether trace output should be produced as analysis tasks are performed. Used
|
| - * for debugging.
|
| + * A flag indicating whether trace output should be produced as analysis tasks
|
| + * are performed. Used for debugging.
|
| */
|
| static bool _TRACE_PERFORM_TASK = false;
|
|
|
| @@ -1001,7 +887,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| ContentCache _contentCache = new ContentCache();
|
|
|
| /**
|
| - * The source factory used to create the sources that can be analyzed in this context.
|
| + * The source factory used to create the sources that can be analyzed in this
|
| + * context.
|
| */
|
| SourceFactory _sourceFactory;
|
|
|
| @@ -1021,17 +908,19 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| Source _asyncLibrarySource;
|
|
|
| /**
|
| - * The partition that contains analysis results that are not shared with other contexts.
|
| + * The partition that contains analysis results that are not shared with other
|
| + * contexts.
|
| */
|
| CachePartition _privatePartition;
|
|
|
| /**
|
| - * A table mapping the sources known to the context to the information known about the source.
|
| + * A table mapping the sources known to the context to the information known
|
| + * about the source.
|
| */
|
| AnalysisCache _cache;
|
|
|
| /**
|
| - * An array containing sources for which data should not be flushed.
|
| + * A list containing sources for which data should not be flushed.
|
| */
|
| List<Source> _priorityOrder = Source.EMPTY_ARRAY;
|
|
|
| @@ -1051,14 +940,14 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| new HashMap<Source, List<PendingFuture>>();
|
|
|
| /**
|
| - * An array containing sources whose AST structure is needed in order to resolve the next library
|
| - * to be resolved.
|
| + * A list containing sources whose AST structure is needed in order to resolve
|
| + * the next library to be resolved.
|
| */
|
| HashSet<Source> _neededForResolution = null;
|
|
|
| /**
|
| - * A table mapping sources to the change notices that are waiting to be returned related to that
|
| - * source.
|
| + * A table mapping sources to the change notices that are waiting to be
|
| + * returned related to that source.
|
| */
|
| HashMap<Source, ChangeNoticeImpl> _pendingNotices =
|
| new HashMap<Source, ChangeNoticeImpl>();
|
| @@ -1069,8 +958,7 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| AnalysisContextImpl_AnalysisTaskResultRecorder _resultRecorder;
|
|
|
| /**
|
| - * Cached information used in incremental analysis or `null` if none. Synchronize against
|
| - * [cacheLock] before accessing this field.
|
| + * Cached information used in incremental analysis or `null` if none.
|
| */
|
| IncrementalAnalysisCache _incrementalAnalysisCache;
|
|
|
| @@ -1095,22 +983,21 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| StreamController<SourcesChangedEvent> _onSourcesChangedController;
|
|
|
| /**
|
| - * The listeners that are to be notified when various analysis results are produced in this
|
| - * context.
|
| + * The listeners that are to be notified when various analysis results are
|
| + * produced in this context.
|
| */
|
| List<AnalysisListener> _listeners = new List<AnalysisListener>();
|
|
|
| /**
|
| - * The most recently incrementally resolved [Source].
|
| - * Is null when it was already validated, or the most recent change was
|
| - * not incrementally resolved.
|
| + * The most recently incrementally resolved source, or `null` when it was
|
| + * already validated, or the most recent change was not incrementally resolved.
|
| */
|
| Source incrementalResolutionValidation_lastUnitSource;
|
|
|
| /**
|
| - * The most recently incrementally resolved library [Source].
|
| - * Is null when it was already validated, or the most recent change was
|
| - * not incrementally resolved.
|
| + * The most recently incrementally resolved library source, or `null` when it
|
| + * was already validated, or the most recent change was not incrementally
|
| + * resolved.
|
| */
|
| Source incrementalResolutionValidation_lastLibrarySource;
|
|
|
| @@ -1120,10 +1007,14 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| */
|
| CompilationUnit incrementalResolutionValidation_lastUnit;
|
|
|
| - /** A factory to override how [ResolverVisitor] is created. */
|
| + /**
|
| + * A factory to override how the [ResolverVisitor] is created.
|
| + */
|
| ResolverVisitorFactory resolverVisitorFactory;
|
|
|
| - /** A factory to override how [TypeResolverVisitor] is created. */
|
| + /**
|
| + * A factory to override how the [TypeResolverVisitor] is created.
|
| + */
|
| TypeResolverVisitorFactory typeResolverVisitorFactory;
|
|
|
| /**
|
| @@ -1273,10 +1164,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| List<Source> get librarySources => _getSources(SourceKind.LIBRARY);
|
|
|
| /**
|
| - * Look through the cache for a task that needs to be performed. Return the task that was found,
|
| - * or `null` if there is no more work to be done.
|
| - *
|
| - * @return the next task that needs to be performed
|
| + * Look through the cache for a task that needs to be performed. Return the
|
| + * task that was found, or `null` if there is no more work to be done.
|
| */
|
| AnalysisTask get nextAnalysisTask {
|
| bool hintsEnabled = _options.hint;
|
| @@ -1473,11 +1362,10 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return a list of the sources that would be processed by [performAnalysisTask]. This
|
| - * method duplicates, and must therefore be kept in sync with, [getNextAnalysisTask].
|
| - * This method is intended to be used for testing purposes only.
|
| - *
|
| - * @return a list of the sources that would be processed by [performAnalysisTask]
|
| + * Return a list of the sources that would be processed by
|
| + * [performAnalysisTask]. This method duplicates, and must therefore be kept
|
| + * in sync with, [getNextAnalysisTask]. This method is intended to be used for
|
| + * testing purposes only.
|
| */
|
| List<Source> get sourcesNeedingProcessing {
|
| HashSet<Source> sources = new HashSet<Source>();
|
| @@ -1822,10 +1710,7 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Create an analysis cache based on the given source factory.
|
| - *
|
| - * @param factory the source factory containing the information needed to create the cache
|
| - * @return the cache that was created
|
| + * Create an analysis cache based on the given source [factory].
|
| */
|
| AnalysisCache createCacheFromSourceFactory(SourceFactory factory) {
|
| if (factory == null) {
|
| @@ -2168,11 +2053,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return the cache entry associated with the given source, or `null` if there is no entry
|
| - * associated with the source.
|
| - *
|
| - * @param source the source for which a cache entry is being sought
|
| - * @return the source cache entry associated with the given source
|
| + * Return the cache entry associated with the given [source], or `null` if
|
| + * there is no entry associated with the source.
|
| */
|
| SourceEntry getReadableSourceEntryOrNull(Source source) => _cache.get(source);
|
|
|
| @@ -2687,22 +2569,17 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Record that we have accessed the AST structure associated with the given source. At the moment,
|
| - * there is no differentiation between the parsed and resolved forms of the AST.
|
| - *
|
| - * @param source the source whose AST structure was accessed
|
| + * Record that we have accessed the AST structure associated with the given
|
| + * [source]. At the moment, there is no differentiation between the parsed and
|
| + * resolved forms of the AST.
|
| */
|
| void _accessedAst(Source source) {
|
| _cache.accessedAst(source);
|
| }
|
|
|
| /**
|
| - * Add all of the sources contained in the given source container to the given list of sources.
|
| - *
|
| - * Note: This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * @param sources the list to which sources are to be added
|
| - * @param container the source container containing the sources to be added to the list
|
| + * Add all of the sources contained in the given source [container] to the
|
| + * given list of [sources].
|
| */
|
| void _addSourcesInContainer(List<Source> sources, SourceContainer container) {
|
| MapIterator<Source, SourceEntry> iterator = _cache.iterator();
|
| @@ -2715,19 +2592,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file and the library that contains it, return a cache entry in which
|
| - * the state of the data represented by the given descriptor is either [CacheState.VALID] or
|
| - * [CacheStateERROR]. This method assumes that the data can be produced by generating hints
|
| - * for the library if the data is not already cached.
|
| - *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Given the [unitSource] of a Dart file and the [librarySource] of the
|
| + * library that contains it, return a cache entry in which the state of the
|
| + * data represented by the given [descriptor] is either [CacheState.VALID] or
|
| + * [CacheState.ERROR]. This method assumes that the data can be produced by
|
| + * generating hints for the library if the data is not already cached. The
|
| + * [dartEntry] is the cache entry associated with the Dart file.
|
| *
|
| - * @param unitSource the source representing the Dart file
|
| - * @param librarySource the source representing the library containing the Dart file
|
| - * @param dartEntry the cache entry associated with the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return a cache entry containing the required data
|
| - * @throws AnalysisException if data could not be returned because the source could not be parsed
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be parsed.
|
| */
|
| DartEntry _cacheDartHintData(Source unitSource, Source librarySource,
|
| DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -2775,19 +2648,13 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file and the library that contains it, return a cache entry in which
|
| - * the state of the data represented by the given descriptor is either [CacheState.VALID] or
|
| - * [CacheStateERROR]. This method assumes that the data can be produced by generating lints
|
| - * for the library if the data is not already cached.
|
| + * Given a source for a Dart file and the library that contains it, return a
|
| + * cache entry in which the state of the data represented by the given
|
| + * descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This method
|
| + * assumes that the data can be produced by generating lints for the library
|
| + * if the data is not already cached.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| - *
|
| - * @param unitSource the source representing the Dart file
|
| - * @param librarySource the source representing the library containing the Dart file
|
| - * @param dartEntry the cache entry associated with the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return a cache entry containing the required data
|
| - * @throws AnalysisException if data could not be returned because the source could not be parsed
|
| */
|
| DartEntry _cacheDartLintData(Source unitSource, Source librarySource,
|
| DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -2836,17 +2703,12 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file, return a cache entry in which the state of the data represented
|
| - * by the given descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This
|
| - * method assumes that the data can be produced by parsing the source if it is not already cached.
|
| + * Given a source for a Dart file, return a cache entry in which the state of
|
| + * the data represented by the given descriptor is either [CacheState.VALID]
|
| + * or [CacheState.ERROR]. This method assumes that the data can be produced by
|
| + * parsing the source if it is not already cached.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| - *
|
| - * @param source the source representing the Dart file
|
| - * @param dartEntry the cache entry associated with the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return a cache entry containing the required data
|
| - * @throws AnalysisException if data could not be returned because the source could not be parsed
|
| */
|
| DartEntry _cacheDartParseData(
|
| Source source, DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -2875,19 +2737,13 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file and the library that contains it, return a cache entry in which
|
| - * the state of the data represented by the given descriptor is either [CacheState.VALID] or
|
| - * [CacheState.ERROR]. This method assumes that the data can be produced by resolving the
|
| - * source in the context of the library if it is not already cached.
|
| + * Given a source for a Dart file and the library that contains it, return a
|
| + * cache entry in which the state of the data represented by the given
|
| + * descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This method
|
| + * assumes that the data can be produced by resolving the source in the
|
| + * context of the library if it is not already cached.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| - *
|
| - * @param unitSource the source representing the Dart file
|
| - * @param librarySource the source representing the library containing the Dart file
|
| - * @param dartEntry the cache entry associated with the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return a cache entry containing the required data
|
| - * @throws AnalysisException if data could not be returned because the source could not be parsed
|
| */
|
| DartEntry _cacheDartResolutionData(Source unitSource, Source librarySource,
|
| DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -2915,18 +2771,12 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file, return a cache entry in which the state of the data represented
|
| - * by the given descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This
|
| - * method assumes that the data can be produced by scanning the source if it is not already
|
| - * cached.
|
| + * Given a source for a Dart file, return a cache entry in which the state of
|
| + * the data represented by the given descriptor is either [CacheState.VALID]
|
| + * or [CacheState.ERROR]. This method assumes that the data can be produced by
|
| + * scanning the source if it is not already cached.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| - *
|
| - * @param source the source representing the Dart file
|
| - * @param dartEntry the cache entry associated with the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return a cache entry containing the required data
|
| - * @throws AnalysisException if data could not be returned because the source could not be scanned
|
| */
|
| DartEntry _cacheDartScanData(
|
| Source source, DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -2959,19 +2809,13 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file and the library that contains it, return a cache entry in which
|
| - * the state of the data represented by the given descriptor is either [CacheState.VALID] or
|
| - * [CacheState.ERROR]. This method assumes that the data can be produced by verifying the
|
| - * source in the given library if the data is not already cached.
|
| + * Given a source for a Dart file and the library that contains it, return a
|
| + * cache entry in which the state of the data represented by the given
|
| + * descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This method
|
| + * assumes that the data can be produced by verifying the source in the given
|
| + * library if the data is not already cached.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| - *
|
| - * @param unitSource the source representing the Dart file
|
| - * @param librarySource the source representing the library containing the Dart file
|
| - * @param dartEntry the cache entry associated with the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return a cache entry containing the required data
|
| - * @throws AnalysisException if data could not be returned because the source could not be parsed
|
| */
|
| DartEntry _cacheDartVerificationData(Source unitSource, Source librarySource,
|
| DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -2998,19 +2842,12 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for an HTML file, return a cache entry in which all of the data represented by
|
| - * the state of the given descriptors is either [CacheState.VALID] or
|
| - * [CacheState.ERROR]. This method assumes that the data can be produced by parsing the
|
| - * source if it is not already cached.
|
| + * Given a source for an HTML file, return a cache entry in which all of the
|
| + * data represented by the state of the given descriptors is either
|
| + * [CacheState.VALID] or [CacheState.ERROR]. This method assumes that the data
|
| + * can be produced by parsing the source if it is not already cached.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| - *
|
| - * @param source the source representing the HTML file
|
| - * @param htmlEntry the cache entry associated with the HTML file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return a cache entry containing the required data
|
| - * @throws AnalysisException if data could not be returned because the source could not be
|
| - * resolved
|
| */
|
| HtmlEntry _cacheHtmlParseData(
|
| Source source, HtmlEntry htmlEntry, DataDescriptor descriptor) {
|
| @@ -3049,19 +2886,12 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for an HTML file, return a cache entry in which the state of the data
|
| - * represented by the given descriptor is either [CacheState.VALID] or
|
| - * [CacheState.ERROR]. This method assumes that the data can be produced by resolving the
|
| - * source if it is not already cached.
|
| + * Given a source for an HTML file, return a cache entry in which the state of
|
| + * the data represented by the given descriptor is either [CacheState.VALID]
|
| + * or [CacheState.ERROR]. This method assumes that the data can be produced by
|
| + * resolving the source if it is not already cached.
|
| *
|
| * <b>Note:</b> This method cannot be used in an async environment.
|
| - *
|
| - * @param source the source representing the HTML file
|
| - * @param dartEntry the cache entry associated with the HTML file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return a cache entry containing the required data
|
| - * @throws AnalysisException if data could not be returned because the source could not be
|
| - * resolved
|
| */
|
| HtmlEntry _cacheHtmlResolutionData(
|
| Source source, HtmlEntry htmlEntry, DataDescriptor descriptor) {
|
| @@ -3099,11 +2929,9 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Compute the transitive closure of all libraries that depend on the given library by adding such
|
| - * libraries to the given collection.
|
| - *
|
| - * @param library the library on which the other libraries depend
|
| - * @param librariesToInvalidate the libraries that depend on the given library
|
| + * Compute the transitive closure of all libraries that depend on the given
|
| + * [library] by adding such libraries to the given collection of
|
| + * [librariesToInvalidate].
|
| */
|
| void _computeAllLibrariesDependingOn(
|
| Source library, HashSet<Source> librariesToInvalidate) {
|
| @@ -3116,11 +2944,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Compute the priority that should be used when the source associated with the given entry is
|
| - * added to the work manager.
|
| - *
|
| - * @param dartEntry the entry associated with the source
|
| - * @return the priority that was computed
|
| + * Return the priority that should be used when the source associated with
|
| + * the given [dartEntry] is added to the work manager.
|
| */
|
| SourcePriority _computePriority(DartEntry dartEntry) {
|
| SourceKind kind = dartEntry.kind;
|
| @@ -3133,20 +2958,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given the encoded form of a source, use the source factory to reconstitute the original source.
|
| - *
|
| - * @param encoding the encoded form of a source
|
| - * @return the source represented by the encoding
|
| + * Given the encoded form of a source ([encoding]), use the source factory to
|
| + * reconstitute the original source.
|
| */
|
| Source _computeSourceFromEncoding(String encoding) =>
|
| _sourceFactory.fromEncoding(encoding);
|
|
|
| /**
|
| - * Return `true` if the given array of sources contains the given source.
|
| - *
|
| - * @param sources the sources being searched
|
| - * @param targetSource the source being searched for
|
| - * @return `true` if the given source is in the array
|
| + * Return `true` if the given list of [sources] contains the given
|
| + * [targetSource].
|
| */
|
| bool _contains(List<Source> sources, Source targetSource) {
|
| for (Source source in sources) {
|
| @@ -3158,11 +2978,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return `true` if the given array of sources contains any of the given target sources.
|
| - *
|
| - * @param sources the sources being searched
|
| - * @param targetSources the sources being searched for
|
| - * @return `true` if any of the given target sources are in the array
|
| + * Return `true` if the given list of [sources] contains any of the given
|
| + * [targetSources].
|
| */
|
| bool _containsAny(List<Source> sources, List<Source> targetSources) {
|
| for (Source targetSource in targetSources) {
|
| @@ -3174,16 +2991,11 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Set the contents of the given source to the given contents and mark the source as having
|
| - * changed. The additional offset and length information is used by the context to determine what
|
| - * reanalysis is necessary. [setChangedContents] triggers a source changed event
|
| - * where as this method does not.
|
| - *
|
| - * @param source the source whose contents are being overridden
|
| - * @param contents the text to replace the range in the current contents
|
| - * @param offset the offset into the current contents
|
| - * @param oldLength the number of characters in the original contents that were replaced
|
| - * @param newLength the number of characters in the replacement text
|
| + * Set the contents of the given [source] to the given [contents] and mark the
|
| + * source as having changed. The additional [offset], [oldLength] and
|
| + * [newLength] information is used by the context to determine what reanalysis
|
| + * is necessary. The method [setChangedContents] triggers a source changed
|
| + * event where as this method does not.
|
| */
|
| bool _contentRangeChanged(Source source, String contents, int offset,
|
| int oldLength, int newLength) {
|
| @@ -3215,44 +3027,22 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Set the contents of the given source to the given contents and mark the source as having
|
| - * changed. This has the effect of overriding the default contents of the source. If the contents
|
| - * are `null` the override is removed so that the default contents will be returned.
|
| - *
|
| - * If [notify] is true, a source changed event is triggered.
|
| - *
|
| - * @param source the source whose contents are being overridden
|
| - * @param contents the new contents of the source
|
| + * Set the contents of the given [source] to the given [contents] and mark the
|
| + * source as having changed. This has the effect of overriding the default
|
| + * contents of the source. If the contents are `null` the override is removed
|
| + * so that the default contents will be returned. If [notify] is true, a
|
| + * source changed event is triggered.
|
| */
|
| void _contentsChanged(Source source, String contents, bool notify) {
|
| String originalContents = _contentCache.setContents(source, contents);
|
| handleContentsChanged(source, originalContents, contents, notify);
|
| }
|
|
|
| -// /**
|
| -// * Create a [BuildUnitElementTask] for the given [source].
|
| -// */
|
| -// AnalysisContextImpl_TaskData _createBuildUnitElementTask(Source source,
|
| -// DartEntry dartEntry, Source librarySource) {
|
| -// CompilationUnit unit = dartEntry.resolvableCompilationUnit;
|
| -// if (unit == null) {
|
| -// return _createParseDartTask(source, dartEntry);
|
| -// }
|
| -// return new AnalysisContextImpl_TaskData(
|
| -// new BuildUnitElementTask(this, source, librarySource, unit),
|
| -// false);
|
| -// }
|
| -
|
| /**
|
| - * Create a [GenerateDartErrorsTask] for the given source, marking the verification errors
|
| - * as being in-process. The compilation unit and the library can be the same if the compilation
|
| - * unit is the defining compilation unit of the library.
|
| - *
|
| - * @param unitSource the source for the compilation unit to be verified
|
| - * @param unitEntry the entry for the compilation unit
|
| - * @param librarySource the source for the library containing the compilation unit
|
| - * @param libraryEntry the entry for the library
|
| - * @return task data representing the created task
|
| + * Create a [GenerateDartErrorsTask] for the given [unitSource], marking the
|
| + * verification errors as being in-process. The compilation unit and the
|
| + * library can be the same if the compilation unit is the defining compilation
|
| + * unit of the library.
|
| */
|
| AnalysisContextImpl_TaskData _createGenerateDartErrorsTask(Source unitSource,
|
| DartEntry unitEntry, Source librarySource, DartEntry libraryEntry) {
|
| @@ -3279,14 +3069,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Create a [GenerateDartHintsTask] for the given source, marking the hints as being
|
| - * in-process.
|
| - *
|
| - * @param source the source whose content is to be verified
|
| - * @param dartEntry the entry for the source
|
| - * @param librarySource the source for the library containing the source
|
| - * @param libraryEntry the entry for the library
|
| - * @return task data representing the created task
|
| + * Create a [GenerateDartHintsTask] for the given [source], marking the hints
|
| + * as being in-process.
|
| */
|
| AnalysisContextImpl_TaskData _createGenerateDartHintsTask(Source source,
|
| DartEntry dartEntry, Source librarySource, DartEntry libraryEntry) {
|
| @@ -3318,14 +3102,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Create a [GenerateDartLintsTask] for the given source, marking the lints as
|
| - * being in-process.
|
| - *
|
| - * @param source the source whose content is to be verified
|
| - * @param dartEntry the entry for the source
|
| - * @param librarySource the source for the library containing the source
|
| - * @param libraryEntry the entry for the library
|
| - * @return task data representing the created task
|
| + * Create a [GenerateDartLintsTask] for the given [source], marking the lints
|
| + * as being in-process.
|
| */
|
| AnalysisContextImpl_TaskData _createGenerateDartLintsTask(Source source,
|
| DartEntry dartEntry, Source librarySource, DartEntry libraryEntry) {
|
| @@ -3358,11 +3136,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Create a [GetContentTask] for the given source, marking the content as being in-process.
|
| - *
|
| - * @param source the source whose content is to be accessed
|
| - * @param sourceEntry the entry for the source
|
| - * @return task data representing the created task
|
| + * Create a [GetContentTask] for the given [source], marking the content as
|
| + * being in-process.
|
| */
|
| AnalysisContextImpl_TaskData _createGetContentTask(
|
| Source source, SourceEntry sourceEntry) {
|
| @@ -3400,11 +3175,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Create a [ResolveDartLibraryTask] for the given source, marking ? as being in-process.
|
| - *
|
| - * @param source the source whose content is to be resolved
|
| - * @param dartEntry the entry for the source
|
| - * @return task data representing the created task
|
| + * Create a [ResolveDartLibraryTask] for the given [source], marking ? as
|
| + * being in-process.
|
| */
|
| AnalysisContextImpl_TaskData _createResolveDartLibraryTask(
|
| Source source, DartEntry dartEntry) {
|
| @@ -3431,12 +3203,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Create a [ResolveHtmlTask] for the given source, marking the resolved unit as being
|
| - * in-process.
|
| - *
|
| - * @param source the source whose content is to be resolved
|
| - * @param htmlEntry the entry for the source
|
| - * @return task data representing the created task
|
| + * Create a [ResolveHtmlTask] for the given [source], marking the resolved
|
| + * unit as being in-process.
|
| */
|
| AnalysisContextImpl_TaskData _createResolveHtmlTask(
|
| Source source, HtmlEntry htmlEntry) {
|
| @@ -3449,12 +3217,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Create a [ScanDartTask] for the given source, marking the scan errors as being
|
| - * in-process.
|
| - *
|
| - * @param source the source whose content is to be scanned
|
| - * @param dartEntry the entry for the source
|
| - * @return task data representing the created task
|
| + * Create a [ScanDartTask] for the given [source], marking the scan errors as
|
| + * being in-process.
|
| */
|
| AnalysisContextImpl_TaskData _createScanDartTask(
|
| Source source, DartEntry dartEntry) {
|
| @@ -3468,12 +3232,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Create a source information object suitable for the given source. Return the source information
|
| - * object that was created, or `null` if the source should not be tracked by this context.
|
| - *
|
| - * @param source the source for which an information object is being created
|
| - * @param explicitlyAdded `true` if the source was explicitly added to the context
|
| - * @return the source information object that was created
|
| + * Create a source entry for the given [source]. Return the source entry that
|
| + * was created, or `null` if the source should not be tracked by this context.
|
| */
|
| SourceEntry _createSourceEntry(Source source, bool explicitlyAdded) {
|
| String name = source.shortName;
|
| @@ -3493,12 +3253,9 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return an array containing all of the change notices that are waiting to be returned. If there
|
| - * are no notices, then return either `null` or an empty array, depending on the value of
|
| - * the argument.
|
| - *
|
| - * @param nullIfEmpty `true` if `null` should be returned when there are no notices
|
| - * @return the change notices that are waiting to be returned
|
| + * Return a list containing all of the change notices that are waiting to be
|
| + * returned. If there are no notices, then return either `null` or an empty
|
| + * list, depending on the value of [nullIfEmpty].
|
| */
|
| List<ChangeNotice> _getChangeNotices(bool nullIfEmpty) {
|
| if (_pendingNotices.isEmpty) {
|
| @@ -3513,19 +3270,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file and the library that contains it, return the data represented by
|
| - * the given descriptor that is associated with that source. This method assumes that the data can
|
| - * be produced by generating hints for the library if it is not already cached.
|
| + * Given a source for a Dart file and the library that contains it, return the
|
| + * data represented by the given descriptor that is associated with that
|
| + * source. This method assumes that the data can be produced by generating
|
| + * hints for the library if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be resolved.
|
| *
|
| - * @param unitSource the source representing the Dart file
|
| - * @param librarySource the source representing the library containing the Dart file
|
| - * @param dartEntry the entry representing the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be
|
| - * resolved
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getDartHintData(Source unitSource, Source librarySource,
|
| DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -3538,19 +3291,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file and the library that contains it, return the data represented by
|
| - * the given descriptor that is associated with that source. This method assumes that the data can
|
| - * be produced by generating lints for the library if it is not already cached.
|
| + * Given a source for a Dart file and the library that contains it, return the
|
| + * data represented by the given descriptor that is associated with that
|
| + * source. This method assumes that the data can be produced by generating
|
| + * lints for the library if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be resolved.
|
| *
|
| - * @param unitSource the source representing the Dart file
|
| - * @param librarySource the source representing the library containing the Dart file
|
| - * @param dartEntry the entry representing the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be
|
| - * resolved
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getDartLintData(Source unitSource, Source librarySource,
|
| DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -3563,17 +3312,14 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file, return the data represented by the given descriptor that is
|
| - * associated with that source. This method assumes that the data can be produced by parsing the
|
| - * source if it is not already cached.
|
| + * Given a source for a Dart file, return the data represented by the given
|
| + * descriptor that is associated with that source. This method assumes that
|
| + * the data can be produced by parsing the source if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be parsed.
|
| *
|
| - * @param source the source representing the Dart file
|
| - * @param dartEntry the cache entry associated with the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be parsed
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getDartParseData(
|
| Source source, DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -3586,17 +3332,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file, return the data represented by the given descriptor that is
|
| - * associated with that source, or the given default value if the source is not a Dart file. This
|
| - * method assumes that the data can be produced by parsing the source if it is not already cached.
|
| + * Given a source for a Dart file, return the data represented by the given
|
| + * descriptor that is associated with that source, or the given default value
|
| + * if the source is not a Dart file. This method assumes that the data can be
|
| + * produced by parsing the source if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be parsed.
|
| *
|
| - * @param source the source representing the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @param defaultValue the value to be returned if the source is not a Dart file
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be parsed
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getDartParseData2(
|
| Source source, DataDescriptor descriptor, Object defaultValue) {
|
| @@ -3615,19 +3359,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file and the library that contains it, return the data represented by
|
| - * the given descriptor that is associated with that source. This method assumes that the data can
|
| - * be produced by resolving the source in the context of the library if it is not already cached.
|
| + * Given a source for a Dart file and the library that contains it, return the
|
| + * data represented by the given descriptor that is associated with that
|
| + * source. This method assumes that the data can be produced by resolving the
|
| + * source in the context of the library if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be resolved.
|
| *
|
| - * @param unitSource the source representing the Dart file
|
| - * @param librarySource the source representing the library containing the Dart file
|
| - * @param dartEntry the entry representing the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be
|
| - * resolved
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getDartResolutionData(Source unitSource, Source librarySource,
|
| DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -3642,20 +3382,16 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file and the library that contains it, return the data represented by
|
| - * the given descriptor that is associated with that source, or the given default value if the
|
| - * source is not a Dart file. This method assumes that the data can be produced by resolving the
|
| - * source in the context of the library if it is not already cached.
|
| + * Given a source for a Dart file and the library that contains it, return the
|
| + * data represented by the given descriptor that is associated with that
|
| + * source, or the given default value if the source is not a Dart file. This
|
| + * method assumes that the data can be produced by resolving the source in the
|
| + * context of the library if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be resolved.
|
| *
|
| - * @param unitSource the source representing the Dart file
|
| - * @param librarySource the source representing the library containing the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @param defaultValue the value to be returned if the source is not a Dart file
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be
|
| - * resolved
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getDartResolutionData2(Source unitSource, Source librarySource,
|
| DataDescriptor descriptor, Object defaultValue) {
|
| @@ -3675,17 +3411,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file, return the data represented by the given descriptor that is
|
| - * associated with that source. This method assumes that the data can be produced by scanning the
|
| - * source if it is not already cached.
|
| + * Given a source for a Dart file, return the data represented by the given
|
| + * descriptor that is associated with that source. This method assumes that
|
| + * the data can be produced by scanning the source if it is not already
|
| + * cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be scanned.
|
| *
|
| - * @param source the source representing the Dart file
|
| - * @param dartEntry the cache entry associated with the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be scanned
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getDartScanData(
|
| Source source, DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -3694,18 +3428,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file, return the data represented by the given descriptor that is
|
| - * associated with that source, or the given default value if the source is not a Dart file. This
|
| - * method assumes that the data can be produced by scanning the source if it is not already
|
| - * cached.
|
| + * Given a source for a Dart file, return the data represented by the given
|
| + * descriptor that is associated with that source, or the given default value
|
| + * if the source is not a Dart file. This method assumes that the data can be
|
| + * produced by scanning the source if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be scanned.
|
| *
|
| - * @param source the source representing the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @param defaultValue the value to be returned if the source is not a Dart file
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be scanned
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getDartScanData2(
|
| Source source, DataDescriptor descriptor, Object defaultValue) {
|
| @@ -3724,19 +3455,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for a Dart file and the library that contains it, return the data represented by
|
| - * the given descriptor that is associated with that source. This method assumes that the data can
|
| - * be produced by verifying the source within the given library if it is not already cached.
|
| + * Given a source for a Dart file and the library that contains it, return the
|
| + * data represented by the given descriptor that is associated with that
|
| + * source. This method assumes that the data can be produced by verifying the
|
| + * source within the given library if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be resolved.
|
| *
|
| - * @param unitSource the source representing the Dart file
|
| - * @param librarySource the source representing the library containing the Dart file
|
| - * @param dartEntry the entry representing the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be
|
| - * resolved
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getDartVerificationData(Source unitSource, Source librarySource,
|
| DartEntry dartEntry, DataDescriptor descriptor) {
|
| @@ -3746,17 +3473,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for an HTML file, return the data represented by the given descriptor that is
|
| - * associated with that source, or the given default value if the source is not an HTML file. This
|
| - * method assumes that the data can be produced by parsing the source if it is not already cached.
|
| + * Given a source for an HTML file, return the data represented by the given
|
| + * descriptor that is associated with that source, or the given default value
|
| + * if the source is not an HTML file. This method assumes that the data can be
|
| + * produced by parsing the source if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be parsed.
|
| *
|
| - * @param source the source representing the Dart file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @param defaultValue the value to be returned if the source is not an HTML file
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be parsed
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getHtmlParseData(
|
| Source source, DataDescriptor descriptor, Object defaultValue) {
|
| @@ -3773,19 +3498,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for an HTML file, return the data represented by the given descriptor that is
|
| - * associated with that source, or the given default value if the source is not an HTML file. This
|
| - * method assumes that the data can be produced by resolving the source if it is not already
|
| - * cached.
|
| + * Given a source for an HTML file, return the data represented by the given
|
| + * descriptor that is associated with that source, or the given default value
|
| + * if the source is not an HTML file. This method assumes that the data can be
|
| + * produced by resolving the source if it is not already cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be resolved.
|
| *
|
| - * @param source the source representing the HTML file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @param defaultValue the value to be returned if the source is not an HTML file
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be
|
| - * resolved
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getHtmlResolutionData(
|
| Source source, DataDescriptor descriptor, Object defaultValue) {
|
| @@ -3804,18 +3525,15 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Given a source for an HTML file, return the data represented by the given descriptor that is
|
| - * associated with that source. This method assumes that the data can be produced by resolving the
|
| - * source if it is not already cached.
|
| + * Given a source for an HTML file, return the data represented by the given
|
| + * descriptor that is associated with that source. This method assumes that
|
| + * the data can be produced by resolving the source if it is not already
|
| + * cached.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment.
|
| + * Throws an [AnalysisException] if data could not be returned because the
|
| + * source could not be resolved.
|
| *
|
| - * @param source the source representing the HTML file
|
| - * @param htmlEntry the entry representing the HTML file
|
| - * @param descriptor the descriptor representing the data to be returned
|
| - * @return the requested data about the given source
|
| - * @throws AnalysisException if data could not be returned because the source could not be
|
| - * resolved
|
| + * <b>Note:</b> This method cannot be used in an async environment.
|
| */
|
| Object _getHtmlResolutionData2(
|
| Source source, HtmlEntry htmlEntry, DataDescriptor descriptor) {
|
| @@ -3827,18 +3545,9 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Look at the given source to see whether a task needs to be performed related to it. Return the
|
| - * task that should be performed, or `null` if there is no more work to be done for the
|
| - * source.
|
| - *
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * @param source the source to be checked
|
| - * @param sourceEntry the cache entry associated with the source
|
| - * @param isPriority `true` if the source is a priority source
|
| - * @param hintsEnabled `true` if hints are currently enabled
|
| - * @param lintsEnabled `true` if lints are currently enabled
|
| - * @return the next task that needs to be performed for the given source
|
| + * Look at the given [source] to see whether a task needs to be performed
|
| + * related to it. Return the task that should be performed, or `null` if there
|
| + * is no more work to be done for the source.
|
| */
|
| AnalysisContextImpl_TaskData _getNextAnalysisTaskForSource(Source source,
|
| SourceEntry sourceEntry, bool isPriority, bool hintsEnabled,
|
| @@ -3975,10 +3684,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return a change notice for the given source, creating one if one does not already exist.
|
| - *
|
| - * @param source the source for which changes are being reported
|
| - * @return a change notice for the given source
|
| + * Return a change notice for the given [source], creating one if one does not
|
| + * already exist.
|
| */
|
| ChangeNoticeImpl _getNotice(Source source) {
|
| ChangeNoticeImpl notice = _pendingNotices[source];
|
| @@ -3990,8 +3697,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return the cache entry associated with the given source, or `null` if the source is not a
|
| - * Dart file.
|
| + * Return the cache entry associated with the given [source], or `null` if the
|
| + * source is not a Dart file.
|
| *
|
| * @param source the source for which a cache entry is being sought
|
| * @return the source cache entry associated with the given source
|
| @@ -4008,11 +3715,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return the cache entry associated with the given source, or `null` if the source is not
|
| - * an HTML file.
|
| - *
|
| - * @param source the source for which a cache entry is being sought
|
| - * @return the source cache entry associated with the given source
|
| + * Return the cache entry associated with the given [source], or `null` if the
|
| + * source is not an HTML file.
|
| */
|
| HtmlEntry _getReadableHtmlEntry(Source source) {
|
| SourceEntry sourceEntry = _cache.get(source);
|
| @@ -4026,10 +3730,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return the cache entry associated with the given source, creating it if necessary.
|
| - *
|
| - * @param source the source for which a cache entry is being sought
|
| - * @return the source cache entry associated with the given source
|
| + * Return the cache entry associated with the given [source], creating it if
|
| + * necessary.
|
| */
|
| SourceEntry _getReadableSourceEntry(Source source) {
|
| SourceEntry sourceEntry = _cache.get(source);
|
| @@ -4040,12 +3742,9 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return a resolved compilation unit corresponding to the given element in the given library, or
|
| - * `null` if the information is not cached.
|
| - *
|
| - * @param element the element representing the compilation unit
|
| - * @param librarySource the source representing the library containing the unit
|
| - * @return the specified resolved compilation unit
|
| + * Return a resolved compilation unit corresponding to the given [element] in
|
| + * the library defined by the given [librarySource], or `null` if the
|
| + * information is not cached.
|
| */
|
| TimestampedData<CompilationUnit> _getResolvedUnit(
|
| CompilationUnitElement element, Source librarySource) {
|
| @@ -4063,10 +3762,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return an array containing all of the sources known to this context that have the given kind.
|
| - *
|
| - * @param kind the kind of sources to be returned
|
| - * @return all of the sources known to this context that have the given kind
|
| + * Return a list containing all of the sources known to this context that have
|
| + * the given [kind].
|
| */
|
| List<Source> _getSources(SourceKind kind) {
|
| List<Source> sources = new List<Source>();
|
| @@ -4080,20 +3777,11 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Look at the given source to see whether a task needs to be performed related to it. If so, add
|
| - * the source to the set of sources that need to be processed. This method duplicates, and must
|
| - * therefore be kept in sync with,
|
| - * [getNextAnalysisTask]. This method is intended to
|
| - * be used for testing purposes only.
|
| - *
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * @param source the source to be checked
|
| - * @param sourceEntry the cache entry associated with the source
|
| - * @param isPriority `true` if the source is a priority source
|
| - * @param hintsEnabled `true` if hints are currently enabled
|
| - * @param lintsEnabled `true` if lints are currently enabled
|
| - * @param sources the set to which sources should be added
|
| + * Look at the given [source] to see whether a task needs to be performed
|
| + * related to it. If so, add the source to the set of sources that need to be
|
| + * processed. This method duplicates, and must therefore be kept in sync with,
|
| + * [_getNextAnalysisTaskForSource]. This method is intended to be used for
|
| + * testing purposes only.
|
| */
|
| void _getSourcesNeedingProcessing(Source source, SourceEntry sourceEntry,
|
| bool isPriority, bool hintsEnabled, bool lintsEnabled,
|
| @@ -4198,12 +3886,9 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Invalidate all of the resolution results computed by this context.
|
| - *
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * @param invalidateUris `true` if the cached results of converting URIs to source files
|
| - * should also be invalidated.
|
| + * Invalidate all of the resolution results computed by this context. The flag
|
| + * [invalidateUris] should be `true` if the cached results of converting URIs
|
| + * to source files should also be invalidated.
|
| */
|
| void _invalidateAllLocalResolutionInformation(bool invalidateUris) {
|
| HashMap<Source, List<Source>> oldPartMap =
|
| @@ -4229,15 +3914,12 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * In response to a change to at least one of the compilation units in the given library,
|
| - * invalidate any results that are dependent on the result of resolving that library.
|
| + * In response to a change to at least one of the compilation units in the
|
| + * library defined by the given [librarySource], invalidate any results that
|
| + * are dependent on the result of resolving that library.
|
| *
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * <b>Note:</b> Any cache entries that were accessed before this method was invoked must be
|
| - * re-accessed after this method returns.
|
| - *
|
| - * @param librarySource the source of the library being invalidated
|
| + * <b>Note:</b> Any cache entries that were accessed before this method was
|
| + * invoked must be re-accessed after this method returns.
|
| */
|
| void _invalidateLibraryResolution(Source librarySource) {
|
| // TODO(brianwilkerson) This could be optimized. There's no need to flush
|
| @@ -4260,12 +3942,9 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Return `true` if this library is, or depends on, dart:html.
|
| - *
|
| - * @param library the library being tested
|
| - * @param visitedLibraries a collection of the libraries that have been visited, used to prevent
|
| - * infinite recursion
|
| - * @return `true` if this library is, or depends on, dart:html
|
| + * Return `true` if the given [library] is, or depends on, 'dart:html'. The
|
| + * [visitedLibraries] is a collection of the libraries that have been visited,
|
| + * used to prevent infinite recursion.
|
| */
|
| bool _isClient(LibraryElement library, Source htmlSource,
|
| HashSet<LibraryElement> visitedLibraries) {
|
| @@ -4293,9 +3972,7 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| false;
|
|
|
| /**
|
| - * Log the given debugging information.
|
| - *
|
| - * @param message the message to be added to the log
|
| + * Log the given debugging [message].
|
| */
|
| void _logInformation(String message) {
|
| AnalysisEngine.instance.logger.logInformation(message);
|
| @@ -4303,8 +3980,6 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
|
|
| /**
|
| * Notify all of the analysis listeners that a task is about to be performed.
|
| - *
|
| - * @param taskDescription a human readable description of the task that is about to be performed
|
| */
|
| void _notifyAboutToPerformTask(String taskDescription) {
|
| int count = _listeners.length;
|
| @@ -4314,12 +3989,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Notify all of the analysis listeners that the errors associated with the given source has been
|
| - * updated to the given errors.
|
| - *
|
| - * @param source the source containing the errors that were computed
|
| - * @param errors the errors that were computed
|
| - * @param lineInfo the line information associated with the source
|
| + * Notify all of the analysis listeners that the errors associated with the
|
| + * given [source] has been updated to the given [errors].
|
| */
|
| void _notifyErrors(
|
| Source source, List<AnalysisError> errors, LineInfo lineInfo) {
|
| @@ -4471,13 +4142,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| // }
|
|
|
| /**
|
| - * Given a cache entry and a library element, record the library element and other information
|
| - * gleaned from the element in the cache entry.
|
| - *
|
| - * @param dartCopy the cache entry in which data is to be recorded
|
| - * @param library the library element used to record information
|
| - * @param librarySource the source for the library used to record information
|
| - * @param htmlSource the source for the HTML library
|
| + * Given a [dartEntry] and a [library] element, record the library element and
|
| + * other information gleaned from the element in the cache entry.
|
| */
|
| void _recordElementData(DartEntry dartEntry, LibraryElement library,
|
| Source librarySource, Source htmlSource) {
|
| @@ -4620,11 +4286,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Record the results produced by performing a [IncrementalAnalysisTask].
|
| - *
|
| - * @param task the task that was performed
|
| - * @return an entry containing the computed results
|
| - * @throws AnalysisException if the results could not be recorded
|
| + * Record the results produced by performing a [task] and return the cache
|
| + * entry associated with the results.
|
| */
|
| DartEntry _recordIncrementalAnalysisTaskResults(
|
| IncrementalAnalysisTask task) {
|
| @@ -4799,13 +4462,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Remove the given library from the list of containing libraries for all of the parts referenced
|
| - * by the given entry.
|
| - *
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * @param librarySource the library to be removed
|
| - * @param dartEntry the entry containing the list of included parts
|
| + * Remove the given [librarySource] from the list of containing libraries for
|
| + * all of the parts referenced by the given [dartEntry].
|
| */
|
| void _removeFromParts(Source librarySource, DartEntry dartEntry) {
|
| List<Source> oldParts = dartEntry.getValue(DartEntry.INCLUDED_PARTS);
|
| @@ -4822,12 +4480,8 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Remove the given libraries that are keys in the given map from the list of containing libraries
|
| - * for each of the parts in the corresponding value.
|
| - *
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * @param oldPartMap the table containing the parts associated with each library
|
| + * Remove the given libraries that are keys in the given map from the list of
|
| + * containing libraries for each of the parts in the corresponding value.
|
| */
|
| void _removeFromPartsUsingMap(HashMap<Source, List<Source>> oldPartMap) {
|
| oldPartMap.forEach((Source librarySource, List<Source> oldParts) {
|
| @@ -4848,9 +4502,7 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Remove the given source from the priority order if it is in the list.
|
| - *
|
| - * @param source the source to be removed
|
| + * Remove the given [source] from the priority order if it is in the list.
|
| */
|
| void _removeFromPriorityOrder(Source source) {
|
| int count = _priorityOrder.length;
|
| @@ -4882,9 +4534,6 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| /**
|
| * Create an entry for the newly added [source] and invalidate any sources
|
| * that referenced the source before it existed.
|
| - *
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on
|
| - * [cacheLock].
|
| */
|
| void _sourceAvailable(Source source) {
|
| SourceEntry sourceEntry = _cache.get(source);
|
| @@ -4904,9 +4553,6 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| /**
|
| * Invalidate the [source] that was changed and any sources that referenced
|
| * the source before it existed.
|
| - *
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on
|
| - * [cacheLock].
|
| */
|
| void _sourceChanged(Source source) {
|
| SourceEntry sourceEntry = _cache.get(source);
|
| @@ -4930,9 +4576,7 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * @param source the source that has been deleted
|
| + * Record that the give [source] has been deleted.
|
| */
|
| void _sourceDeleted(Source source) {
|
| SourceEntry sourceEntry = _cache.get(source);
|
| @@ -4963,9 +4607,7 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * @param source the source that has been removed
|
| + * Record that the given [source] has been removed.
|
| */
|
| void _sourceRemoved(Source source) {
|
| SourceEntry sourceEntry = _cache.get(source);
|
| @@ -5050,13 +4692,10 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * Check the cache for any invalid entries (entries whose modification time does not match the
|
| - * modification time of the source associated with the entry). Invalid entries will be marked as
|
| - * invalid so that the source will be re-analyzed.
|
| - *
|
| - * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
|
| - *
|
| - * @return `true` if at least one entry was invalid
|
| + * Check the cache for any invalid entries (entries whose modification time
|
| + * does not match the modification time of the source associated with the
|
| + * entry). Invalid entries will be marked as invalid so that the source will
|
| + * be re-analyzed. Return `true` if at least one entry was invalid.
|
| */
|
| bool _validateCacheConsistency() {
|
| int consistencyCheckStart = JavaSystem.nanoTime();
|
| @@ -5138,8 +4777,7 @@ class AnalysisContextImpl implements InternalAnalysisContext {
|
| }
|
|
|
| /**
|
| - * An `AnalysisTaskResultRecorder` is used by an analysis context to record the
|
| - * results of a task.
|
| + * An object used by an analysis context to record the results of a task.
|
| */
|
| class AnalysisContextImpl_AnalysisTaskResultRecorder
|
| implements AnalysisTaskVisitor<SourceEntry> {
|
| @@ -5236,15 +4874,16 @@ class AnalysisContextImpl_ContextRetentionPolicy
|
| }
|
|
|
| /**
|
| - * Instances of the class `CycleBuilder` are used to construct a list of the libraries that
|
| - * must be resolved together in order to resolve any one of the libraries.
|
| + * An object used to construct a list of the libraries that must be resolved
|
| + * together in order to resolve any one of the libraries.
|
| */
|
| class AnalysisContextImpl_CycleBuilder {
|
| final AnalysisContextImpl AnalysisContextImpl_this;
|
|
|
| /**
|
| - * A table mapping the sources of the defining compilation units of libraries to the
|
| - * representation of the library that has the information needed to resolve the library.
|
| + * A table mapping the sources of the defining compilation units of libraries
|
| + * to the representation of the library that has the information needed to
|
| + * resolve the library.
|
| */
|
| HashMap<Source, ResolvableLibrary> _libraryMap =
|
| new HashMap<Source, ResolvableLibrary>();
|
| @@ -5260,8 +4899,8 @@ class AnalysisContextImpl_CycleBuilder {
|
| List<ResolvableLibrary> _librariesInCycle;
|
|
|
| /**
|
| - * The analysis task that needs to be performed before the cycle of libraries can be resolved,
|
| - * or `null` if the libraries are ready to be resolved.
|
| + * The analysis task that needs to be performed before the cycle of libraries
|
| + * can be resolved, or `null` if the libraries are ready to be resolved.
|
| */
|
| AnalysisContextImpl_TaskData _taskData;
|
|
|
| @@ -5271,28 +4910,21 @@ class AnalysisContextImpl_CycleBuilder {
|
| AnalysisContextImpl_CycleBuilder(this.AnalysisContextImpl_this) : super();
|
|
|
| /**
|
| - * Return a list containing the libraries that are ready to be resolved (assuming that
|
| - * [getTaskData] returns `null`).
|
| - *
|
| - * @return the libraries that are ready to be resolved
|
| + * Return a list containing the libraries that are ready to be resolved
|
| + * (assuming that [getTaskData] returns `null`).
|
| */
|
| List<ResolvableLibrary> get librariesInCycle => _librariesInCycle;
|
|
|
| /**
|
| - * Return a representation of an analysis task that needs to be performed before the cycle of
|
| - * libraries can be resolved, or `null` if the libraries are ready to be resolved.
|
| - *
|
| - * @return the analysis task that needs to be performed before the cycle of libraries can be
|
| - * resolved
|
| + * Return a representation of an analysis task that needs to be performed
|
| + * before the cycle of libraries can be resolved, or `null` if the libraries
|
| + * are ready to be resolved.
|
| */
|
| AnalysisContextImpl_TaskData get taskData => _taskData;
|
|
|
| /**
|
| - * Compute a list of the libraries that need to be resolved together in order to resolve the
|
| - * given library.
|
| - *
|
| - * @param librarySource the source of the library to be resolved
|
| - * @throws AnalysisException if the core library cannot be found
|
| + * Compute a list of the libraries that need to be resolved together in orde
|
| + * to resolve the given [librarySource].
|
| */
|
| void computeCycleContaining(Source librarySource) {
|
| //
|
| @@ -5359,12 +4991,12 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Recursively traverse the libraries reachable from the given library, creating instances of
|
| - * the class [Library] to represent them, and record the references in the library
|
| - * objects.
|
| + * Recursively traverse the libraries reachable from the given [library],
|
| + * creating instances of the class [Library] to represent them, and record the
|
| + * references in the library objects.
|
| *
|
| - * @param library the library to be processed to find libraries that have not yet been traversed
|
| - * @throws AnalysisException if some portion of the library graph could not be traversed
|
| + * Throws an [AnalysisException] if some portion of the library graph could
|
| + * not be traversed.
|
| */
|
| void _computeLibraryDependencies(ResolvableLibrary library) {
|
| Source librarySource = library.librarySource;
|
| @@ -5385,15 +5017,12 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Recursively traverse the libraries reachable from the given library, creating instances of
|
| - * the class [Library] to represent them, and record the references in the library
|
| - * objects.
|
| - *
|
| - * @param library the library to be processed to find libraries that have not yet been traversed
|
| - * @param importedSources an array containing the sources that are imported into the given
|
| - * library
|
| - * @param exportedSources an array containing the sources that are exported from the given
|
| - * library
|
| + * Recursively traverse the libraries reachable from the given [library],
|
| + * creating instances of the class [Library] to represent them, and record the
|
| + * references in the library objects. The [importedSources] is a list
|
| + * containing the sources that are imported into the given library. The
|
| + * [exportedSources] is a list containing the sources that are exported from
|
| + * the given library.
|
| */
|
| void _computeLibraryDependenciesFromDirectives(ResolvableLibrary library,
|
| List<Source> importedSources, List<Source> exportedSources) {
|
| @@ -5450,11 +5079,13 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Gather the resolvable AST structures for each of the compilation units in each of the
|
| - * libraries in the cycle. This is done in two phases: first we ensure that we have cached an
|
| - * AST structure for each compilation unit, then we gather them. We split the work this way
|
| - * because getting the AST structures can change the state of the cache in such a way that we
|
| - * would have more work to do if any compilation unit didn't have a resolvable AST structure.
|
| + * Gather the resolvable AST structures for each of the compilation units in
|
| + * each of the libraries in the cycle. This is done in two phases: first we
|
| + * ensure that we have cached an AST structure for each compilation unit, then
|
| + * we gather them. We split the work this way because getting the AST
|
| + * structures can change the state of the cache in such a way that we would
|
| + * have more work to do if any compilation unit didn't have a resolvable AST
|
| + * structure.
|
| */
|
| void _computePartsInCycle(Source librarySource) {
|
| int count = _librariesInCycle.length;
|
| @@ -5479,11 +5110,8 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Gather the resolvable compilation units for each of the compilation units in the specified
|
| - * library.
|
| - *
|
| - * @param libraryPair a holder containing both the library and a list of (source, entry) pairs
|
| - * for all of the compilation units in the library
|
| + * Gather the resolvable compilation units for each of the compilation units
|
| + * in the library represented by the [libraryPair].
|
| */
|
| void _computePartsInLibrary(CycleBuilder_LibraryPair libraryPair) {
|
| ResolvableLibrary library = libraryPair.library;
|
| @@ -5502,11 +5130,8 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Create an object to represent the information about the library defined by the compilation
|
| - * unit with the given source.
|
| - *
|
| - * @param librarySource the source of the library's defining compilation unit
|
| - * @return the library object that was created
|
| + * Create an object to represent the information about the library defined by
|
| + * the compilation unit with the given [librarySource].
|
| */
|
| ResolvableLibrary _createLibrary(Source librarySource) {
|
| ResolvableLibrary library = new ResolvableLibrary(librarySource);
|
| @@ -5524,11 +5149,8 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Create an object to represent the information about the library defined by the compilation
|
| - * unit with the given source.
|
| - *
|
| - * @param librarySource the source of the library's defining compilation unit
|
| - * @return the library object that was created
|
| + * Create an object to represent the information about the library defined by
|
| + * the compilation unit with the given [librarySource].
|
| */
|
| ResolvableLibrary _createLibraryOrNull(Source librarySource) {
|
| ResolvableLibrary library = new ResolvableLibrary(librarySource);
|
| @@ -5546,10 +5168,9 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Ensure that the given library has an element model built for it. If another task needs to be
|
| - * executed first in order to build the element model, that task is placed in [taskData].
|
| - *
|
| - * @param library the library which needs an element model.
|
| + * Ensure that the given [library] has an element model built for it. If
|
| + * another task needs to be executed first in order to build the element
|
| + * model, that task is placed in [taskData].
|
| */
|
| void _ensureElementModel(ResolvableLibrary library) {
|
| Source librarySource = library.librarySource;
|
| @@ -5567,11 +5188,10 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Ensure that all of the libraries that are exported by the given library (but are not
|
| - * themselves in the cycle) have element models built for them. If another task needs to be
|
| - * executed first in order to build the element model, that task is placed in [taskData].
|
| - *
|
| - * @param library the library being tested
|
| + * Ensure that all of the libraries that are exported by the given [library]
|
| + * (but are not themselves in the cycle) have element models built for them.
|
| + * If another task needs to be executed first in order to build the element
|
| + * model, that task is placed in [taskData].
|
| */
|
| void _ensureExports(
|
| ResolvableLibrary library, HashSet<Source> visitedLibraries) {
|
| @@ -5594,11 +5214,10 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Ensure that all of the libraries that are exported by the given library (but are not
|
| - * themselves in the cycle) have element models built for them. If another task needs to be
|
| - * executed first in order to build the element model, that task is placed in [taskData].
|
| - *
|
| - * @param library the library being tested
|
| + * Ensure that all of the libraries that are exported by the given [library]
|
| + * (but are not themselves in the cycle) have element models built for them.
|
| + * If another task needs to be executed first in order to build the element
|
| + * model, that task is placed in [taskData].
|
| */
|
| void _ensureImports(ResolvableLibrary library) {
|
| List<ResolvableLibrary> dependencies = library.imports;
|
| @@ -5616,8 +5235,9 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Ensure that all of the libraries that are either imported or exported by libraries in the
|
| - * cycle (but are not themselves in the cycle) have element models built for them.
|
| + * Ensure that all of the libraries that are either imported or exported by
|
| + * libraries in the cycle (but are not themselves in the cycle) have element
|
| + * models built for them.
|
| */
|
| void _ensureImportsAndExports() {
|
| HashSet<Source> visitedLibraries = new HashSet<Source>();
|
| @@ -5636,11 +5256,8 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Ensure that there is a resolvable compilation unit available for all of the compilation units
|
| - * in the given library.
|
| - *
|
| - * @param library the library for which resolvable compilation units must be available
|
| - * @return a list of (source, entry) pairs for all of the compilation units in the library
|
| + * Ensure that there is a resolvable compilation unit available for all of the
|
| + * compilation units in the given [library].
|
| */
|
| List<CycleBuilder_SourceEntryPair> _ensurePartsInLibrary(
|
| ResolvableLibrary library) {
|
| @@ -5682,10 +5299,8 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Ensure that there is a resolvable compilation unit available for the given source.
|
| - *
|
| - * @param source the source for which a resolvable compilation unit must be available
|
| - * @param dartEntry the entry associated with the source
|
| + * Ensure that there is a resolvable compilation unit available for the given
|
| + * [source].
|
| */
|
| void _ensureResolvableCompilationUnit(Source source, DartEntry dartEntry) {
|
| // The entry will be null if the source represents a non-Dart file.
|
| @@ -5711,12 +5326,7 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Return the sources described by the given descriptor.
|
| - *
|
| - * @param source the source with which the sources are associated
|
| - * @param dartEntry the entry corresponding to the source
|
| - * @param descriptor the descriptor indicating which sources are to be returned
|
| - * @return the sources described by the given descriptor
|
| + * Return the sources described by the given [descriptor].
|
| */
|
| List<Source> _getSources(Source source, DartEntry dartEntry,
|
| DataDescriptor<List<Source>> descriptor) {
|
| @@ -5738,15 +5348,16 @@ class AnalysisContextImpl_CycleBuilder {
|
| }
|
|
|
| /**
|
| - * Instances of the class `TaskData` represent information about the next task to be
|
| - * performed. Each data has an implicit associated source: the source that might need to be
|
| - * analyzed. There are essentially three states that can be represented:
|
| + * Information about the next task to be performed. Each data has an implicit
|
| + * associated source: the source that might need to be analyzed. There are
|
| + * essentially three states that can be represented:
|
| + *
|
| * * If [getTask] returns a non-`null` value, then that is the task that should
|
| - * be executed to further analyze the associated source.
|
| + * be executed to further analyze the associated source.
|
| * * Otherwise, if [isBlocked] returns `true`, then there is no work that can be
|
| - * done, but analysis for the associated source is not complete.
|
| - * * Otherwise, [getDependentSource] should return a source that needs to be analyzed
|
| - * before the analysis of the associated source can be completed.
|
| + * done, but analysis for the associated source is not complete.
|
| + * * Otherwise, [getDependentSource] should return a source that needs to be
|
| + * analyzed before the analysis of the associated source can be completed.
|
| */
|
| class AnalysisContextImpl_TaskData {
|
| /**
|
| @@ -5755,26 +5366,19 @@ class AnalysisContextImpl_TaskData {
|
| final AnalysisTask task;
|
|
|
| /**
|
| - * A flag indicating whether the associated source is blocked waiting for its contents to be
|
| - * loaded.
|
| + * A flag indicating whether the associated source is blocked waiting for its
|
| + * contents to be loaded.
|
| */
|
| final bool _blocked;
|
|
|
| /**
|
| * Initialize a newly created data holder.
|
| - *
|
| - * @param task the task that is to be performed
|
| - * @param blocked `true` if the associated source is blocked waiting for its contents to
|
| - * be loaded
|
| */
|
| AnalysisContextImpl_TaskData(this.task, this._blocked);
|
|
|
| /**
|
| - * Return `true` if the associated source is blocked waiting for its contents to be
|
| - * loaded.
|
| - *
|
| - * @return `true` if the associated source is blocked waiting for its contents to be
|
| - * loaded
|
| + * Return `true` if the associated source is blocked waiting for its contents
|
| + * to be loaded.
|
| */
|
| bool get isBlocked => _blocked;
|
|
|
| @@ -5788,8 +5392,7 @@ class AnalysisContextImpl_TaskData {
|
| }
|
|
|
| /**
|
| - * The interface `AnalysisContextStatistics` defines access to statistics about a single
|
| - * [AnalysisContext].
|
| + * Statistics and information about a single [AnalysisContext].
|
| */
|
| abstract class AnalysisContextStatistics {
|
| /**
|
| @@ -5798,7 +5401,8 @@ abstract class AnalysisContextStatistics {
|
| List<AnalysisContextStatistics_CacheRow> get cacheRows;
|
|
|
| /**
|
| - * Return the exceptions that caused some entries to have a state of [CacheState.ERROR].
|
| + * Return the exceptions that caused some entries to have a state of
|
| + * [CacheState.ERROR].
|
| */
|
| List<CaughtException> get exceptions;
|
|
|
| @@ -5808,7 +5412,7 @@ abstract class AnalysisContextStatistics {
|
| List<AnalysisContextStatistics_PartitionData> get partitionData;
|
|
|
| /**
|
| - * Return an array containing all of the sources in the cache.
|
| + * Return a list containing all of the sources in the cache.
|
| */
|
| List<Source> get sources;
|
| }
|
| @@ -5869,8 +5473,8 @@ abstract class AnalysisContextStatistics_CacheRow {
|
| */
|
| abstract class AnalysisContextStatistics_PartitionData {
|
| /**
|
| - * Return the number of entries in the partition that have an AST structure in one state or
|
| - * another.
|
| + * Return the number of entries in the partition that have an AST structure in
|
| + * one state or another.
|
| */
|
| int get astCount;
|
|
|
| @@ -5997,22 +5601,21 @@ class AnalysisContextStatisticsImpl_PartitionDataImpl
|
| }
|
|
|
| /**
|
| - * Instances of the class `AnalysisDelta` indicate changes to the types of analysis that
|
| - * should be performed.
|
| + * A representation of changes to the types of analysis that should be
|
| + * performed.
|
| */
|
| class AnalysisDelta {
|
| /**
|
| - * A mapping from source to what type of analysis should be performed on that source.
|
| + * A mapping from source to what type of analysis should be performed on that
|
| + * source.
|
| */
|
| HashMap<Source, AnalysisLevel> _analysisMap =
|
| new HashMap<Source, AnalysisLevel>();
|
|
|
| /**
|
| - * Return a collection of the sources that have been added. This is equivalent to calling
|
| - * [getAnalysisLevels] and collecting all sources that do not have an analysis level of
|
| - * [AnalysisLevel.NONE].
|
| - *
|
| - * @return a collection of the sources
|
| + * Return a collection of the sources that have been added. This is equivalent
|
| + * to calling [getAnalysisLevels] and collecting all sources that do not have
|
| + * an analysis level of [AnalysisLevel.NONE].
|
| */
|
| List<Source> get addedSources {
|
| List<Source> result = new List<Source>();
|
| @@ -6025,17 +5628,13 @@ class AnalysisDelta {
|
| }
|
|
|
| /**
|
| - * Return a mapping of sources to the level of analysis that should be performed.
|
| - *
|
| - * @return the analysis map
|
| + * Return a mapping of sources to the level of analysis that should be
|
| + * performed.
|
| */
|
| Map<Source, AnalysisLevel> get analysisLevels => _analysisMap;
|
|
|
| /**
|
| - * Record that the specified source should be analyzed at the specified level.
|
| - *
|
| - * @param source the source
|
| - * @param level the level at which the given source should be analyzed
|
| + * Record that the given [source] should be analyzed at the given [level].
|
| */
|
| void setAnalysisLevel(Source source, AnalysisLevel level) {
|
| _analysisMap[source] = level;
|
| @@ -6052,7 +5651,7 @@ class AnalysisDelta {
|
| }
|
|
|
| /**
|
| - * Appendto the given [builder] all sources with the given analysis [level],
|
| + * Appendto the given [buffer] all sources with the given analysis [level],
|
| * prefixed with a label and a separator if [needsSeparator] is `true`.
|
| */
|
| bool _appendSources(
|
| @@ -6211,53 +5810,47 @@ class AnalysisEngine {
|
| }
|
|
|
| /**
|
| - * The interface `AnalysisErrorInfo` contains the analysis errors and line information for the
|
| - * errors.
|
| + * The analysis errors and line information for the errors.
|
| */
|
| abstract class AnalysisErrorInfo {
|
| /**
|
| - * Return the errors that as a result of the analysis, or `null` if there were no errors.
|
| - *
|
| - * @return the errors as a result of the analysis
|
| + * Return the errors that as a result of the analysis, or `null` if there were
|
| + * no errors.
|
| */
|
| List<AnalysisError> get errors;
|
|
|
| /**
|
| - * Return the line information associated with the errors, or `null` if there were no
|
| - * errors.
|
| - *
|
| - * @return the line information associated with the errors
|
| + * Return the line information associated with the errors, or `null` if there
|
| + * were no errors.
|
| */
|
| LineInfo get lineInfo;
|
| }
|
|
|
| /**
|
| - * Instances of the class `AnalysisErrorInfoImpl` represent the analysis errors and line info
|
| - * associated with a source.
|
| + * The analysis errors and line info associated with a source.
|
| */
|
| class AnalysisErrorInfoImpl implements AnalysisErrorInfo {
|
| /**
|
| - * The analysis errors associated with a source, or `null` if there are no errors.
|
| + * The analysis errors associated with a source, or `null` if there are no
|
| + * errors.
|
| */
|
| final List<AnalysisError> errors;
|
|
|
| /**
|
| - * The line information associated with the errors, or `null` if there are no errors.
|
| + * The line information associated with the errors, or `null` if there are no
|
| + * errors.
|
| */
|
| final LineInfo lineInfo;
|
|
|
| /**
|
| - * Initialize an newly created error info with the errors and line information
|
| - *
|
| - * @param errors the errors as a result of analysis
|
| - * @param lineinfo the line info for the errors
|
| + * Initialize an newly created error info with the given [errors] and
|
| + * [lineInfo].
|
| */
|
| AnalysisErrorInfoImpl(this.errors, this.lineInfo);
|
| }
|
|
|
| /**
|
| - * The enumeration `AnalysisLevel` encodes the different levels at which a source can be
|
| - * analyzed.
|
| + * The levels at which a source can be analyzed.
|
| */
|
| class AnalysisLevel extends Enum<AnalysisLevel> {
|
| /**
|
| @@ -6286,82 +5879,55 @@ class AnalysisLevel extends Enum<AnalysisLevel> {
|
| }
|
|
|
| /**
|
| - * The interface `AnalysisListener` defines the behavior of objects that are listening for
|
| - * results being produced by an analysis context.
|
| + * An object that is listening for results being produced by an analysis
|
| + * context.
|
| */
|
| abstract class AnalysisListener {
|
| /**
|
| - * Reports that a task is about to be performed by the given context.
|
| - *
|
| - * @param context the context in which the task is to be performed
|
| - * @param taskDescription a human readable description of the task that is about to be performed
|
| + * Reports that a task, described by the given [taskDescription] is about to
|
| + * be performed by the given [context].
|
| */
|
| void aboutToPerformTask(AnalysisContext context, String taskDescription);
|
|
|
| /**
|
| - * Reports that the errors associated with the given source in the given context has been updated
|
| - * to the given errors.
|
| - *
|
| - * @param context the context in which the new list of errors was produced
|
| - * @param source the source containing the errors that were computed
|
| - * @param errors the errors that were computed
|
| - * @param lineInfo the line information associated with the source
|
| + * Reports that the [errors] associated with the given [source] in the given
|
| + * [context] has been updated to the given errors. The [lineInfo] is the line
|
| + * information associated with the source.
|
| */
|
| void computedErrors(AnalysisContext context, Source source,
|
| List<AnalysisError> errors, LineInfo lineInfo);
|
|
|
| /**
|
| - * Reports that the given source is no longer included in the set of sources that are being
|
| - * analyzed by the given analysis context.
|
| - *
|
| - * @param context the context in which the source is being analyzed
|
| - * @param source the source that is no longer being analyzed
|
| + * Reports that the given [source] is no longer included in the set of sources
|
| + * that are being analyzed by the given analysis [context].
|
| */
|
| void excludedSource(AnalysisContext context, Source source);
|
|
|
| /**
|
| - * Reports that the given source is now included in the set of sources that are being analyzed by
|
| - * the given analysis context.
|
| - *
|
| - * @param context the context in which the source is being analyzed
|
| - * @param source the source that is now being analyzed
|
| + * Reports that the given [source] is now included in the set of sources that
|
| + * are being analyzed by the given analysis [context].
|
| */
|
| void includedSource(AnalysisContext context, Source source);
|
|
|
| /**
|
| - * Reports that the given Dart source was parsed in the given context.
|
| - *
|
| - * @param context the context in which the source was parsed
|
| - * @param source the source that was parsed
|
| - * @param unit the result of parsing the source in the given context
|
| + * Reports that the given Dart [source] was parsed in the given [context],
|
| + * producing the given [unit].
|
| */
|
| void parsedDart(AnalysisContext context, Source source, CompilationUnit unit);
|
|
|
| /**
|
| - * Reports that the given HTML source was parsed in the given context.
|
| - *
|
| - * @param context the context in which the source was parsed
|
| - * @param source the source that was parsed
|
| - * @param unit the result of parsing the source in the given context
|
| + * Reports that the given HTML [source] was parsed in the given [context].
|
| */
|
| void parsedHtml(AnalysisContext context, Source source, ht.HtmlUnit unit);
|
|
|
| /**
|
| - * Reports that the given Dart source was resolved in the given context.
|
| - *
|
| - * @param context the context in which the source was resolved
|
| - * @param source the source that was resolved
|
| - * @param unit the result of resolving the source in the given context
|
| + * Reports that the given Dart [source] was resolved in the given [context].
|
| */
|
| void resolvedDart(
|
| AnalysisContext context, Source source, CompilationUnit unit);
|
|
|
| /**
|
| - * Reports that the given HTML source was resolved in the given context.
|
| - *
|
| - * @param context the context in which the source was resolved
|
| - * @param source the source that was resolved
|
| - * @param unit the result of resolving the source in the given context
|
| + * Reports that the given HTML [source] was resolved in the given [context].
|
| */
|
| void resolvedHtml(AnalysisContext context, Source source, ht.HtmlUnit unit);
|
| }
|
| @@ -6667,17 +6233,18 @@ class AnalysisOptionsImpl implements AnalysisOptions {
|
| }
|
|
|
| /**
|
| - * Instances of the class `AnalysisResult`
|
| + *
|
| */
|
| class AnalysisResult {
|
| /**
|
| - * The change notices associated with this result, or `null` if there were no changes and
|
| - * there is no more work to be done.
|
| + * The change notices associated with this result, or `null` if there were no
|
| + * changes and there is no more work to be done.
|
| */
|
| final List<ChangeNotice> _notices;
|
|
|
| /**
|
| - * The number of milliseconds required to determine which task was to be performed.
|
| + * The number of milliseconds required to determine which task was to be
|
| + * performed.
|
| */
|
| final int getTime;
|
|
|
| @@ -6692,35 +6259,31 @@ class AnalysisResult {
|
| final int performTime;
|
|
|
| /**
|
| - * Initialize a newly created analysis result to have the given values.
|
| - *
|
| - * @param notices the change notices associated with this result
|
| - * @param getTime the number of milliseconds required to determine which task was to be performed
|
| - * @param taskClassName the name of the class of the task that was performed
|
| - * @param performTime the number of milliseconds required to perform the task
|
| + * Initialize a newly created analysis result to have the given values. The
|
| + * [notices] is the change notices associated with this result. The [getTime]
|
| + * is the number of milliseconds required to determine which task was to be
|
| + * performed. The [taskClassName] is the name of the class of the task that
|
| + * was performed. The [performTime] is the number of milliseconds required to
|
| + * perform the task.
|
| */
|
| AnalysisResult(
|
| this._notices, this.getTime, this.taskClassName, this.performTime);
|
|
|
| /**
|
| - * Return the change notices associated with this result, or `null` if there were no changes
|
| - * and there is no more work to be done.
|
| - *
|
| - * @return the change notices associated with this result
|
| + * Return the change notices associated with this result, or `null` if there
|
| + * were no changes and there is no more work to be done.
|
| */
|
| List<ChangeNotice> get changeNotices => _notices;
|
|
|
| /**
|
| - * Return `true` if there is more to be performed after the task that was performed.
|
| - *
|
| - * @return `true` if there is more to be performed after the task that was performed
|
| + * Return `true` if there is more to be performed after the task that was
|
| + * performed.
|
| */
|
| bool get hasMoreWork => _notices != null;
|
| }
|
|
|
| /**
|
| - * The abstract class `AnalysisTask` defines the behavior of objects used to perform an
|
| - * analysis task.
|
| + * An analysis task.
|
| */
|
| abstract class AnalysisTask {
|
| /**
|
| @@ -6729,55 +6292,44 @@ abstract class AnalysisTask {
|
| final InternalAnalysisContext context;
|
|
|
| /**
|
| - * The exception that was thrown while performing this task, or `null` if the task completed
|
| - * successfully.
|
| + * The exception that was thrown while performing this task, or `null` if the
|
| + * task completed successfully.
|
| */
|
| CaughtException _thrownException;
|
|
|
| /**
|
| - * Initialize a newly created task to perform analysis within the given context.
|
| - *
|
| - * @param context the context in which the task is to be performed
|
| + * Initialize a newly created task to perform analysis within the given
|
| + * [context].
|
| */
|
| AnalysisTask(this.context);
|
|
|
| /**
|
| - * Return the exception that was thrown while performing this task, or `null` if the task
|
| - * completed successfully.
|
| - *
|
| - * @return the exception that was thrown while performing this task
|
| + * Return the exception that was thrown while performing this task, or `null`
|
| + * if the task completed successfully.
|
| */
|
| CaughtException get exception => _thrownException;
|
|
|
| /**
|
| * Return a textual description of this task.
|
| - *
|
| - * @return a textual description of this task
|
| */
|
| String get taskDescription;
|
|
|
| /**
|
| - * Use the given visitor to visit this task.
|
| - *
|
| - * @param visitor the visitor that should be used to visit this task
|
| - * @return the value returned by the visitor
|
| - * @throws AnalysisException if the visitor throws the exception
|
| + * Use the given [visitor] to visit this task. Throws an [AnalysisException]
|
| + * if the visitor throws the exception.
|
| */
|
| accept(AnalysisTaskVisitor visitor);
|
|
|
| /**
|
| - * Perform this analysis task, protected by an exception handler.
|
| - *
|
| - * @throws AnalysisException if an exception occurs while performing the task
|
| + * Perform this analysis task, protected by an exception handler. Throws an
|
| + * [AnalysisException] if an exception occurs while performing the task.
|
| */
|
| void internalPerform();
|
|
|
| /**
|
| - * Perform this analysis task and use the given visitor to visit this task after it has completed.
|
| - *
|
| - * @param visitor the visitor used to visit this task after it has completed
|
| - * @return the value returned by the visitor
|
| - * @throws AnalysisException if the visitor throws the exception
|
| + * Perform this analysis task and use the given [visitor] to visit this task
|
| + * after it has completed. Throws an [AnalysisException] if the visitor throws
|
| + * the exception.
|
| */
|
| Object perform(AnalysisTaskVisitor visitor) {
|
| try {
|
| @@ -6797,9 +6349,8 @@ abstract class AnalysisTask {
|
|
|
| /**
|
| * Perform this analysis task, ensuring that all exceptions are wrapped in an
|
| - * [AnalysisException].
|
| - *
|
| - * @throws AnalysisException if any exception occurs while performing the task
|
| + * [AnalysisException]. Throws an [AnalysisException] if any exception occurs
|
| + * while performing the task
|
| */
|
| void _safelyPerform() {
|
| try {
|
| @@ -6820,7 +6371,7 @@ abstract class AnalysisTask {
|
| }
|
|
|
| /**
|
| - * An `AnalysisTaskVisitor` visits tasks. While tasks are not structured in any
|
| + * An object used to visit tasks. While tasks are not structured in any
|
| * interesting way, this class provides the ability to dispatch to an
|
| * appropriate method.
|
| */
|
| @@ -6932,18 +6483,18 @@ class CachedResult<E> {
|
| }
|
|
|
| /**
|
| - * Instances of the class `CachePartition` implement a single partition in an LRU cache of
|
| - * information related to analysis.
|
| + * A single partition in an LRU cache of information related to analysis.
|
| */
|
| abstract class CachePartition {
|
| /**
|
| - * The context that owns this partition. Multiple contexts can reference a partition, but only one
|
| - * context can own it.
|
| + * The context that owns this partition. Multiple contexts can reference a
|
| + * partition, but only one context can own it.
|
| */
|
| final InternalAnalysisContext context;
|
|
|
| /**
|
| - * The maximum number of sources for which AST structures should be kept in the cache.
|
| + * The maximum number of sources for which AST structures should be kept in
|
| + * the cache.
|
| */
|
| int _maxCacheSize = 0;
|
|
|
| @@ -6953,27 +6504,24 @@ abstract class CachePartition {
|
| final CacheRetentionPolicy _retentionPolicy;
|
|
|
| /**
|
| - * A table mapping the sources belonging to this partition to the information known about those
|
| - * sources.
|
| + * A table mapping the sources belonging to this partition to the information
|
| + * known about those sources.
|
| */
|
| HashMap<Source, SourceEntry> _sourceMap = new HashMap<Source, SourceEntry>();
|
|
|
| /**
|
| - * A list containing the most recently accessed sources with the most recently used at the end of
|
| - * the list. When more sources are added than the maximum allowed then the least recently used
|
| - * source will be removed and will have it's cached AST structure flushed.
|
| + * A list containing the most recently accessed sources with the most recently
|
| + * used at the end of the list. When more sources are added than the maximum
|
| + * allowed then the least recently used source will be removed and will have
|
| + * it's cached AST structure flushed.
|
| */
|
| List<Source> _recentlyUsed;
|
|
|
| /**
|
| - * Initialize a newly created cache to maintain at most the given number of AST structures in the
|
| - * cache.
|
| - *
|
| - * @param context the context that owns this partition
|
| - * @param maxCacheSize the maximum number of sources for which AST structures should be kept in
|
| - * the cache
|
| - * @param retentionPolicy the policy used to determine which pieces of data to remove from the
|
| - * cache
|
| + * Initialize a newly created cache to maintain at most [maxCacheSize] AST
|
| + * structures in the cache. The cache is owned by the give [context], and the
|
| + * [retentionPolicy] will be used to determine which pieces of data to remove
|
| + * from the cache.
|
| */
|
| CachePartition(this.context, int maxCacheSize, this._retentionPolicy) {
|
| this._maxCacheSize = maxCacheSize;
|
| @@ -6981,9 +6529,8 @@ abstract class CachePartition {
|
| }
|
|
|
| /**
|
| - * Return the number of entries in this partition that have an AST associated with them.
|
| - *
|
| - * @return the number of entries in this partition that have an AST associated with them
|
| + * Return the number of entries in this partition that have an AST associated
|
| + * with them.
|
| */
|
| int get astSize {
|
| int astSize = 0;
|
| @@ -7005,21 +6552,16 @@ abstract class CachePartition {
|
| }
|
|
|
| /**
|
| - * Return a table mapping the sources known to the context to the information known about the
|
| - * source.
|
| - *
|
| - * <b>Note:</b> This method is only visible for use by [AnalysisCache] and should not be
|
| - * used for any other purpose.
|
| + * Return a table mapping the sources known to the context to the information
|
| + * known about the source.
|
| *
|
| - * @return a table mapping the sources known to the context to the information known about the
|
| - * source
|
| + * <b>Note:</b> This method is only visible for use by [AnalysisCache] and
|
| + * should not be used for any other purpose.
|
| */
|
| Map<Source, SourceEntry> get map => _sourceMap;
|
|
|
| /**
|
| - * Set the maximum size of the cache to the given size.
|
| - *
|
| - * @param size the maximum number of sources for which AST structures should be kept in the cache
|
| + * Set the maximum size of the cache to the given [size].
|
| */
|
| void set maxCacheSize(int size) {
|
| _maxCacheSize = size;
|
| @@ -7031,9 +6573,8 @@ abstract class CachePartition {
|
| }
|
|
|
| /**
|
| - * Record that the AST associated with the given source was just read from the cache.
|
| - *
|
| - * @param source the source whose AST was accessed
|
| + * Record that the AST associated with the given source was just read from the
|
| + * cache.
|
| */
|
| void accessedAst(Source source) {
|
| if (_recentlyUsed.remove(source)) {
|
| @@ -7049,34 +6590,24 @@ abstract class CachePartition {
|
| }
|
|
|
| /**
|
| - * Return `true` if the given source is contained in this partition.
|
| - *
|
| - * @param source the source being tested
|
| - * @return `true` if the source is contained in this partition
|
| + * Return `true` if the given [source] is contained in this partition.
|
| */
|
| bool contains(Source source);
|
|
|
| /**
|
| - * Return the entry associated with the given source.
|
| - *
|
| - * @param source the source whose entry is to be returned
|
| - * @return the entry associated with the given source
|
| + * Return the entry associated with the given [source].
|
| */
|
| SourceEntry get(Source source) => _sourceMap[source];
|
|
|
| /**
|
| - * Return an iterator returning all of the map entries mapping sources to cache entries.
|
| - *
|
| - * @return an iterator returning all of the map entries mapping sources to cache entries
|
| + * Return an iterator returning all of the map entries mapping sources to
|
| + * cache entries.
|
| */
|
| MapIterator<Source, SourceEntry> iterator() =>
|
| new SingleMapIterator<Source, SourceEntry>(_sourceMap);
|
|
|
| /**
|
| - * Associate the given entry with the given source.
|
| - *
|
| - * @param source the source with which the entry is to be associated
|
| - * @param entry the entry to be associated with the source
|
| + * Associate the given [entry] with the given [source].
|
| */
|
| void put(Source source, SourceEntry entry) {
|
| entry.fixExceptionState();
|
| @@ -7084,9 +6615,7 @@ abstract class CachePartition {
|
| }
|
|
|
| /**
|
| - * Remove all information related to the given source from this cache.
|
| - *
|
| - * @param source the source to be removed
|
| + * Remove all information related to the given [source] from this cache.
|
| */
|
| void remove(Source source) {
|
| _recentlyUsed.remove(source);
|
| @@ -7094,9 +6623,8 @@ abstract class CachePartition {
|
| }
|
|
|
| /**
|
| - * Record that the AST associated with the given source was just removed from the cache.
|
| - *
|
| - * @param source the source whose AST was removed
|
| + * Record that the AST associated with the given [source] was just removed
|
| + * from the cache.
|
| */
|
| void removedAst(Source source) {
|
| _recentlyUsed.remove(source);
|
| @@ -7104,15 +6632,12 @@ abstract class CachePartition {
|
|
|
| /**
|
| * Return the number of sources that are mapped to cache entries.
|
| - *
|
| - * @return the number of sources that are mapped to cache entries
|
| */
|
| int size() => _sourceMap.length;
|
|
|
| /**
|
| - * Record that the AST associated with the given source was just stored to the cache.
|
| - *
|
| - * @param source the source whose AST was stored
|
| + * Record that the AST associated with the given [source] was just stored to
|
| + * the cache.
|
| */
|
| void storedAst(Source source) {
|
| if (_recentlyUsed.contains(source)) {
|
| @@ -7127,9 +6652,8 @@ abstract class CachePartition {
|
| }
|
|
|
| /**
|
| - * Attempt to flush one AST structure from the cache.
|
| - *
|
| - * @return `true` if a structure was flushed
|
| + * Attempt to flush one AST structure from the cache. Return `true` if a
|
| + * structure was flushed.
|
| */
|
| bool _flushAstFromCache() {
|
| Source removedSource = _removeAstToFlush();
|
| @@ -7148,11 +6672,10 @@ abstract class CachePartition {
|
| }
|
|
|
| /**
|
| - * Remove and return one source from the list of recently used sources whose AST structure can be
|
| - * flushed from the cache. The source that will be returned will be the source that has been
|
| - * unreferenced for the longest period of time but that is not a priority for analysis.
|
| - *
|
| - * @return the source that was removed
|
| + * Remove and return one source from the list of recently used sources whose
|
| + * AST structure can be flushed from the cache. The source that will be
|
| + * returned will be the source that has been unreferenced for the longest
|
| + * period of time but that is not a priority for analysis.
|
| */
|
| Source _removeAstToFlush() {
|
| int sourceToRemove = -1;
|
| @@ -7178,16 +6701,12 @@ abstract class CachePartition {
|
| }
|
|
|
| /**
|
| - * Instances of the class `CacheRetentionPolicy` define the behavior of objects that determine
|
| - * how important it is for data to be retained in the analysis cache.
|
| + * An object used to determine how important it is for data to be retained in
|
| + * the analysis cache.
|
| */
|
| abstract class CacheRetentionPolicy {
|
| /**
|
| - * Return the priority of retaining the AST structure for the given source.
|
| - *
|
| - * @param source the source whose AST structure is being considered for removal
|
| - * @param sourceEntry the entry representing the source
|
| - * @return the priority of retaining the AST structure for the given source
|
| + * Return the priority of retaining the AST structure for the given [source].
|
| */
|
| RetentionPriority getAstPriority(Source source, SourceEntry sourceEntry);
|
| }
|
| @@ -7363,14 +6882,14 @@ class ChangeNoticeImpl implements ChangeNotice {
|
| }
|
|
|
| /**
|
| - * Instances of the class `ChangeSet` indicate which sources have been added, changed,
|
| - * removed, or deleted. In the case of a changed source, there are multiple ways of indicating the
|
| + * An indication of which sources have been added, changed, removed, or deleted.
|
| + * In the case of a changed source, there are multiple ways of indicating the
|
| * nature of the change.
|
| *
|
| - * No source should be added to the change set more than once, either with the same or a different
|
| - * kind of change. It does not make sense, for example, for a source to be both added and removed,
|
| - * and it is redundant for a source to be marked as changed in its entirety and changed in some
|
| - * specific range.
|
| + * No source should be added to the change set more than once, either with the
|
| + * same or a different kind of change. It does not make sense, for example, for
|
| + * a source to be both added and removed, and it is redundant for a source to be
|
| + * marked as changed in its entirety and changed in some specific range.
|
| */
|
| class ChangeSet {
|
| /**
|
| @@ -7384,14 +6903,15 @@ class ChangeSet {
|
| final List<Source> changedSources = new List<Source>();
|
|
|
| /**
|
| - * A table mapping the sources whose content has been changed to the current content of those
|
| - * sources.
|
| + * A table mapping the sources whose content has been changed to the current
|
| + * content of those sources.
|
| */
|
| HashMap<Source, String> _changedContent = new HashMap<Source, String>();
|
|
|
| /**
|
| - * A table mapping the sources whose content has been changed within a single range to the current
|
| - * content of those sources and information about the affected range.
|
| + * A table mapping the sources whose content has been changed within a single
|
| + * range to the current content of those sources and information about the
|
| + * affected range.
|
| */
|
| final HashMap<Source, ChangeSet_ContentChange> changedRanges =
|
| new HashMap<Source, ChangeSet_ContentChange>();
|
| @@ -7402,7 +6922,8 @@ class ChangeSet {
|
| final List<Source> removedSources = new List<Source>();
|
|
|
| /**
|
| - * A list containing the source containers specifying additional sources that have been removed.
|
| + * A list containing the source containers specifying additional sources that
|
| + * have been removed.
|
| */
|
| final List<SourceContainer> removedContainers = new List<SourceContainer>();
|
|
|
| @@ -7412,18 +6933,13 @@ class ChangeSet {
|
| final List<Source> deletedSources = new List<Source>();
|
|
|
| /**
|
| - * Return a table mapping the sources whose content has been changed to the current content of
|
| - * those sources.
|
| - *
|
| - * @return a table mapping the sources whose content has been changed to the current content of
|
| - * those sources
|
| + * Return a table mapping the sources whose content has been changed to the
|
| + * current content of those sources.
|
| */
|
| Map<Source, String> get changedContents => _changedContent;
|
|
|
| /**
|
| * Return `true` if this change set does not contain any changes.
|
| - *
|
| - * @return `true` if this change set does not contain any changes
|
| */
|
| bool get isEmpty => addedSources.isEmpty &&
|
| changedSources.isEmpty &&
|
| @@ -7434,34 +6950,27 @@ class ChangeSet {
|
| deletedSources.isEmpty;
|
|
|
| /**
|
| - * Record that the specified source has been added and that its content is the default contents of
|
| - * the source.
|
| - *
|
| - * @param source the source that was added
|
| + * Record that the specified [source] has been added and that its content is
|
| + * the default contents of the source.
|
| */
|
| void addedSource(Source source) {
|
| addedSources.add(source);
|
| }
|
|
|
| /**
|
| - * Record that the specified source has been changed and that its content is the given contents.
|
| - *
|
| - * @param source the source that was changed
|
| - * @param contents the new contents of the source, or `null` if the default contents of the
|
| - * source are to be used
|
| + * Record that the specified [source] has been changed and that its content is
|
| + * the given [contents].
|
| */
|
| void changedContent(Source source, String contents) {
|
| _changedContent[source] = contents;
|
| }
|
|
|
| /**
|
| - * Record that the specified source has been changed and that its content is the given contents.
|
| - *
|
| - * @param source the source that was changed
|
| - * @param contents the new contents of the source
|
| - * @param offset the offset into the current contents
|
| - * @param oldLength the number of characters in the original contents that were replaced
|
| - * @param newLength the number of characters in the replacement text
|
| + * Record that the specified [source] has been changed and that its content is
|
| + * the given [contents]. The [offset] is the offset into the current contents.
|
| + * The [oldLength] is the number of characters in the original contents that
|
| + * were replaced. The [newLength] is the number of characters in the
|
| + * replacement text.
|
| */
|
| void changedRange(Source source, String contents, int offset, int oldLength,
|
| int newLength) {
|
| @@ -7470,29 +6979,24 @@ class ChangeSet {
|
| }
|
|
|
| /**
|
| - * Record that the specified source has been changed. If the content of the source was previously
|
| - * overridden, this has no effect (the content remains overridden). To cancel (or change) the
|
| - * override, use [changedContent] instead.
|
| - *
|
| - * @param source the source that was changed
|
| + * Record that the specified [source] has been changed. If the content of the
|
| + * source was previously overridden, this has no effect (the content remains
|
| + * overridden). To cancel (or change) the override, use [changedContent]
|
| + * instead.
|
| */
|
| void changedSource(Source source) {
|
| changedSources.add(source);
|
| }
|
|
|
| /**
|
| - * Record that the specified source has been deleted.
|
| - *
|
| - * @param source the source that was deleted
|
| + * Record that the specified [source] has been deleted.
|
| */
|
| void deletedSource(Source source) {
|
| deletedSources.add(source);
|
| }
|
|
|
| /**
|
| - * Record that the specified source container has been removed.
|
| - *
|
| - * @param container the source container that was removed
|
| + * Record that the specified source [container] has been removed.
|
| */
|
| void removedContainer(SourceContainer container) {
|
| if (container != null) {
|
| @@ -7501,9 +7005,7 @@ class ChangeSet {
|
| }
|
|
|
| /**
|
| - * Record that the specified source has been removed.
|
| - *
|
| - * @param source the source that was removed
|
| + * Record that the specified [source] has been removed.
|
| */
|
| void removedSource(Source source) {
|
| if (source != null) {
|
| @@ -7545,14 +7047,9 @@ class ChangeSet {
|
| }
|
|
|
| /**
|
| - * Append the given sources to the given builder, prefixed with the given label and possibly a
|
| - * separator.
|
| - *
|
| - * @param builder the builder to which the sources are to be appended
|
| - * @param sources the sources to be appended
|
| - * @param needsSeparator `true` if a separator is needed before the label
|
| - * @param label the label used to prefix the sources
|
| - * @return `true` if future lists of sources will need a separator
|
| + * Append the given [sources] to the given [buffer], prefixed with the given
|
| + * [label] and a separator if [needsSeparator] is `true`. Return `true` if
|
| + * future lists of sources will need a separator.
|
| */
|
| bool _appendSources(StringBuffer buffer, List<Source> sources,
|
| bool needsSeparator, String label) {
|
| @@ -7573,14 +7070,9 @@ class ChangeSet {
|
| }
|
|
|
| /**
|
| - * Append the given sources to the given builder, prefixed with the given label and possibly a
|
| - * separator.
|
| - *
|
| - * @param builder the builder to which the sources are to be appended
|
| - * @param sources the sources to be appended
|
| - * @param needsSeparator `true` if a separator is needed before the label
|
| - * @param label the label used to prefix the sources
|
| - * @return `true` if future lists of sources will need a separator
|
| + * Append the given [sources] to the given [builder], prefixed with the given
|
| + * [label] and a separator if [needsSeparator] is `true`. Return `true` if
|
| + * future lists of sources will need a separator.
|
| */
|
| bool _appendSources2(StringBuffer buffer, HashMap<Source, dynamic> sources,
|
| bool needsSeparator, String label) {
|
| @@ -7602,7 +7094,7 @@ class ChangeSet {
|
| }
|
|
|
| /**
|
| - * Instances of the class `ContentChange` represent a change to the content of a source.
|
| + * A change to the content of a source.
|
| */
|
| class ChangeSet_ContentChange {
|
| /**
|
| @@ -7626,20 +7118,19 @@ class ChangeSet_ContentChange {
|
| final int newLength;
|
|
|
| /**
|
| - * Initialize a newly created change object to represent a change to the content of a source.
|
| - *
|
| - * @param contents the new contents of the source
|
| - * @param offset the offset into the current contents
|
| - * @param oldLength the number of characters in the original contents that were replaced
|
| - * @param newLength the number of characters in the replacement text
|
| + * Initialize a newly created change object to represent a change to the
|
| + * content of a source. The [contents] is the new contents of the source. The
|
| + * [offse] ist the offset into the current contents. The [oldLength] is the
|
| + * number of characters in the original contents that were replaced. The
|
| + * [newLength] is the number of characters in the replacement text.
|
| */
|
| ChangeSet_ContentChange(
|
| this.contents, this.offset, this.oldLength, this.newLength);
|
| }
|
|
|
| /**
|
| - * Instances of the class `LibraryPair` hold a library and a list of the (source, entry)
|
| - * pairs for compilation units in the library.
|
| + * A pair containing a library and a list of the (source, entry) pairs for
|
| + * compilation units in the library.
|
| */
|
| class CycleBuilder_LibraryPair {
|
| /**
|
| @@ -7648,16 +7139,13 @@ class CycleBuilder_LibraryPair {
|
| ResolvableLibrary library;
|
|
|
| /**
|
| - * The (source, entry) pairs representing the compilation units in the library.
|
| + * The (source, entry) pairs representing the compilation units in the
|
| + * library.
|
| */
|
| List<CycleBuilder_SourceEntryPair> entryPairs;
|
|
|
| /**
|
| - * Initialize a newly created pair.
|
| - *
|
| - * @param library the library containing the compilation units
|
| - * @param entryPairs the (source, entry) pairs representing the compilation units in the
|
| - * library
|
| + * Initialize a newly created pair from the given [library] and [entryPairs].
|
| */
|
| CycleBuilder_LibraryPair(ResolvableLibrary library,
|
| List<CycleBuilder_SourceEntryPair> entryPairs) {
|
| @@ -7667,9 +7155,9 @@ class CycleBuilder_LibraryPair {
|
| }
|
|
|
| /**
|
| - * Instances of the class `SourceEntryPair` hold a source and the cache entry associated
|
| - * with that source. They are used to reduce the number of times an entry must be looked up in
|
| - * the [cache].
|
| + * A pair containing a source and the cache entry associated with that source.
|
| + * They are used to reduce the number of times an entry must be looked up in the
|
| + * [cache].
|
| */
|
| class CycleBuilder_SourceEntryPair {
|
| /**
|
| @@ -7683,10 +7171,7 @@ class CycleBuilder_SourceEntryPair {
|
| DartEntry entry;
|
|
|
| /**
|
| - * Initialize a newly created pair.
|
| - *
|
| - * @param source the source associated with the entry
|
| - * @param entry the entry associated with the source
|
| + * Initialize a newly created pair from the given [source] and [entry].
|
| */
|
| CycleBuilder_SourceEntryPair(Source source, DartEntry entry) {
|
| this.source = source;
|
| @@ -7695,8 +7180,7 @@ class CycleBuilder_SourceEntryPair {
|
| }
|
|
|
| /**
|
| - * A `DartEntry` maintains the information cached by an analysis context about
|
| - * an individual Dart file.
|
| + * The information cached by an analysis context about an individual Dart file.
|
| */
|
| class DartEntry extends SourceEntry {
|
| /**
|
| @@ -7893,8 +7377,8 @@ class DartEntry extends SourceEntry {
|
|
|
| /**
|
| * Return a valid parsed compilation unit, either an unresolved AST structure
|
| - * or the result of resolving the AST structure in the context of some library,
|
| - * or `null` if there is no parsed compilation unit available.
|
| + * or the result of resolving the AST structure in the context of some
|
| + * library, or `null` if there is no parsed compilation unit available.
|
| */
|
| CompilationUnit get anyParsedCompilationUnit {
|
| if (getState(PARSED_UNIT) == CacheState.VALID) {
|
| @@ -7933,10 +7417,8 @@ class DartEntry extends SourceEntry {
|
|
|
| /**
|
| * Set the list of libraries that contain this compilation unit to contain
|
| - * only the given source. This method should only be invoked on entries that
|
| - * represent a library.
|
| - *
|
| - * @param librarySource the source of the single library that the list should contain
|
| + * only the given [librarySource]. This method should only be invoked on
|
| + * entries that represent a library.
|
| */
|
| void set containingLibrary(Source librarySource) {
|
| _containingLibraries.clear();
|
| @@ -8212,10 +7694,9 @@ class DartEntry extends SourceEntry {
|
| /**
|
| * Record that an error occurred while attempting to generate hints for the
|
| * source represented by this entry. This will set the state of all
|
| - * verification information as being in error.
|
| - *
|
| - * @param librarySource the source of the library in which hints were being generated
|
| - * @param exception the exception that shows where the error occurred
|
| + * verification information as being in error. The [librarySource] is the
|
| + * source of the library in which hints were being generated. The [exception]
|
| + * is the exception that shows where the error occurred.
|
| */
|
| void recordHintErrorInLibrary(
|
| Source librarySource, CaughtException exception) {
|
| @@ -8227,10 +7708,9 @@ class DartEntry extends SourceEntry {
|
| /**
|
| * Record that an error occurred while attempting to generate lints for the
|
| * source represented by this entry. This will set the state of all
|
| - * verification information as being in error.
|
| - *
|
| - * @param librarySource the source of the library in which lints were being generated
|
| - * @param exception the exception that shows where the error occurred
|
| + * verification information as being in error. The [librarySource] is the
|
| + * source of the library in which lints were being generated. The [exception]
|
| + * is the exception that shows where the error occurred.
|
| */
|
| void recordLintErrorInLibrary(
|
| Source librarySource, CaughtException exception) {
|
| @@ -8259,8 +7739,6 @@ class DartEntry extends SourceEntry {
|
| * represented by this entry. This will set the state of all resolution-based
|
| * information as being in error, but will not change the state of any parse
|
| * results.
|
| - *
|
| - * @param exception the exception that shows where the error occurred
|
| */
|
| void recordResolutionError(CaughtException exception) {
|
| this.exception = exception;
|
| @@ -8272,12 +7750,12 @@ class DartEntry extends SourceEntry {
|
| }
|
|
|
| /**
|
| - * Record that an error occurred while attempting to resolve the source represented by this entry.
|
| - * This will set the state of all resolution-based information as being in error, but will not
|
| - * change the state of any parse results.
|
| - *
|
| - * @param librarySource the source of the library in which resolution was being performed
|
| - * @param exception the exception that shows where the error occurred
|
| + * Record that an error occurred while attempting to resolve the source
|
| + * represented by this entry. This will set the state of all resolution-based
|
| + * information as being in error, but will not change the state of any parse
|
| + * results. The [librarySource] is the source of the library in which
|
| + * resolution was being performed. The [exception] is the exception that shows
|
| + * where the error occurred.
|
| */
|
| void recordResolutionErrorInLibrary(
|
| Source librarySource, CaughtException exception) {
|
| @@ -8292,8 +7770,8 @@ class DartEntry extends SourceEntry {
|
|
|
| /**
|
| * Record that an [exception] occurred while attempting to scan or parse the
|
| - * entry represented by this entry. This will set the state of all information,
|
| - * including any resolution-based information, as being in error.
|
| + * entry represented by this entry. This will set the state of all
|
| + * information, including any resolution-based information, as being in error.
|
| */
|
| @override
|
| void recordScanError(CaughtException exception) {
|
| @@ -8306,10 +7784,9 @@ class DartEntry extends SourceEntry {
|
| /**
|
| * Record that an [exception] occurred while attempting to generate errors and
|
| * warnings for the source represented by this entry. This will set the state
|
| - * of all verification information as being in error.
|
| - *
|
| - * @param librarySource the source of the library in which verification was being performed
|
| - * @param exception the exception that shows where the error occurred
|
| + * of all verification information as being in error. The [librarySource] is
|
| + * the source of the library in which verification was being performed. The
|
| + * [exception] is the exception that shows where the error occurred.
|
| */
|
| void recordVerificationErrorInLibrary(
|
| Source librarySource, CaughtException exception) {
|
| @@ -8321,8 +7798,6 @@ class DartEntry extends SourceEntry {
|
| /**
|
| * Remove the given [library] from the list of libraries that contain this
|
| * part. This method should only be invoked on entries that represent a part.
|
| - *
|
| - * @param librarySource the source of the library to be removed
|
| */
|
| void removeContainingLibrary(Source library) {
|
| _containingLibraries.remove(library);
|
| @@ -8357,46 +7832,36 @@ class DartEntry extends SourceEntry {
|
| }
|
|
|
| /**
|
| - * Set the state of the data represented by the given descriptor in the context of the given
|
| - * library to the given state.
|
| - *
|
| - * @param descriptor the descriptor representing the data whose state is to be set
|
| - * @param librarySource the source of the defining compilation unit of the library that is the
|
| - * context for the data
|
| - * @param cacheState the new state of the data represented by the given descriptor
|
| + * Set the state of the data represented by the given [descriptor] in the
|
| + * context of the given [library] to the given [state].
|
| */
|
| void setStateInLibrary(
|
| - DataDescriptor descriptor, Source librarySource, CacheState cacheState) {
|
| + DataDescriptor descriptor, Source library, CacheState state) {
|
| if (!_isValidLibraryDescriptor(descriptor)) {
|
| throw new ArgumentError("Invalid descriptor: $descriptor");
|
| }
|
| - ResolutionState state = _getOrCreateResolutionState(librarySource);
|
| - state.setState(descriptor, cacheState);
|
| + ResolutionState resolutionState = _getOrCreateResolutionState(library);
|
| + resolutionState.setState(descriptor, state);
|
| }
|
|
|
| /**
|
| - * Set the value of the data represented by the given descriptor in the context of the given
|
| - * library to the given value, and set the state of that data to [CacheState.VALID].
|
| - *
|
| - * @param descriptor the descriptor representing which data is to have its value set
|
| - * @param librarySource the source of the defining compilation unit of the library that is the
|
| - * context for the data
|
| - * @param value the new value of the data represented by the given descriptor and library
|
| + * Set the value of the data represented by the given [descriptor] in the
|
| + * context of the given [library] to the given [value], and set the state of
|
| + * that data to [CacheState.VALID].
|
| */
|
| void setValueInLibrary(
|
| - DataDescriptor descriptor, Source librarySource, Object value) {
|
| + DataDescriptor descriptor, Source library, Object value) {
|
| if (!_isValidLibraryDescriptor(descriptor)) {
|
| throw new ArgumentError("Invalid descriptor: $descriptor");
|
| }
|
| - ResolutionState state = _getOrCreateResolutionState(librarySource);
|
| + ResolutionState state = _getOrCreateResolutionState(library);
|
| state.setValue(descriptor, value);
|
| }
|
|
|
| /**
|
| - * Invalidate all of the resolution information associated with the compilation unit.
|
| - *
|
| - * @param invalidateUris true if the cached results of converting URIs to source files should also
|
| - * be invalidated.
|
| + * Invalidate all of the resolution information associated with the
|
| + * compilation unit. The flag [invalidateUris] should be `true` if the cached
|
| + * results of converting URIs to source files should also be invalidated.
|
| */
|
| void _discardCachedResolutionInformation(bool invalidateUris) {
|
| setState(ELEMENT, CacheState.INVALID);
|
| @@ -8412,21 +7877,19 @@ class DartEntry extends SourceEntry {
|
| }
|
|
|
| /**
|
| - * Return a resolution state for the specified library, creating one as necessary.
|
| - *
|
| - * @param librarySource the library source (not `null`)
|
| - * @return the resolution state (not `null`)
|
| + * Return a resolution state for the specified [library], creating one as
|
| + * necessary.
|
| */
|
| - ResolutionState _getOrCreateResolutionState(Source librarySource) {
|
| + ResolutionState _getOrCreateResolutionState(Source library) {
|
| ResolutionState state = _resolutionState;
|
| if (state._librarySource == null) {
|
| - state._librarySource = librarySource;
|
| + state._librarySource = library;
|
| return state;
|
| }
|
| - while (state._librarySource != librarySource) {
|
| + while (state._librarySource != library) {
|
| if (state._nextState == null) {
|
| ResolutionState newState = new ResolutionState();
|
| - newState._librarySource = librarySource;
|
| + newState._librarySource = library;
|
| state._nextState = newState;
|
| return newState;
|
| }
|
| @@ -8580,8 +8043,7 @@ class DartEntry extends SourceEntry {
|
| }
|
|
|
| /**
|
| - * Instances of the class `DataDescriptor` are immutable constants representing data that can
|
| - * be stored in the cache.
|
| + * An immutable constant representing data that can be stored in the cache.
|
| */
|
| class DataDescriptor<E> {
|
| /**
|
| @@ -8618,9 +8080,9 @@ class DataDescriptor<E> {
|
| }
|
|
|
| /**
|
| - * Instances of the class `DefaultRetentionPolicy` implement a retention policy that will keep
|
| - * AST's in the cache if there is analysis information that needs to be computed for a source, where
|
| - * the computation is dependent on having the AST.
|
| + * A retention policy that will keep AST's in the cache if there is analysis
|
| + * information that needs to be computed for a source, where the computation is
|
| + * dependent on having the AST.
|
| */
|
| class DefaultRetentionPolicy implements CacheRetentionPolicy {
|
| /**
|
| @@ -8629,11 +8091,9 @@ class DefaultRetentionPolicy implements CacheRetentionPolicy {
|
| static DefaultRetentionPolicy POLICY = new DefaultRetentionPolicy();
|
|
|
| /**
|
| - * Return `true` if there is analysis information in the given entry that needs to be
|
| - * computed, where the computation is dependent on having the AST.
|
| - *
|
| - * @param dartEntry the entry being tested
|
| - * @return `true` if there is analysis information that needs to be computed from the AST
|
| + * Return `true` if there is analysis information in the given [dartEntry]
|
| + * that needs to be computed, where the computation is dependent on having the
|
| + * AST.
|
| */
|
| bool astIsNeeded(DartEntry dartEntry) =>
|
| dartEntry.hasInvalidData(DartEntry.HINTS) ||
|
| @@ -8791,7 +8251,7 @@ class GenerateDartErrorsTask extends AnalysisTask {
|
| class GenerateDartHintsTask extends AnalysisTask {
|
| /**
|
| * The compilation units that comprise the library, with the defining compilation unit appearing
|
| - * first in the array.
|
| + * first in the list.
|
| */
|
| final List<TimestampedData<CompilationUnit>> _units;
|
|
|
| @@ -8811,7 +8271,7 @@ class GenerateDartHintsTask extends AnalysisTask {
|
| *
|
| * @param context the context in which the task is to be performed
|
| * @param units the compilation units that comprise the library, with the defining compilation
|
| - * unit appearing first in the array
|
| + * unit appearing first in the list
|
| * @param libraryElement the element model for the library being analyzed
|
| */
|
| GenerateDartHintsTask(
|
| @@ -8874,7 +8334,7 @@ class GenerateDartHintsTask extends AnalysisTask {
|
| class GenerateDartLintsTask extends AnalysisTask {
|
|
|
| ///The compilation units that comprise the library, with the defining
|
| - ///compilation unit appearing first in the array.
|
| + ///compilation unit appearing first in the list.
|
| final List<TimestampedData<CompilationUnit>> _units;
|
|
|
| /// The element model for the library being analyzed.
|
| @@ -9014,8 +8474,7 @@ class GetContentTask extends AnalysisTask {
|
| }
|
|
|
| /**
|
| - * An `HtmlEntry` maintains the information cached by an analysis context about
|
| - * an individual HTML file.
|
| + * The information cached by an analysis context about an individual HTML file.
|
| */
|
| class HtmlEntry extends SourceEntry {
|
| /**
|
| @@ -9524,8 +8983,8 @@ class IncrementalAnalysisTask extends AnalysisTask {
|
| }
|
|
|
| /**
|
| - * The interface `InternalAnalysisContext` defines additional behavior for an analysis context
|
| - * that is required by internal users of the context.
|
| + * Additional behavior for an analysis context that is required by internal
|
| + * users of the context.
|
| */
|
| abstract class InternalAnalysisContext implements AnalysisContext {
|
| /**
|
| @@ -9536,14 +8995,14 @@ abstract class InternalAnalysisContext implements AnalysisContext {
|
| set contentCache(ContentCache value);
|
|
|
| /**
|
| - * Return an array containing all of the sources that have been marked as priority sources.
|
| - * Clients must not modify the returned array.
|
| - *
|
| - * @return the sources that have been marked as priority sources
|
| + * Return a list containing all of the sources that have been marked as
|
| + * priority sources. Clients must not modify the returned list.
|
| */
|
| List<Source> get prioritySources;
|
|
|
| - /** A factory to override how [ResolverVisitor] is created. */
|
| + /**
|
| + * A factory to override how [ResolverVisitor] is created.
|
| + */
|
| ResolverVisitorFactory get resolverVisitorFactory;
|
|
|
| /**
|
| @@ -9556,49 +9015,46 @@ abstract class InternalAnalysisContext implements AnalysisContext {
|
| */
|
| void set typeProvider(TypeProvider typeProvider);
|
|
|
| - /** A factory to override how [TypeResolverVisitor] is created. */
|
| + /**
|
| + * A factory to override how [TypeResolverVisitor] is created.
|
| + */
|
| TypeResolverVisitorFactory get typeResolverVisitorFactory;
|
|
|
| /**
|
| - * Add the given source with the given information to this context.
|
| - *
|
| - * @param source the source to be added
|
| - * @param info the information about the source
|
| + * Add the given [source] with the given [information] to this context.
|
| */
|
| - void addSourceInfo(Source source, SourceEntry info);
|
| + void addSourceInfo(Source source, SourceEntry information);
|
|
|
| /**
|
| - * Return an array containing the sources of the libraries that are exported by the library with
|
| - * the given source. The array will be empty if the given source is invalid, if the given source
|
| - * does not represent a library, or if the library does not export any other libraries.
|
| + * Return a list containing the sources of the libraries that are exported by
|
| + * the library with the given [source]. The list will be empty if the given
|
| + * source is invalid, if the given source does not represent a library, or if
|
| + * the library does not export any other libraries.
|
| *
|
| - * @param source the source representing the library whose exports are to be returned
|
| - * @return the sources of the libraries that are exported by the given library
|
| - * @throws AnalysisException if the exported libraries could not be computed
|
| + * Throws an [AnalysisException] if the exported libraries could not be
|
| + * computed.
|
| */
|
| List<Source> computeExportedLibraries(Source source);
|
|
|
| /**
|
| - * Return an array containing the sources of the libraries that are imported by the library with
|
| - * the given source. The array will be empty if the given source is invalid, if the given source
|
| - * does not represent a library, or if the library does not import any other libraries.
|
| + * Return a list containing the sources of the libraries that are imported by
|
| + * the library with the given [source]. The list will be empty if the given
|
| + * source is invalid, if the given source does not represent a library, or if
|
| + * the library does not import any other libraries.
|
| *
|
| - * @param source the source representing the library whose imports are to be returned
|
| - * @return the sources of the libraries that are imported by the given library
|
| - * @throws AnalysisException if the imported libraries could not be computed
|
| + * Throws an [AnalysisException] if the imported libraries could not be
|
| + * computed.
|
| */
|
| List<Source> computeImportedLibraries(Source source);
|
|
|
| /**
|
| - * Return an AST structure corresponding to the given source, but ensure that the structure has
|
| - * not already been resolved and will not be resolved by any other threads or in any other
|
| - * library.
|
| + * Return an AST structure corresponding to the given [source], but ensure
|
| + * that the structure has not already been resolved and will not be resolved
|
| + * by any other threads or in any other library.
|
| *
|
| - * <b>Note:</b> This method cannot be used in an async environment
|
| + * Throws an [AnalysisException] if the analysis could not be performed.
|
| *
|
| - * @param source the compilation unit for which an AST structure should be returned
|
| - * @return the AST structure representing the content of the source
|
| - * @throws AnalysisException if the analysis could not be performed
|
| + * <b>Note:</b> This method cannot be used in an async environment
|
| */
|
| CompilationUnit computeResolvableCompilationUnit(Source source);
|
|
|
| @@ -9610,19 +9066,13 @@ abstract class InternalAnalysisContext implements AnalysisContext {
|
| List<CompilationUnit> ensureResolvedDartUnits(Source source);
|
|
|
| /**
|
| - * Return context that owns the given source.
|
| - *
|
| - * @param source the source whose context is to be returned
|
| - * @return the context that owns the partition that contains the source
|
| + * Return context that owns the given [source].
|
| */
|
| InternalAnalysisContext getContextFor(Source source);
|
|
|
| /**
|
| - * Return a namespace containing mappings for all of the public names defined by the given
|
| - * library.
|
| - *
|
| - * @param library the library whose public namespace is to be returned
|
| - * @return the public namespace of the given library
|
| + * Return a namespace containing mappings for all of the public names defined
|
| + * by the given [library].
|
| */
|
| Namespace getPublicNamespace(LibraryElement library);
|
|
|
| @@ -9646,11 +9096,9 @@ abstract class InternalAnalysisContext implements AnalysisContext {
|
| Source source, String originalContents, String newContents, bool notify);
|
|
|
| /**
|
| - * Given a table mapping the source for the libraries represented by the corresponding elements to
|
| - * the elements representing the libraries, record those mappings.
|
| - *
|
| - * @param elementMap a table mapping the source for the libraries represented by the elements to
|
| - * the elements representing the libraries
|
| + * Given an [elementMap] mapping the source for the libraries represented by
|
| + * the corresponding elements to the elements representing the libraries,
|
| + * record those mappings.
|
| */
|
| void recordLibraryElements(Map<Source, LibraryElement> elementMap);
|
|
|
| @@ -9662,10 +9110,10 @@ abstract class InternalAnalysisContext implements AnalysisContext {
|
| }
|
|
|
| /**
|
| - * A `Logger` is an object that can be used to receive information about errors
|
| - * within the analysis engine. Implementations usually write this information to
|
| - * a file, but can also record the information for later use (such as during
|
| - * testing) or even ignore the information.
|
| + * An object that can be used to receive information about errors within the
|
| + * analysis engine. Implementations usually write this information to a file,
|
| + * but can also record the information for later use (such as during testing) or
|
| + * even ignore the information.
|
| */
|
| abstract class Logger {
|
| /**
|
| @@ -9682,10 +9130,8 @@ abstract class Logger {
|
| void logError(String message, [CaughtException exception]);
|
|
|
| /**
|
| - * Log the given exception as one representing an error.
|
| - *
|
| - * @param message an explanation of why the error occurred or what it means
|
| - * @param exception the exception being logged
|
| + * Log the given [exception] as one representing an error. The [message] is an
|
| + * explanation of why the error occurred or what it means.
|
| */
|
| @deprecated
|
| void logError2(String message, Object exception);
|
| @@ -9698,10 +9144,8 @@ abstract class Logger {
|
| void logInformation(String message, [CaughtException exception]);
|
|
|
| /**
|
| - * Log the given exception as one representing an informational message.
|
| - *
|
| - * @param message an explanation of why the error occurred or what it means
|
| - * @param exception the exception being logged
|
| + * Log the given [exception] as one representing an informational message. The
|
| + * [message] is an explanation of why the error occurred or what it means.
|
| */
|
| @deprecated
|
| void logInformation2(String message, Object exception);
|
| @@ -9725,9 +9169,9 @@ class NullLogger implements Logger {
|
| }
|
|
|
| /**
|
| - * Instances of the class `ObsoleteSourceAnalysisException` represent an analysis attempt that
|
| - * failed because a source was deleted between the time the analysis started and the time the
|
| - * results of the analysis were ready to be recorded.
|
| + * An exception created when an analysis attempt fails because a source was
|
| + * deleted between the time the analysis started and the time the results of the
|
| + * analysis were ready to be recorded.
|
| */
|
| class ObsoleteSourceAnalysisException extends AnalysisException {
|
| /**
|
| @@ -9736,9 +9180,8 @@ class ObsoleteSourceAnalysisException extends AnalysisException {
|
| Source _source;
|
|
|
| /**
|
| - * Initialize a newly created exception to represent the removal of the given source.
|
| - *
|
| - * @param source the source that was removed while it was being analyzed
|
| + * Initialize a newly created exception to represent the removal of the given
|
| + * [source].
|
| */
|
| ObsoleteSourceAnalysisException(Source source) : super(
|
| "The source '${source.fullName}' was removed while it was being analyzed") {
|
| @@ -9747,8 +9190,6 @@ class ObsoleteSourceAnalysisException extends AnalysisException {
|
|
|
| /**
|
| * Return the source that was removed while it was being analyzed.
|
| - *
|
| - * @return the source that was removed
|
| */
|
| Source get source => _source;
|
| }
|
| @@ -9828,7 +9269,7 @@ class ParseDartTask extends AnalysisTask {
|
| CompilationUnit get compilationUnit => _unit;
|
|
|
| /**
|
| - * Return the errors that were produced by scanning and parsing the source, or an empty array if
|
| + * Return the errors that were produced by scanning and parsing the source, or an empty list if
|
| * the task has not yet been performed or if an exception occurred.
|
| *
|
| * @return the errors that were produced by scanning and parsing the source
|
| @@ -9836,10 +9277,10 @@ class ParseDartTask extends AnalysisTask {
|
| List<AnalysisError> get errors => _errors;
|
|
|
| /**
|
| - * Return an array containing the sources referenced by 'export' directives, or an empty array if
|
| + * Return a list containing the sources referenced by 'export' directives, or an empty list if
|
| * the task has not yet been performed or if an exception occurred.
|
| *
|
| - * @return an array containing the sources referenced by 'export' directives
|
| + * @return an list containing the sources referenced by 'export' directives
|
| */
|
| List<Source> get exportedSources => _toArray(_exportedSources);
|
|
|
| @@ -9860,18 +9301,18 @@ class ParseDartTask extends AnalysisTask {
|
| bool get hasPartOfDirective => _containsPartOfDirective;
|
|
|
| /**
|
| - * Return an array containing the sources referenced by 'import' directives, or an empty array if
|
| + * Return a list containing the sources referenced by 'import' directives, or an empty list if
|
| * the task has not yet been performed or if an exception occurred.
|
| *
|
| - * @return an array containing the sources referenced by 'import' directives
|
| + * @return a list containing the sources referenced by 'import' directives
|
| */
|
| List<Source> get importedSources => _toArray(_importedSources);
|
|
|
| /**
|
| - * Return an array containing the sources referenced by 'part' directives, or an empty array if
|
| + * Return a list containing the sources referenced by 'part' directives, or an empty list if
|
| * the task has not yet been performed or if an exception occurred.
|
| *
|
| - * @return an array containing the sources referenced by 'part' directives
|
| + * @return a list containing the sources referenced by 'part' directives
|
| */
|
| List<Source> get includedSources => _toArray(_includedSources);
|
|
|
| @@ -9930,10 +9371,7 @@ class ParseDartTask extends AnalysisTask {
|
| }
|
|
|
| /**
|
| - * Efficiently convert the given set of sources to an array.
|
| - *
|
| - * @param sources the set to be converted
|
| - * @return an array containing all of the sources in the given set
|
| + * Efficiently convert the given set of [sources] to a list.
|
| */
|
| List<Source> _toArray(HashSet<Source> sources) {
|
| int size = sources.length;
|
| @@ -10029,7 +9467,7 @@ class ParseHtmlTask extends AnalysisTask {
|
| List<AnalysisError> _errors = AnalysisError.NO_ERRORS;
|
|
|
| /**
|
| - * An array containing the sources of the libraries that are referenced within the HTML.
|
| + * A list containing the sources of the libraries that are referenced within the HTML.
|
| */
|
| List<Source> _referencedLibraries = Source.EMPTY_ARRAY;
|
|
|
| @@ -10081,7 +9519,7 @@ class ParseHtmlTask extends AnalysisTask {
|
| LineInfo get lineInfo => _lineInfo;
|
|
|
| /**
|
| - * Return an array containing the sources of the libraries that are referenced within the HTML.
|
| + * Return a list containing the sources of the libraries that are referenced within the HTML.
|
| *
|
| * @return the sources of the libraries that are referenced within the HTML
|
| */
|
| @@ -10169,8 +9607,8 @@ class ParseHtmlTask_getLibrarySources extends ht.RecursiveXmlVisitor<Object> {
|
| }
|
|
|
| /**
|
| - * Instances of the class `PartitionManager` manage the partitions that can be shared between
|
| - * analysis contexts.
|
| + * An object that manages the partitions that can be shared between analysis
|
| + * contexts.
|
| */
|
| class PartitionManager {
|
| /**
|
| @@ -10192,10 +9630,8 @@ class PartitionManager {
|
| }
|
|
|
| /**
|
| - * Return the partition being used for the given SDK, creating the partition
|
| + * Return the partition being used for the given [sdk], creating the partition
|
| * if necessary.
|
| - *
|
| - * [sdk] - the SDK for which a partition is being requested.
|
| */
|
| SdkCachePartition forSdk(DartSdk sdk) {
|
| // Call sdk.context now, because when it creates a new
|
| @@ -10366,21 +9802,19 @@ class PerformanceStatistics {
|
| }
|
|
|
| /**
|
| - * Instances of the class `RecordingErrorListener` implement 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 {
|
| /**
|
| - * A HashMap of lists containing the errors that were collected, keyed by each [Source].
|
| + * A map of sets containing the errors that were collected, keyed by each
|
| + * source.
|
| */
|
| Map<Source, HashSet<AnalysisError>> _errors =
|
| new HashMap<Source, HashSet<AnalysisError>>();
|
|
|
| /**
|
| - * Answer the errors collected by the listener.
|
| - *
|
| - * @return an array of errors (not `null`, contains no `null`s)
|
| + * Return the errors collected by the listener.
|
| */
|
| List<AnalysisError> get errors {
|
| int numEntries = _errors.length;
|
| @@ -10395,9 +9829,7 @@ class RecordingErrorListener implements AnalysisErrorListener {
|
| }
|
|
|
| /**
|
| - * Add all of the errors recorded by the given listener to this listener.
|
| - *
|
| - * @param listener the listener that has recorded the errors to be added
|
| + * Add all of the errors recorded by the given [listener] to this listener.
|
| */
|
| void addAll(RecordingErrorListener listener) {
|
| for (AnalysisError error in listener.errors) {
|
| @@ -10406,11 +9838,7 @@ class RecordingErrorListener implements AnalysisErrorListener {
|
| }
|
|
|
| /**
|
| - * Answer the errors collected by the listener for some passed [Source].
|
| - *
|
| - * @param source some [Source] for which the caller wants the set of [AnalysisError]s
|
| - * collected by this listener
|
| - * @return the errors collected by the listener for the passed [Source]
|
| + * Return the errors collected by the listener for the given [source].
|
| */
|
| List<AnalysisError> getErrorsForSource(Source source) {
|
| HashSet<AnalysisError> errorsForSource = _errors[source];
|
| @@ -10472,8 +9900,8 @@ class RecursiveXmlVisitor_ResolveHtmlTask_internalPerform
|
| }
|
|
|
| /**
|
| - * A `ResolutionEraser` removes any resolution information from an AST
|
| - * structure when used to visit that structure.
|
| + * An visitor that removes any resolution information from an AST structure when
|
| + * used to visit that structure.
|
| */
|
| class ResolutionEraser extends GeneralizingAstVisitor<Object> {
|
| @override
|
| @@ -10602,8 +10030,8 @@ class ResolutionEraser extends GeneralizingAstVisitor<Object> {
|
| }
|
|
|
| /**
|
| - * A `ResolutionState` maintains the information produced by resolving a
|
| - * compilation unit as part of a specific library.
|
| + * The information produced by resolving a compilation unit as part of a
|
| + * specific library.
|
| */
|
| class ResolutionState {
|
| /**
|
| @@ -10612,9 +10040,9 @@ class ResolutionState {
|
| ResolutionState _nextState;
|
|
|
| /**
|
| - * The source for the defining compilation unit of the library that contains this unit. If this
|
| - * unit is the defining compilation unit for it's library, then this will be the source for this
|
| - * unit.
|
| + * The source for the defining compilation unit of the library that contains
|
| + * this unit. If this unit is the defining compilation unit for it's library,
|
| + * then this will be the source for this unit.
|
| */
|
| Source _librarySource;
|
|
|
| @@ -10795,12 +10223,11 @@ class ResolutionState {
|
| }
|
|
|
| /**
|
| - * Write a textual representation of the difference between the old entry and this entry to the
|
| - * given string builder.
|
| - *
|
| - * @param builder the string builder to which the difference is to be written
|
| - * @param oldEntry the entry that was replaced by this entry
|
| - * @return `true` if some difference was written
|
| + * Write a textual representation of the difference between the old entry and
|
| + * this entry to the given string [buffer]. A separator will be written before
|
| + * the first difference if [needsSeparator] is `true`. The [oldEntry] is the
|
| + * entry that was replaced by this entry. Return `true` is a separator is
|
| + * needed before writing any subsequent differences.
|
| */
|
| bool _writeDiffOn(
|
| StringBuffer buffer, bool needsSeparator, DartEntry oldEntry) {
|
| @@ -10818,10 +10245,8 @@ class ResolutionState {
|
| }
|
|
|
| /**
|
| - * Write a textual representation of this state to the given builder. The result will only be
|
| - * used for debugging purposes.
|
| - *
|
| - * @param builder the builder to which the text should be written
|
| + * Write a textual representation of this state to the given [buffer]. The
|
| + * result will only be used for debugging purposes.
|
| */
|
| void _writeOn(StringBuffer buffer) {
|
| if (_librarySource != null) {
|
| @@ -10878,8 +10303,8 @@ class ResolutionState {
|
| }
|
|
|
| /**
|
| - * A `ResolvableCompilationUnit` is a compilation unit that is not referenced by
|
| - * any other objects. It is used by the [LibraryResolver] to resolve a library.
|
| + * A compilation unit that is not referenced by any other objects. It is used by
|
| + * the [LibraryResolver] to resolve a library.
|
| */
|
| class ResolvableCompilationUnit {
|
| /**
|
| @@ -10893,10 +10318,8 @@ class ResolvableCompilationUnit {
|
| final CompilationUnit compilationUnit;
|
|
|
| /**
|
| - * Initialize a newly created holder to hold the given values.
|
| - *
|
| - * @param source the source of the compilation unit
|
| - * @param unit the AST that was created from the source
|
| + * Initialize a newly created holder to hold the given [source] and
|
| + * [compilationUnit].
|
| */
|
| ResolvableCompilationUnit(this.source, this.compilationUnit);
|
| }
|
| @@ -11243,26 +10666,27 @@ class ResolveHtmlTask extends AnalysisTask {
|
| }
|
|
|
| /**
|
| - * The enumerated type `RetentionPriority` represents the priority of data in the cache in
|
| - * terms of the desirability of retaining some specified data about a specified source.
|
| + * The priority of data in the cache in terms of the desirability of retaining
|
| + * some specified data about a specified source.
|
| */
|
| class RetentionPriority extends Enum<RetentionPriority> {
|
| /**
|
| - * A priority indicating that a given piece of data can be removed from the cache without
|
| - * reservation.
|
| + * A priority indicating that a given piece of data can be removed from the
|
| + * cache without reservation.
|
| */
|
| static const RetentionPriority LOW = const RetentionPriority('LOW', 0);
|
|
|
| /**
|
| - * A priority indicating that a given piece of data should not be removed from the cache unless
|
| - * there are no sources for which the corresponding data has a lower priority. Currently used for
|
| - * data that is needed in order to finish some outstanding analysis task.
|
| + * A priority indicating that a given piece of data should not be removed from
|
| + * the cache unless there are no sources for which the corresponding data has
|
| + * a lower priority. Currently used for data that is needed in order to finish
|
| + * some outstanding analysis task.
|
| */
|
| static const RetentionPriority MEDIUM = const RetentionPriority('MEDIUM', 1);
|
|
|
| /**
|
| - * A priority indicating that a given piece of data should not be removed from the cache.
|
| - * Currently used for data related to a priority source.
|
| + * A priority indicating that a given piece of data should not be removed from
|
| + * the cache. Currently used for data related to a priority source.
|
| */
|
| static const RetentionPriority HIGH = const RetentionPriority('HIGH', 2);
|
|
|
| @@ -11365,8 +10789,7 @@ class ScanDartTask extends AnalysisTask {
|
| }
|
|
|
| /**
|
| - * Instances of the class `SdkAnalysisContext` implement an [AnalysisContext] that only
|
| - * contains sources for a Dart SDK.
|
| + * An [AnalysisContext] that only contains sources for a Dart SDK.
|
| */
|
| class SdkAnalysisContext extends AnalysisContextImpl {
|
| @override
|
| @@ -11385,16 +10808,13 @@ class SdkAnalysisContext extends AnalysisContextImpl {
|
| }
|
|
|
| /**
|
| - * Instances of the class `SdkCachePartition` implement a cache partition that contains all of
|
| - * the sources in the SDK.
|
| + * A cache partition that contains all of the sources in the SDK.
|
| */
|
| class SdkCachePartition extends CachePartition {
|
| /**
|
| - * Initialize a newly created partition.
|
| - *
|
| - * @param context the context that owns this partition
|
| - * @param maxCacheSize the maximum number of sources for which AST structures should be kept in
|
| - * the cache
|
| + * Initialize a newly created partition. The [context] is the context that
|
| + * owns this partition. The [maxCacheSize] is the maximum number of sources
|
| + * for which AST structures should be kept in the cache.
|
| */
|
| SdkCachePartition(InternalAnalysisContext context, int maxCacheSize)
|
| : super(context, maxCacheSize, DefaultRetentionPolicy.POLICY);
|
| @@ -11404,8 +10824,8 @@ class SdkCachePartition extends CachePartition {
|
| }
|
|
|
| /**
|
| - * A `SourceEntry` maintains the information cached by an analysis context about
|
| - * an individual source, no matter what kind of source it is.
|
| + * The information cached by an analysis context about an individual source, no
|
| + * matter what kind of source it is.
|
| */
|
| abstract class SourceEntry {
|
| /**
|
| @@ -11806,14 +11226,15 @@ abstract class SourceEntry {
|
| }
|
|
|
| /**
|
| - * The enumerated type `Priority` defines the priority levels used to return sources in an
|
| - * optimal order. A smaller ordinal value equates to a higher priority.
|
| + * The priority levels used to return sources in an optimal order. A smaller
|
| + * ordinal value equates to a higher priority.
|
| */
|
| class SourcePriority extends Enum<SourcePriority> {
|
| /**
|
| - * Used for a Dart source that is known to be a part contained in a library that was recently
|
| - * resolved. These parts are given a higher priority because there is a high probability that
|
| - * their AST structure is still in the cache and therefore would not need to be re-created.
|
| + * Used for a Dart source that is known to be a part contained in a library
|
| + * that was recently resolved. These parts are given a higher priority because
|
| + * there is a high probability that their AST structure is still in the cache
|
| + * and therefore would not need to be re-created.
|
| */
|
| static const SourcePriority PRIORITY_PART =
|
| const SourcePriority('PRIORITY_PART', 0);
|
| @@ -11829,7 +11250,8 @@ class SourcePriority extends Enum<SourcePriority> {
|
| static const SourcePriority UNKNOWN = const SourcePriority('UNKNOWN', 2);
|
|
|
| /**
|
| - * Used for a Dart source that is known to be a part but whose library has not yet been resolved.
|
| + * Used for a Dart source that is known to be a part but whose library has not
|
| + * yet been resolved.
|
| */
|
| static const SourcePriority NORMAL_PART =
|
| const SourcePriority('NORMAL_PART', 3);
|
| @@ -11855,10 +11277,9 @@ class SourcePriority extends Enum<SourcePriority> {
|
| * or whose contents have changed.
|
| */
|
| class SourcesChangedEvent {
|
| -
|
| /**
|
| - * The internal representation of what has changed.
|
| - * Clients should not access this field directly.
|
| + * The internal representation of what has changed. Clients should not access
|
| + * this field directly.
|
| */
|
| final ChangeSet _changeSet;
|
|
|
| @@ -11911,8 +11332,7 @@ class SourcesChangedEvent {
|
| }
|
|
|
| /**
|
| - * Instances of the class `TimestampedData` represent analysis data for which we have a
|
| - * modification time.
|
| + * Analysis data for which we have a modification time.
|
| */
|
| class TimestampedData<E> {
|
| /**
|
| @@ -11926,27 +11346,23 @@ class TimestampedData<E> {
|
| final E data;
|
|
|
| /**
|
| - * Initialize a newly created holder to hold the given values.
|
| - *
|
| - * @param modificationTime the modification time of the source from which the data was created
|
| - * @param unit the data that was created from the source
|
| + * Initialize a newly created holder to associate the given [data] with the
|
| + * given [modificationTime].
|
| */
|
| TimestampedData(this.modificationTime, this.data);
|
| }
|
|
|
| /**
|
| - * Instances of the class `UniversalCachePartition` implement a cache partition that contains
|
| - * all sources not contained in other partitions.
|
| + * A cache partition that contains all sources not contained in other
|
| + * partitions.
|
| */
|
| class UniversalCachePartition extends CachePartition {
|
| /**
|
| - * Initialize a newly created partition.
|
| - *
|
| - * @param context the context that owns this partition
|
| - * @param maxCacheSize the maximum number of sources for which AST structures should be kept in
|
| - * the cache
|
| - * @param retentionPolicy the policy used to determine which pieces of data to remove from the
|
| - * cache
|
| + * Initialize a newly created partition. The [context] is the context that
|
| + * owns this partition. The [maxCacheSize] is the maximum number of sources
|
| + * for which AST structures should be kept in the cache. The [retentionPolicy]
|
| + * is the policy used to determine which pieces of data to remove from the
|
| + * cache.
|
| */
|
| UniversalCachePartition(InternalAnalysisContext context, int maxCacheSize,
|
| CacheRetentionPolicy retentionPolicy)
|
| @@ -11992,12 +11408,12 @@ class WaitForAsyncTask extends AnalysisTask {
|
| }
|
|
|
| /**
|
| - * Instances of the class `WorkManager` manage a list of sources that need to have analysis
|
| - * work performed on them.
|
| + * An object that manages a list of sources that need to have analysis work
|
| + * performed on them.
|
| */
|
| class WorkManager {
|
| /**
|
| - * An array containing the various queues is priority order.
|
| + * A list containing the various queues is priority order.
|
| */
|
| List<List<Source>> _workQueues;
|
|
|
| @@ -12013,13 +11429,11 @@ class WorkManager {
|
| }
|
|
|
| /**
|
| - * Record that the given source needs to be analyzed. The priority level is used to control when
|
| - * the source will be analyzed with respect to other sources. If the source was previously added
|
| - * then it's priority is updated. If it was previously added with the same priority then it's
|
| - * position in the queue is unchanged.
|
| - *
|
| - * @param source the source that needs to be analyzed
|
| - * @param priority the priority level of the source
|
| + * Record that the given [source] needs to be analyzed. The [priority] level
|
| + * is used to control when the source will be analyzed with respect to other
|
| + * sources. If the source was previously added then it's priority is updated.
|
| + * If it was previously added with the same priority then it's position in the
|
| + * queue is unchanged.
|
| */
|
| void add(Source source, SourcePriority priority) {
|
| int queueCount = _workQueues.length;
|
| @@ -12037,13 +11451,11 @@ class WorkManager {
|
| }
|
|
|
| /**
|
| - * Record that the given source needs to be analyzed. The priority level is used to control when
|
| - * the source will be analyzed with respect to other sources. If the source was previously added
|
| - * then it's priority is updated. In either case, it will be analyzed before other sources of the
|
| - * same priority.
|
| - *
|
| - * @param source the source that needs to be analyzed
|
| - * @param priority the priority level of the source
|
| + * Record that the given [source] needs to be analyzed. The [priority] level
|
| + * is used to control when the source will be analyzed with respect to other
|
| + * sources. If the source was previously added then it's priority is updated.
|
| + * In either case, it will be analyzed before other sources of the same
|
| + * priority.
|
| */
|
| void addFirst(Source source, SourcePriority priority) {
|
| int queueCount = _workQueues.length;
|
| @@ -12060,22 +11472,19 @@ class WorkManager {
|
| }
|
|
|
| /**
|
| - * Return an iterator that can be used to access the sources to be analyzed in the order in which
|
| - * they should be analyzed.
|
| + * Return an iterator that can be used to access the sources to be analyzed in
|
| + * the order in which they should be analyzed.
|
| *
|
| - * <b>Note:</b> As with other iterators, no sources can be added or removed from this work manager
|
| - * while the iterator is being used. Unlike some implementations, however, the iterator will not
|
| - * detect when this requirement has been violated; it might work correctly, it might return the
|
| + * <b>Note:</b> As with other iterators, no sources can be added or removed
|
| + * from this work manager while the iterator is being used. Unlike some
|
| + * implementations, however, the iterator will not detect when this
|
| + * requirement has been violated; it might work correctly, it might return the
|
| * wrong source, or it might throw an exception.
|
| - *
|
| - * @return an iterator that can be used to access the next source to be analyzed
|
| */
|
| WorkManager_WorkIterator iterator() => new WorkManager_WorkIterator(this);
|
|
|
| /**
|
| * Record that the given source is fully analyzed.
|
| - *
|
| - * @param source the source that is fully analyzed
|
| */
|
| void remove(Source source) {
|
| int queueCount = _workQueues.length;
|
| @@ -12113,8 +11522,8 @@ class WorkManager {
|
| }
|
|
|
| /**
|
| - * Instances of the class `WorkIterator` implement an iterator that returns the sources in a
|
| - * work manager in the order in which they are to be analyzed.
|
| + * An iterator that returns the sources in a work manager in the order in which
|
| + * they are to be analyzed.
|
| */
|
| class WorkManager_WorkIterator {
|
| final WorkManager _manager;
|
| @@ -12130,7 +11539,8 @@ class WorkManager_WorkIterator {
|
| int _index = -1;
|
|
|
| /**
|
| - * Initialize a newly created iterator to be ready to return the first element in the iteration.
|
| + * Initialize a newly created iterator to be ready to return the first element
|
| + * in the iteration.
|
| */
|
| WorkManager_WorkIterator(this._manager) {
|
| _advance();
|
| @@ -12138,16 +11548,12 @@ class WorkManager_WorkIterator {
|
|
|
| /**
|
| * Return `true` if there is another [Source] available for processing.
|
| - *
|
| - * @return `true` if there is another [Source] available for processing
|
| */
|
| bool get hasNext => _queueIndex < _manager._workQueues.length;
|
|
|
| /**
|
| - * Return the next [Source] available for processing and advance so that the returned
|
| - * source will not be returned again.
|
| - *
|
| - * @return the next [Source] available for processing
|
| + * Return the next [Source] available for processing and advance so that the
|
| + * returned source will not be returned again.
|
| */
|
| Source next() {
|
| if (!hasNext) {
|
| @@ -12159,8 +11565,9 @@ class WorkManager_WorkIterator {
|
| }
|
|
|
| /**
|
| - * Increment the [index] and [queueIndex] so that they are either indicating the
|
| - * next source to be returned or are indicating that there are no more sources to be returned.
|
| + * Increment the [index] and [queueIndex] so that they are either indicating
|
| + * the next source to be returned or are indicating that there are no more
|
| + * sources to be returned.
|
| */
|
| void _advance() {
|
| _index++;
|
| @@ -12176,7 +11583,7 @@ class WorkManager_WorkIterator {
|
| }
|
|
|
| /**
|
| - * Helper class used to create futures for AnalysisContextImpl. Using a helper
|
| + * A helper class used to create futures for AnalysisContextImpl. Using a helper
|
| * class allows us to preserve the generic parameter T.
|
| */
|
| class _AnalysisFutureHelper<T> {
|
|
|
Chromium Code Reviews
Issue 1021723008:
More comment clean-up (Closed)
Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart