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

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

 // Copyright (c) 2014, 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.
 
 library analyzer.dart.element.element;
 
 import 'package:analyzer/dart/element/type.dart';
 import 'package:analyzer/src/generated/ast.dart';
 import 'package:analyzer/src/generated/constant.dart' show DartObject;
 import 'package:analyzer/src/generated/engine.dart' show AnalysisContext;
@@ skipping 520 matching lines @@
  * represent the semantic structure of the program.
  *
  * Clients may not extend, implement or mix-in this class.
  */
 abstract class Element implements AnalysisTarget {
   /**
    * A comparator that can be used to sort elements by their name offset.
    * 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.
    */
   AnalysisContext get context;
 
   /**
    * Return the display name of this element, or `null` if this element does not
    * have a name.
    *
    * In most cases the name and the display name are the same. Differences
    * though are cases such as setters where the name of some setter `set f(x)`
    * is `f=`, instead of `f`.
    */
   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;
 
   /**
    * Return the element that either physically or logically encloses this
    * element. This will be `null` if this element is a library because libraries
    * are the top-level elements in the model.
    */
   Element get enclosingElement;
 
   /**
@@ skipping 96 matching lines @@
 
   /**
    * Return the documentation comment for this element as it appears in the
    * original source (complete with the beginning and ending delimiters), or
    * `null` if this element does not have a documentation comment associated
    * with it. This can be a long-running operation if the information needed to
    * access the comment is not cached.
    *
    * Throws [AnalysisException] if the documentation comment could not be
    * determined because the analysis could not be performed
+   *
+   * Deprecated.  Use [documentationComment] instead.
    */
+  @deprecated
   String computeDocumentationComment();
 
   /**
    * Return the resolved [AstNode] node that declares this element, or `null` if
    * this element is synthetic or isn't contained in a compilation unit, such as
    * a [LibraryElement].
    *
    * This method is expensive, because resolved AST might be evicted from cache,
    * so parsing and resolving will be performed.
    *
@@ skipping 1338 matching lines @@
    */
   bool get isStatic;
 
   /**
    * Return the declared type of this variable, or `null` if the variable did
    * not have a declared type (such as if it was declared using the keyword
    * 'var').
    */
   DartType get type;
 }