Improve the documentation of extension points

pkg/analysis_server/lib/analysis/analysis_domain.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.
 
 /**
- * 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;
 
 import 'dart:async';
 
 import 'package:analysis_server/src/plugin/server_plugin.dart';
 import 'package:analysis_server/src/protocol.dart' show AnalysisService;
 import 'package:analyzer/src/generated/engine.dart'
     show AnalysisContext, ComputedResult;
 import 'package:analyzer/src/generated/source.dart' show Source;
 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]
    * in the given [context].
    */
   void scheduleNotification(
       AnalysisContext context, Source source, AnalysisService service);
 }