Clean up wording of client usage expectations

pkg/analyzer/lib/task/model.dart

 // Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 library analyzer.task.model;
 
 import 'dart:collection';
 import 'dart:developer';
 
 import 'package:analyzer/src/generated/engine.dart' hide AnalysisTask;
@@ skipping 41 matching lines @@
 
   AnalysisContextTarget(this.context);
 
   @override
   Source get source => null;
 }
 
 /**
  * An object with which an analysis result can be associated.
  *
- * Clients are allowed to subtype this class when creating new kinds of targets.
+ * Clients may implement this class when creating new kinds of targets.
  * Instances of this type are used in hashed data structures, so subtypes are
  * required to correctly implement [==] and [hashCode].
  */
 abstract class AnalysisTarget {
   /**
    * Return the source associated with this target, or `null` if this target is
    * not associated with a source.
    */
   Source get source;
 }
 
 /**
  * An object used to compute one or more analysis results associated with a
  * single target.
  *
- * Clients are expected to extend this class when creating new tasks.
+ * Clients must extend this class when creating new tasks.
  */
 abstract class AnalysisTask {
   /**
    * A table mapping the types of analysis tasks to the number of times each
    * kind of task has been performed.
    */
   static final Map<Type, int> countMap = new HashMap<Type, int>();
 
   /**
    * A table mapping the types of analysis tasks to user tags used to collect
@@ skipping 102 matching lines @@
    * map (have a key/value pair for each result that this task is expected to
    * produce).
    */
   void internalPerform();
 
   /**
    * Perform this analysis task. When this method returns, either the [outputs]
    * map should be fully populated (have a key/value pair for each result that
    * this task is expected to produce) or the [caughtException] should be set.
    *
-   * Clients should not override this method.
+   * Clients may not override this method.
    */
   void perform() {
     try {
       _safelyPerform();
     } on AnalysisException catch (exception, stackTrace) {
       caughtException = new CaughtException(exception, stackTrace);
       AnalysisEngine.instance.logger
           .logInformation("Task failed: ${description}", caughtException);
     }
   }
 
   @override
   String toString() => description;
 
   /**
    * Perform this analysis task, ensuring that all exceptions are wrapped in an
    * [AnalysisException].
    *
-   * Clients should not override this method.
+   * Clients may not override this method.
    */
   void _safelyPerform() {
     try {
       //
       // Report that this task is being performed.
       //
       String contextName = context.name;
       if (contextName == null) {
         contextName = 'unnamed';
       }
@@ skipping 35 matching lines @@
           'Unexpected exception while performing $description',
           new CaughtException(exception, stackTrace));
     }
   }
 }
 
 /**
  * A description of a [List]-based analysis result that can be computed by an
  * [AnalysisTask].
  *
- * Clients are not expected to subtype this class.
+ * Clients may not extend, implement or mix-in this class.
  */
 abstract class ListResultDescriptor<E> implements ResultDescriptor<List<E>> {
   /**
    * Initialize a newly created analysis result to have the given [name] and
    * [defaultValue]. If a [cachingPolicy] is provided, it will control how long
    * values associated with this result will remain in the cache.
    */
   factory ListResultDescriptor(String name, List<E> defaultValue,
       {ResultCachingPolicy<List<E>> cachingPolicy}) = ListResultDescriptorImpl<
       E>;
 
   @override
   ListTaskInput<E> of(AnalysisTarget target, {bool flushOnAccess: false});
 }
 
 /**
  * A description of an input to an [AnalysisTask] that can be used to compute
  * that input.
  *
- * Clients are not expected to subtype this class.
+ * Clients may not extend, implement or mix-in this class.
  */
 abstract class ListTaskInput<E> extends TaskInput<List<E>> {
   /**
    * Return a task input that can be used to compute a list whose elements are
    * the result of passing the elements of this input to the [mapper] function.
    */
   ListTaskInput /*<V>*/ toList(UnaryFunction<E, dynamic /*<V>*/ > mapper);
 
   /**
    * Return a task input that can be used to compute a list whose elements are
@@ skipping 14 matching lines @@
    * elements of this input and whose values are the [valueResult]'s associated
    * with those elements.
    */
   MapTaskInput<AnalysisTarget, dynamic /*V*/ > toMapOf(
       ResultDescriptor /*<V>*/ valueResult);
 }
 
 /**
  * A description of an input with a [Map] based values.
  *
- * Clients are not expected to subtype this class.
+ * Clients may not extend, implement or mix-in this class.
  */
 abstract class MapTaskInput<K, V> extends TaskInput<Map<K, V>> {
   /**
    * [V] must be a [List].
    * Return a task input that can be used to compute a list whose elements are
    * the result of passing keys [K] and the corresponding elements of [V] to
    * the [mapper] function.
    */
   TaskInput<List /*<E>*/ > toFlattenList(
       BinaryFunction<K, dynamic /*element of V*/, dynamic /*<E>*/ > mapper);
 }
 
 /**
  * A policy object that can compute sizes of results and provide the maximum
  * active and idle sizes that can be kept in the cache.
  *
  * All the [ResultDescriptor]s with the same [ResultCachingPolicy] instance
  * share the same total size in a cache.
+ *
+ * Clients may implement this class when implementing plugins.
  */
 abstract class ResultCachingPolicy<T> {
   /**
    * Return the maximum total size of results that can be kept in the cache
    * while analysis is in progress.
    */
   int get maxActiveSize;
 
   /**
    * Return the maximum total size of results that can be kept in the cache
    * while analysis is idle.
    */
   int get maxIdleSize;
 
   /**
    * Return the size of the given [object].
    */
   int measure(T object);
 }
 
 /**
  * A description of an analysis result that can be computed by an [AnalysisTask].
  *
- * Clients are not expected to subtype this class.
+ * Clients may not extend, implement or mix-in this class.
  */
 abstract class ResultDescriptor<V> {
   /**
    * Initialize a newly created analysis result to have the given [name] and
    * [defaultValue].
    *
    * The given [cachingPolicy] is used to limit the total size of results
    * described by this descriptor. If no policy is specified, the results are
    * never evicted from the cache, and removed only when they are invalidated.
    */
@@ skipping 19 matching lines @@
    * Return a task input that can be used to compute this result for the given
    * [target]. If [flushOnAccess] is `true` then the value of this result that
    * is associated with the [target] will be flushed when it is accessed.
    */
   TaskInput<V> of(AnalysisTarget target, {bool flushOnAccess: false});
 }
 
 /**
  * A specification of the given [result] for the given [target].
  *
- * Clients are not expected to subtype this class.
+ * Clients may not extend, implement or mix-in this class.
  */
 class TargetedResult {
   /**
    * An empty list of results.
    */
   static final List<TargetedResult> EMPTY_LIST = const <TargetedResult>[];
 
   /**
    * The target with which the result is associated.
    */
@@ skipping 20 matching lines @@
         other.target == target &&
         other.result == result;
   }
 
   @override
   String toString() => '$result for $target';
 }
 
 /**
  * A description of an [AnalysisTask].
+ *
+ * Clients may not extend, implement or mix-in this class.
  */
 abstract class TaskDescriptor {
   /**
    * Initialize a newly created task descriptor to have the given [name] and to
    * describe a task that takes the inputs built using the given [inputBuilder],
    * and produces the given [results]. The [buildTask] will be used to create
    * the instance of [AnalysisTask] thusly described.
    */
   factory TaskDescriptor(
       String name,
@@ skipping 21 matching lines @@
    * used to compute results based on the given [inputs].
    */
   AnalysisTask createTask(AnalysisContext context, AnalysisTarget target,
       Map<String, dynamic> inputs);
 }
 
 /**
  * A description of an input to an [AnalysisTask] that can be used to compute
  * that input.
  *
- * Clients are not expected to subtype this class.
+ * Clients may not extend, implement or mix-in this class.
  */
 abstract class TaskInput<V> {
   /**
    * Create and return a builder that can be used to build this task input.
    */
   TaskInputBuilder<V> createBuilder();
 
   /**
    * Return a task input that can be used to compute a list whose elements are
    * the result of passing the result of this input to the [mapper] function.
    */
   ListTaskInput /*<E>*/ mappedToList(List /*<E>*/ mapper(V value));
 }
 
 /**
  * An object used to build the value associated with a single [TaskInput].
  *
  * All builders work by requesting one or more results (each result being
  * associated with a target). The interaction pattern is modeled after the class
  * [Iterator], in which the method [moveNext] is invoked to move from one result
  * request to the next. The getters [currentResult] and [currentTarget] are used
  * to get the result and target of the current request. The value of the result
  * must be supplied using the [currentValue] setter before [moveNext] can be
  * invoked to move to the next request. When [moveNext] returns `false`,
  * indicating that there are no more requests, the method [inputValue] can be
  * used to access the value of the input that was built.
  *
- * Clients are not expected to subtype this class.
+ * Clients may not extend, implement or mix-in this class.
  */
 abstract class TaskInputBuilder<V> {
   /**
    * Return the result that needs to be computed, or `null` if [moveNext] has
    * not been invoked or if the last invocation of [moveNext] returned `false`.
    */
   ResultDescriptor get currentResult;
 
   /**
    * Return the target for which the result needs to be computed, or `null` if
@@ skipping 47 matching lines @@
    * provided using [currentValue].
    */
   bool moveNext();
 }
 
 /**
  * [WorkManager]s are used to drive analysis.
  *
  * They know specific of the targets and results they care about,
  * so they can request analysis results in optimal order.
+ *
+ * Clients may implement this class when implementing plugins.
  */
 abstract class WorkManager {
   /**
    * Notifies the manager about changes in the explicit source list.
    */
   void applyChange(List<Source> addedSources, List<Source> changedSources,
       List<Source> removedSources);
 
   /**
    * Notifies the managers that the given set of priority [targets] was set.
@@ skipping 66 matching lines @@
   /**
    * A work should be done, but without any special urgency.
    */
   NORMAL,
 
   /**
    * Nothing to do.
    */
   NONE
 }