Improve the documentation of extension points

R=scheglov@google.com

Review URL: https://codereview.chromium.org//1335113004 .

pkg/analysis_server/lib/analysis/analysis_domain.dart

@@ -3,7 +3,27 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /**
- * Support for client code that extends the analysis aspect of analysis server.
+ * Support for client code that interacts with the analysis domain of an
+ * analysis server.
+ *
+ * Plugins can gain access to the request handler that implements the analysis
+ * domain in order to extend the functionality of that domain. The class
+ * [AnalysisDomain] defines the API of the analysis domain that plugins can use.
+ *
+ * If a plugin is interested in gaining access to the analysis domain, it should
+ * register a function by including code like the following in the plugin's
+ * registerExtensions method:
+ *
+ *     AnalysisDomain analysisDomain;
+ *
+ *     @override
+ *     void registerExtensions(RegisterExtension registerExtension) {
+ *       ...
+ *       registerExtension(
+ *           SET_ANALYSIS_DOMAIN_EXTENSION_POINT_ID,
+ *           (AnalysisDomain domain) => analysisDomain = domain);
+ *       ...
+ *     }
  */
 library analysis_server.analysis;
 
@@ -18,31 +38,37 @@ import 'package:analyzer/task/model.dart' show ResultDescriptor;
 import 'package:plugin/plugin.dart';
 
 /**
- * The identifier of the extension point that allows plugins to get access to
- * `AnalysisSite`. The object used as an extension must be
- * a [SetAnalysisDomain].
+ * The identifier of the extension point that allows plugins to get access to an
+ * [AnalysisDomain]. The object used as an extension must be a
+ * [SetAnalysisDomain].
  */
 final String SET_ANALYSIS_DOMAIN_EXTENSION_POINT_ID = Plugin.join(
     ServerPlugin.UNIQUE_IDENTIFIER,
     ServerPlugin.SET_ANALISYS_DOMAIN_EXTENSION_POINT);
 
 /**
- * A function that is invoked on the `analysis` domain creation.
+ * A function that is invoked after the analysis domain has been created and is
+ * initialized.
  */
-typedef void SetAnalysisDomain(AnalysisDomain site);
+typedef void SetAnalysisDomain(AnalysisDomain domain);
 
 /**
- * An object that gives [SetAnalysisDomain]s access to the `analysis` domain
- * of the analysis server.
+ * An object that gives plugins access to the analysis domain of the analysis
+ * server.
  *
  * Clients are not expected to subtype this class.
  */
 abstract class AnalysisDomain {
   /**
    * Return the stream that is notified when a new value for the given
-   * [descriptor] is computed.
+   * [result] is computed.
+   *
+   * This method should be used by plugins that need to perform some additional
+   * processing after analysis has completed. One example would be a plugin that
+   * needed to send a notification to the client because some data was now
+   * invalidated.
    */
-  Stream<ComputedResult> onResultComputed(ResultDescriptor descriptor);
+  Stream<ComputedResult> onResultComputed(ResultDescriptor result);
 
   /**
    * Schedule sending the given [service] notifications for the given [source]

pkg/analysis_server/lib/analysis/navigation_core.dart

@@ -16,9 +16,9 @@ import 'package:analyzer/src/generated/source.dart' show Source;
  */
 abstract class NavigationContributor {
   /**
-   * Contribute navigation regions for a part of the given [source] into the
-   * given [collector]. The part is specified by the [offset] and [length].
-   * The [context] can be used to get analysis results.
+   * Contribute navigation regions for a subset of the content of the given
+   * [source] into the given [collector]. The subset is specified by the
+   * [offset] and [length]. The [context] can be used to access analysis results.
    */
   void computeNavigation(NavigationCollector collector, AnalysisContext context,
       Source source, int offset, int length);
@@ -33,7 +33,7 @@ abstract class NavigationContributor {
 abstract class NavigationCollector {
   /**
    * Record a new navigation region with the given [offset] and [length] that
-   * should navigation to the given [targetLocation].
+   * should navigate to the given [targetLocation].
    */
   void addRegion(
       int offset, int length, ElementKind targetKind, Location targetLocation);

pkg/analysis_server/lib/edit/assist/assist_dart.dart

@@ -13,7 +13,7 @@ import 'package:analyzer/src/generated/source.dart';
  * An [AssistContributor] that can be used to contribute assists for Dart
  * files.
  *
- * Clients are expected to subtype this class when implementing plugins.
+ * Clients are expected to extend this class when implementing plugins.
  */
 abstract class DartAssistContributor extends AssistContributor {
   @override

pkg/analysis_server/lib/edit/fix/fix_dart.dart

@@ -15,7 +15,7 @@ import 'package:analyzer/src/generated/source.dart';
  * A [FixContributor] that can be used to contribute fixes for errors in Dart
  * files.
  *
- * Clients are expected to subtype this class when implementing plugins.
+ * Clients are expected to extend this class when implementing plugins.
  */
 abstract class DartFixContributor extends FixContributor {
   @override

pkg/analysis_server/lib/plugin/analyzed_files.dart

@@ -11,6 +11,20 @@
  * The analysis server will invoke the contributed functions and analyze the
  * file if at least one of the functions returns `true`. (The server is not
  * required to invoke every function with every file.)
+ *
+ * If a plugin is interested in analyzing a certain kind of files, it needs to
+ * ensure that files of that kind will be analyzed. It should register a
+ * function by including code like the following in the plugin's
+ * registerExtensions method:
+ *
+ *     @override
+ *     void registerExtensions(RegisterExtension registerExtension) {
+ *       ...
+ *       registerExtension(
+ *           ANALYZE_FILE_EXTENSION_POINT_ID,
+ *           (File file) => file.path.endsWith(...));
+ *       ...
+ *     }
  */
 library analysis_server.plugin.analyzed_files;
 

pkg/analysis_server/lib/plugin/assist.dart

@@ -5,6 +5,22 @@
 /**
  * Support for client code that extends the analysis server by adding new assist
  * contributors.
+ *
+ * Plugins can register assist contributors. The registered contributors will be
+ * used to get assists any time a client issues an 'edit.getAssists' request.
+ *
+ * If a plugin wants to add assists, it should implement the class
+ * [AssistContributor] and then register the contributor by including code like
+ * the following in the plugin's registerExtensions method:
+ *
+ *     @override
+ *     void registerExtensions(RegisterExtension registerExtension) {
+ *       ...
+ *       registerExtension(
+ *           ASSIST_CONTRIBUTOR_EXTENSION_POINT_ID,
+ *           new MyAssistContributor());
+ *       ...
+ *     }
  */
 library analysis_server.plugin.assist;
 

pkg/analysis_server/lib/plugin/completion.dart

@@ -5,6 +5,23 @@
 /**
  * Support for client code that extends the analysis server by adding new code
  * completion contributors.
+ *
+ * Plugins can register completion contributors. The registered contributors
+ * will be used to get completions any time a client issues a
+ * 'completion.getSuggestions' request.
+ *
+ * If a plugin wants to add completions, it should implement the class
+ * [CompletionContributor] and then register the contributor by including code
+ * like the following in the plugin's registerExtensions method:
+ *
+ *     @override
+ *     void registerExtensions(RegisterExtension registerExtension) {
+ *       ...
+ *       registerExtension(
+ *           COMPLETION_CONTRIBUTOR_EXTENSION_POINT_ID,
+ *           new MyCompletionContributor());
+ *       ...
+ *     }
  */
 library analysis_server.plugin.completion;
 

pkg/analysis_server/lib/plugin/fix.dart

@@ -5,6 +5,22 @@
 /**
  * Support for client code that extends the analysis server by adding new fix
  * contributors.
+ *
+ * Plugins can register fix contributors. The registered contributors will be
+ * used to get fixes any time a client issues an 'edit.getFixes' request.
+ *
+ * If a plugin wants to add fixes, it should implement the class
+ * [FixContributor] and then register the contributor by including code like the
+ * following in the plugin's registerExtensions method:
+ *
+ *     @override
+ *     void registerExtensions(RegisterExtension registerExtension) {
+ *       ...
+ *       registerExtension(
+ *           FIX_CONTRIBUTOR_EXTENSION_POINT_ID,
+ *           new MyFixContributor());
+ *       ...
+ *     }
  */
 library analysis_server.plugin.fix;
 

pkg/analysis_server/lib/plugin/index.dart

@@ -5,6 +5,28 @@
 /**
  * Support for client code that extends the analysis server by adding new index
  * contributors.
+ *
+ * Plugins can register index contributors. The registered contributors will be
+ * used to contribute relationships to the index when the analysis of a file has
+ * been completed.
+ *
+ * Typical relationships include things like "this variable is referenced here"
+ * or "this method is invoked here". The index is used to improve the
+ * performance of operations such as search or building a type hierarchy by
+ * pre-computing some of the information needed by those operations.
+ *
+ * If a plugin wants to contribute information to the index, it should implement
+ * the class [IndexContributor] and then register the contributor by including
+ * code like the following in the plugin's registerExtensions method:
+ *
+ *     @override
+ *     void registerExtensions(RegisterExtension registerExtension) {
+ *       ...
+ *       registerExtension(
+ *           INDEX_CONTRIBUTOR_EXTENSION_POINT_ID,
+ *           new MyIndexContributor());
+ *       ...
+ *     }
  */
 library analysis_server.plugin.index;
 

pkg/analysis_server/lib/plugin/navigation.dart

@@ -5,6 +5,24 @@
 /**
  * Support for client code that extends the analysis server by adding new
  * navigation contributors.
+ *
+ * Plugins can register navigation contributors. The registered contributors
+ * will be used to get navigation regions any time a client issues an
+ * 'analysis.getNavigation' request or the server is about to send an
+ * 'analysis.navigation' notification.
+ *
+ * If a plugin wants to add navigation regions, it should implement the class
+ * [NavigationContributor] and then register the contributor by including code
+ * like the following in the plugin's registerExtensions method:
+ *
+ *     @override
+ *     void registerExtensions(RegisterExtension registerExtension) {
+ *       ...
+ *       registerExtension(
+ *           NAVIGATION_CONTRIBUTOR_EXTENSION_POINT_ID,
+ *           new MyNavigationContributor());
+ *       ...
+ *     }
  */
 library analysis_server.plugin.navigation;
 

pkg/analysis_server/lib/starter.dart

@@ -12,6 +12,8 @@ import 'package:plugin/plugin.dart';
 
 /**
  * An object that can be used to start an analysis server.
+ *
+ * Clients are not expected to subtype this class.
  */
 abstract class ServerStarter {
   /**