Cache element docs (and add to completions) (#23694).

pkg/analyzer/lib/dart/element/element.dart

Index: pkg/analyzer/lib/dart/element/element.dart
diff --git a/pkg/analyzer/lib/dart/element/element.dart b/pkg/analyzer/lib/dart/element/element.dart
index 7d74842687f108e57f674b96781e9d951811b1b5..4df5e845f62dc3b158b8b6b1af2e1e79898dcfec 100644
--- a/pkg/analyzer/lib/dart/element/element.dart
+++ b/pkg/analyzer/lib/dart/element/element.dart
@@ -538,9 +538,9 @@ abstract class Element implements AnalysisTarget {
    * Elements with a smaller offset will be sorted to be before elements with a
    * larger name offset.
    */
-  static final Comparator<Element> SORT_BY_OFFSET = (Element firstElement,
-          Element secondElement) =>
-      firstElement.nameOffset - secondElement.nameOffset;
+  static final Comparator<Element> SORT_BY_OFFSET =
+      (Element firstElement, Element secondElement) =>
+          firstElement.nameOffset - secondElement.nameOffset;
 
   /**
    * Return the analysis context in which this element is defined.
@@ -558,9 +558,18 @@ abstract class Element implements AnalysisTarget {
   String get displayName;
 
   /**
+   * Return the source content of the documentation comment for this element,
+   * or `null` if this element does not or cannot have a documentation.

[Brian Wilkerson, 2015/12/17 22:51:17]

I know you copied the comment, but...

Not clear what "source content" means. Perhaps just "content" and then add
something that clarifies that the content includes the delimiters.

"a documentation" --> "documentation"

[pquitslund, 2015/12/18 04:56:50]

Done.

+   */
+  String get documentationComment;
+
+  /**
    * Return the source range of the documentation comment for this element,
    * or `null` if this element does not or cannot have a documentation.
+   *
+   * Deprecated.  Use [documentationComment] instead.

[Brian Wilkerson, 2015/12/17 22:51:17]

Not exactly a replacement...

[pquitslund, 2015/12/18 04:56:50]

Acknowledged.

    */
+  @deprecated
   SourceRange get docRange;
 
   /**
@@ -677,7 +686,10 @@ abstract class Element implements AnalysisTarget {
    *
    * Throws [AnalysisException] if the documentation comment could not be
    * determined because the analysis could not be performed
+   *
+   * Deprecated.  Use [documentationComment] instead.
    */
+  @deprecated
   String computeDocumentationComment();
 
   /**