Add file missed in previous CL and comment clean-up

pkg/analysis_server/lib/completion/completion_core.dart

Index: pkg/analysis_server/lib/completion/completion_core.dart
diff --git a/pkg/analysis_server/lib/completion/completion_core.dart b/pkg/analysis_server/lib/completion/completion_core.dart
index 749a1c7a9c871844297a688bf370e51ba0afb245..d1aca7ae2a0b8d7316fabc5675ec4395681884cd 100644
--- a/pkg/analysis_server/lib/completion/completion_core.dart
+++ b/pkg/analysis_server/lib/completion/completion_core.dart
@@ -4,10 +4,17 @@
 
 library analysis_server.completion.completion_core;
 
-import 'package:analyzer/src/generated/engine.dart';
 import 'package:analysis_server/src/protocol.dart';
+import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/source.dart';
 
+/**
+ * An object used to produce completions for a specific error. Completion
+ * contributors are long-lived objects and must not retain any state between
+ * invocations of [computeSuggestions].
+ *
+ * Clients are expected to subtype this class when implementing plugins.
+ */
 abstract class CompletionContributor {
   /**
    * Compute a list of completion suggestions based on the given completion
@@ -20,6 +27,8 @@ abstract class CompletionContributor {
 
 /**
  * The information about a requested list of completions.
+ *
+ * Clients are not expected to subtype this class.
  */
 abstract class CompletionRequest {
   /**
@@ -28,6 +37,11 @@ abstract class CompletionRequest {
   AnalysisContext get context;
 
   /**
+   * The offset within the source at which the completion is being requested.
+   */
+  int get offset;
+
+  /**
    * Return the results that were returned the last time the contributor was
    * asked for results, or `null` if this is the first request for results at
    * this location.
@@ -38,13 +52,13 @@ abstract class CompletionRequest {
    * Return the source in which the completion is being requested.
    */
   Source get source;
-
-  /**
-   * The offset within the source at which the completion is being requested.
-   */
-  int get offset;
 }
 
+/**
+ * The result of computing suggestions for code completion.
+ *
+ * Clients are expected to subtype this class when implementing plugins.
+ */
 abstract class CompletionResult {
   /**
    * Return `true` if this result contains suggestions that were not in the
@@ -61,6 +75,15 @@ abstract class CompletionResult {
   bool get isLast;
 
   /**
+   * Return the length of the text to be replaced. This will be zero (0) if the
+   * suggestion is to be inserted, otherwise it will be greater than zero. For
+   * example, if the remainder of the identifier containing the cursor is to be
+   * replaced when the suggestion is applied, in which case the length will be
+   * the number of characters in the existing identifier.
+   */
+  int get replacementLength;
+
+  /**
    * Return the offset of the start of the text to be replaced. This will be
    * different than the offset used to request the completion suggestions if
    * there was a portion of text that needs to be replaced. For example, if a
@@ -71,15 +94,6 @@ abstract class CompletionResult {
   int get replacementOffset;
 
   /**
-   * Return the length of the text to be replaced. This will be zero (0) if the
-   * suggestion is to be inserted, otherwise it will be greater than zero. For
-   * example, if the remainder of the identifier containing the cursor is to be
-   * replaced when the suggestion is applied, in which case the length will be
-   * the number of characters in the existing identifier.
-   */
-  int get replacementLength;
-
-  /**
    * Return the list of suggestions being contributed by the contributor.
    */
   List<CompletionSuggestion> get suggestions;