Implement support for Element.documentationComment in summaries.

pkg/analyzer/tool/summary/idl.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.
 
 /**
  * This file is an "idl" style description of the summary format.  It is not
  * executed directly; instead it is parsed and transformed into code that
  * implements the summary format.
  *
  * The code generation process introduces the following non-typical semantics:
@@ skipping 204 matching lines @@
    */
   String name;
 
   /**
    * Offset of the class name relative to the beginning of the file.
    */
   @informative
   int nameOffset;
 
   /**
+   * Documentation comment for the class, or `null` if there is no
+   * documentation comment.
+   */
+  @informative
+  UnlinkedDocumentationComment documentationComment;
+
+  /**
    * Type parameters of the class, if any.
    */
   List<UnlinkedTypeParam> typeParameters;
 
   /**
    * Supertype of the class, or `null` if either (a) the class doesn't
    * explicitly declare a supertype (and hence has supertype `Object`), or (b)
    * the class *is* `Object` (and hence has no supertype).
    */
   UnlinkedTypeRef supertype;
@@ skipping 45 matching lines @@
    */
   List<String> shows;
 
   /**
    * List of names which are hidden.  Empty if this is a `show` combinator.
    */
   List<String> hides;
 }
 
 /**
+ * Unlinked summary information about a documentation comment.
+ */
+class UnlinkedDocumentationComment {
+  /**
+   * Text of the documentation comment, with '\r\n' replaced by '\n'.
+   *
+   * References appearing within the doc comment in square brackets are not
+   * specially encoded.
+   */
+  String text;
+}
+
+/**
  * Unlinked summary information about an enum declaration.
  */
 class UnlinkedEnum {
   /**
    * Name of the enum type.
    */
   String name;
 
   /**
    * Offset of the enum name relative to the beginning of the file.
    */
   @informative
   int nameOffset;
 
   /**
+   * Documentation comment for the enum, or `null` if there is no documentation
+   * comment.
+   */
+  @informative
+  UnlinkedDocumentationComment documentationComment;
+
+  /**
    * Values listed in the enum declaration, in declaration order.
    */
   List<UnlinkedEnumValue> values;
 }
 
 /**
  * Unlinked summary information about a single enumerated value in an enum
  * declaration.
  */
 class UnlinkedEnumValue {
   /**
    * Name of the enumerated value.
    */
   String name;
 
   /**
    * Offset of the enum value name relative to the beginning of the file.
    */
   @informative
   int nameOffset;
+
+  /**
+   * Documentation comment for the enum value, or `null` if there is no
+   * documentation comment.
+   */
+  @informative
+  UnlinkedDocumentationComment documentationComment;
 }
 
 /**
  * Unlinked summary information about a function, method, getter, or setter
  * declaration.
  */
 class UnlinkedExecutable {
   /**
    * Name of the executable.  For setters, this includes the trailing "=".  For
    * named constructors, this excludes the class name and excludes the ".".
    * For unnamed constructors, this is the empty string.
    */
   String name;
 
   /**
    * Offset of the executable name relative to the beginning of the file.  For
    * named constructors, this excludes the class name and excludes the ".".
    * For unnamed constructors, this is the offset of the class name (i.e. the
    * offset of the second "C" in "class C { C(); }").
    */
   @informative
   int nameOffset;
 
   /**
+   * Documentation comment for the executable, or `null` if there is no
+   * documentation comment.
+   */
+  @informative
+  UnlinkedDocumentationComment documentationComment;
+
+  /**
    * Type parameters of the executable, if any.  Empty if support for generic
    * method syntax is disabled.
    */
   List<UnlinkedTypeParam> typeParameters;
 
   /**
    * Declared return type of the executable.  Absent if the return type is
    * `void` or the executable is a constructor.  Note that when strong mode is
    * enabled, the actual return type may be different due to type inference.
    */
@@ skipping 352 matching lines @@
    */
   String name;
 
   /**
    * Offset of the typedef name relative to the beginning of the file.
    */
   @informative
   int nameOffset;
 
   /**
+   * Documentation comment for the typedef, or `null` if there is no
+   * documentation comment.
+   */
+  @informative
+  UnlinkedDocumentationComment documentationComment;
+
+  /**
    * Type parameters of the typedef, if any.
    */
   List<UnlinkedTypeParam> typeParameters;
 
   /**
    * Return type of the typedef.  Absent if the return type is `void`.
    */
   UnlinkedTypeRef returnType;
 
   /**
@@ skipping 86 matching lines @@
   int libraryNameOffset;
 
   /**
    * Length of the library name as it appears in the source code (or 0 if the
    * library has no name).
    */
   @informative
   int libraryNameLength;
 
   /**
+   * Documentation comment for the library, or `null` if there is no
+   * documentation comment.
+   */
+  @informative
+  UnlinkedDocumentationComment libraryDocumentationComment;
+
+  /**
    * Unlinked public namespace of this compilation unit.
    */
   UnlinkedPublicNamespace publicNamespace;
 
   /**
    * Top level and prefixed names referred to by this compilation unit.  The
    * zeroth element of this array is always populated and always represents a
    * reference to the pseudo-type "dynamic".
    */
   List<UnlinkedReference> references;
@@ skipping 50 matching lines @@
    */
   String name;
 
   /**
    * Offset of the variable name relative to the beginning of the file.
    */
   @informative
   int nameOffset;
 
   /**
+   * Documentation comment for the variable, or `null` if there is no
+   * documentation comment.
+   */
+  @informative
+  UnlinkedDocumentationComment documentationComment;
+
+  /**
    * Declared type of the variable.  Note that when strong mode is enabled, the
    * actual type of the variable may be different due to type inference.
    */
   UnlinkedTypeRef type;
 
   /**
    * Indicates whether the variable is declared using the `static` keyword.
    *
    * Note that for top level variables, this flag is false, since they are not
    * declared using the `static` keyword (even though they are considered
    * static for semantic purposes).
    */
   bool isStatic;
 
   /**
    * Indicates whether the variable is declared using the `final` keyword.
    */
   bool isFinal;
 
   /**
    * Indicates whether the variable is declared using the `const` keyword.
    */
   bool isConst;
 
   /**
    * Indicates whether this variable lacks an explicit type declaration.
    */
   bool hasImplicitType;
 }