step toward new completion API

pkg/analysis_server/lib/src/provisional/completion/completion_core.dart

Index: pkg/analysis_server/lib/src/provisional/completion/completion_core.dart
diff --git a/pkg/analysis_server/lib/src/provisional/completion/completion_core.dart b/pkg/analysis_server/lib/src/provisional/completion/completion_core.dart
index af69cd0152ff5099cad55a6e2687f33a0d50d914..99ef35b456ca940631f806f6c376426875755d75 100644
--- a/pkg/analysis_server/lib/src/provisional/completion/completion_core.dart
+++ b/pkg/analysis_server/lib/src/provisional/completion/completion_core.dart
@@ -4,6 +4,8 @@
 
 library analysis_server.src.provisional.completion.completion_core;
 
+import 'dart:async';
+
 import 'package:analysis_server/plugin/protocol/protocol.dart';
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:analyzer/src/generated/engine.dart' show AnalysisContext;
@@ -41,14 +43,15 @@ class AnalysisRequest<V> {
 /**
  * An object used to produce completions at a specific location within a file.
  *
- * Clients may extend this class when implementing plugins.
+ * Clients may implement this class when implementing plugins.
  */
 abstract class CompletionContributor {
   /**
-   * Compute a list of completion suggestions based on the given completion
-   * [request]. Return the suggestions that were computed.
+   * Compute [suggestions] for the given completion [request].

[scheglov, 2015/11/22 05:19:01]

Why do you use [suggestions] here?
I cannot find its declaration.

[Brian Wilkerson, 2015/11/22 18:02:46]

Interesting documentation question. Thinking out loud...

If it didn't return a future, I would write:

    Return a list of suggestions appropriate to the given completion [request].

Is the presence of the type Future in the return type sufficient to tell the
reader what's actually happening, or do we need to be explicit in every such
method, such as:

    Return a future that will complete with a list of suggestions appropriate to
the given completion [request].

Seems like a lot of boiler plate to me. Unless there's good reason for it, I'd
like to abbreviate in the docs.

[danrubel, 2015/11/23 17:47:31]

Updated dartdoc.

+   * Return a [Future] that completes with a list of suggestions.
    */
-  List<CompletionSuggestion> computeSuggestions(CompletionRequest request);
+  Future<List<CompletionSuggestion>> computeSuggestions(
+      CompletionRequest request);
 }
 
 /**