Implement support for Element.documentationComment in summaries.

pkg/analyzer/test/src/summary/summary_test.dart

Index: pkg/analyzer/test/src/summary/summary_test.dart
diff --git a/pkg/analyzer/test/src/summary/summary_test.dart b/pkg/analyzer/test/src/summary/summary_test.dart
index 3eac6312e297d69988eea63bd8f0647d321e12a5..7d9bb94bbd19a533697a4ace5ffa61f3a40190da 100644
--- a/pkg/analyzer/test/src/summary/summary_test.dart
+++ b/pkg/analyzer/test/src/summary/summary_test.dart
@@ -226,6 +226,26 @@ abstract class SummaryTest {
   }
 
   /**
+   * Check that the given [documentationComment] matches the first
+   * Javadoc-style comment found in [text].
+   *
+   * Note that the algorithm for finding the Javadoc-style comment in [text] is
+   * a simple-minded text search; it is easily confused by corner cases such as
+   * strings containing comments, nested comments, etc.
+   */
+  void checkDocumentationComment(
+      UnlinkedDocumentationComment documentationComment, String text) {
+    expect(documentationComment, isNotNull);
+    int commentStart = text.indexOf('/*');
+    expect(commentStart, isNot(-1));
+    int commentEnd = text.indexOf('*/');
+    expect(commentEnd, isNot(-1));
+    commentEnd += 2;
+    String expectedCommentText = text.substring(commentStart, commentEnd);
+    expect(documentationComment.text, expectedCommentText);
+  }
+
+  /**
    * Verify that the given [typeRef] represents the type `dynamic`.
    */
   void checkDynamicTypeRef(UnlinkedTypeRef typeRef) {
@@ -368,6 +388,20 @@ abstract class SummaryTest {
         expectedKind: PrelinkedReferenceKind.unresolved);
   }
 
+  fail_enum_value_documented() {
+    // TODO(paulberry): currently broken because of dartbug.com/25385
+    String text = '''
+enum E {
+  /**
+   * Docs
+   */
+  v
+}''';
+    UnlinkedEnumValue value = serializeEnumText(text).values[0];
+    expect(value.documentationComment, isNotNull);
+    checkDocumentationComment(value.documentationComment, text);
+  }
+
   fail_test_import_missing() {
     // TODO(paulberry): At the moment unresolved imports are not included in
     // the element model, so we can't pass this test.
@@ -724,6 +758,21 @@ C c;
     expect(unlinkedUnits[0].publicNamespace.names[0].numTypeParameters, 0);
   }
 
+  test_class_alias_documented() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+class C = D with E;
+
+class D {}
+class E {}''';
+    UnlinkedClass cls = serializeClassText(text);
+    expect(cls.documentationComment, isNotNull);
+    checkDocumentationComment(cls.documentationComment, text);
+  }
+
   test_class_alias_flag() {
     UnlinkedClass cls =
         serializeClassText('class C = D with E; class D {} class E {}');
@@ -796,6 +845,41 @@ class E {}
     expect(unlinkedUnits[0].publicNamespace.names[0].numTypeParameters, 0);
   }
 
+  test_class_documented() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+class C {}''';
+    UnlinkedClass cls = serializeClassText(text);
+    expect(cls.documentationComment, isNotNull);
+    checkDocumentationComment(cls.documentationComment, text);
+  }
+
+  test_class_documented_with_references() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs referring to [D] and [E]
+ */
+class C {}
+
+class D {}
+class E {}''';
+    UnlinkedClass cls = serializeClassText(text);
+    expect(cls.documentationComment, isNotNull);
+    checkDocumentationComment(cls.documentationComment, text);
+  }
+
+  test_class_documented_with_with_windows_line_endings() {
+    String text = '/**\r\n * Docs\r\n */\r\nclass C {}';
+    String convertedText = text.replaceAll('\r\n', '\n');
+    UnlinkedClass cls = serializeClassText(text);
+    expect(cls.documentationComment, isNotNull);
+    checkDocumentationComment(cls.documentationComment, convertedText);
+  }
+
   test_class_interface() {
     UnlinkedClass cls = serializeClassText('''
 class C implements D {}
@@ -963,6 +1047,19 @@ class E {}
     expect(executable.isExternal, isTrue);
   }
 
+  test_constructor_documented() {
+    String text = '''
+class C {
+  /**
+   * Docs
+   */
+  C();
+}''';
+    UnlinkedExecutable executable = serializeClassText(text).executables[0];
+    expect(executable.documentationComment, isNotNull);
+    checkDocumentationComment(executable.documentationComment, text);
+  }
+
   test_constructor_external() {
     UnlinkedExecutable executable = findExecutable('',
         executables:
@@ -1269,6 +1366,18 @@ typedef F();
     expect(unlinkedUnits[0].publicNamespace.names[0].numTypeParameters, 0);
   }
 
+  test_enum_documented() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+enum E { v }''';
+    UnlinkedEnum enm = serializeEnumText(text);
+    expect(enm.documentationComment, isNotNull);
+    checkDocumentationComment(enm.documentationComment, text);
+  }
+
   test_enum_order() {
     UnlinkedEnum e = serializeEnumText('enum E { v1, v2 }');
     expect(e.values, hasLength(2));
@@ -1826,6 +1935,19 @@ typedef F();
     expect(variable.isConst, isTrue);
   }
 
+  test_field_documented() {
+    String text = '''
+class C {
+  /**
+   * Docs
+   */
+  var v;
+}''';
+    UnlinkedVariable variable = serializeClassText(text).fields[0];
+    expect(variable.documentationComment, isNotNull);
+    checkDocumentationComment(variable.documentationComment, text);
+  }
+
   test_field_final() {
     UnlinkedVariable variable =
         serializeClassText('class C { final int i = 0; }').fields[0];
@@ -1838,6 +1960,18 @@ typedef F();
     expect(variable.isStatic, isTrue);
   }
 
+  test_function_documented() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+f() {}''';
+    UnlinkedExecutable executable = serializeExecutableText(text);
+    expect(executable.documentationComment, isNotNull);
+    checkDocumentationComment(executable.documentationComment, text);
+  }
+
   test_generic_method_in_generic_class() {
     UnlinkedClass cls = serializeClassText(
         'class C<T, U> { void m<V, W>(T t, U u, V v, W w) {} }');
@@ -1848,6 +1982,18 @@ typedef F();
     checkParamTypeRef(params[3].type, 1);
   }
 
+  test_getter_documented() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+get f => null;''';
+    UnlinkedExecutable executable = serializeExecutableText(text);
+    expect(executable.documentationComment, isNotNull);
+    checkDocumentationComment(executable.documentationComment, text);
+  }
+
   test_import_deferred() {
     serializeLibraryText(
         'import "dart:async" deferred as a; main() { print(a.Future); }');
@@ -2024,6 +2170,19 @@ a.Stream s;
     expect(unlinkedUnits[0].imports[0].uri, 'dart:async');
   }
 
+  test_library_documented() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+library foo;''';
+    serializeLibraryText(text);
+    expect(unlinkedUnits[0].libraryDocumentationComment, isNotNull);
+    checkDocumentationComment(
+        unlinkedUnits[0].libraryDocumentationComment, text);
+  }
+
   test_library_name_with_spaces() {
     String text = 'library foo . bar ;';
     serializeLibraryText(text);
@@ -2047,6 +2206,19 @@ a.Stream s;
     expect(unlinkedUnits[0].libraryNameLength, 0);
   }
 
+  test_method_documented() {
+    String text = '''
+class C {
+  /**
+   * Docs
+   */
+  f() {}
+}''';
+    UnlinkedExecutable executable = serializeClassText(text).executables[0];
+    expect(executable.documentationComment, isNotNull);
+    checkDocumentationComment(executable.documentationComment, text);
+  }
+
   test_part_declaration() {
     addNamedSource('/a.dart', 'part of my.lib;');
     String text = 'library my.lib; part "a.dart"; // <-part';
@@ -2082,6 +2254,18 @@ a.Stream s;
     expect(unlinkedUnits[1].publicNamespace.names[0].name, 'C');
   }
 
+  test_setter_documented() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+void set f(value) {}''';
+    UnlinkedExecutable executable = serializeExecutableText(text, 'f=');
+    expect(executable.documentationComment, isNotNull);
+    checkDocumentationComment(executable.documentationComment, text);
+  }
+
   test_type_arguments_explicit() {
     UnlinkedTypeRef typeRef = serializeTypeText('List<int>');
     checkTypeRef(typeRef, 'dart:core', 'dart:core', 'List',
@@ -2283,6 +2467,18 @@ a.Stream s;
     checkUnresolvedTypeRef(typeRef, null, 'Foo');
   }
 
+  test_typedef_documented() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+typedef F();''';
+    UnlinkedTypedef typedef = serializeTypedefText(text);
+    expect(typedef.documentationComment, isNotNull);
+    checkDocumentationComment(typedef.documentationComment, text);
+  }
+
   test_typedef_name() {
     String text = 'typedef F();';
     UnlinkedTypedef type = serializeTypedefText(text);
@@ -2378,6 +2574,18 @@ a.Stream s;
     expect(variable.isConst, isTrue);
   }
 
+  test_variable_documented() {
+    String text = '''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+var v;''';
+    UnlinkedVariable variable = serializeVariableText(text);
+    expect(variable.documentationComment, isNotNull);
+    checkDocumentationComment(variable.documentationComment, text);
+  }
+
   test_variable_explicit_dynamic() {
     UnlinkedVariable variable = serializeVariableText('dynamic v;');
     checkDynamicTypeRef(variable.type);