Implement support for Element.documentationComment in summaries.

pkg/analyzer/test/src/summary/summary_test.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.
 
 library analyzer.test.src.summary.summary_test;
 
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/src/generated/ast.dart';
 import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/error.dart';
@@ skipping 208 matching lines @@
       // The element model doesn't (yet) store enough information to recover
       // relative URIs, so we have to use the absolute URI.
       // TODO(paulberry): fix this.
       relativeUri = absoluteUri;
     }
     expect(dependency, new isInstanceOf<int>());
     expect(prelinked.dependencies[dependency].uri, relativeUri);
   }
 
   /**
+   * 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) {
     checkTypeRef(typeRef, null, null, null);
   }
 
   /**
    * Verify that the dependency table contains an entry for a file reachable
    * via the given [absoluteUri] and [relativeUri].
    */
@@ skipping 122 matching lines @@
    */
   void checkUnresolvedTypeRef(
       UnlinkedTypeRef typeRef, String expectedPrefix, String expectedName) {
     // When serializing from the element model, unresolved type refs lose their
     // name.
     checkTypeRef(typeRef, null, null, checkAstDerivedData ? expectedName : null,
         expectedPrefix: expectedPrefix,
         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.
     // Unresolved imports are included since this is necessary for proper
     // dependency tracking.
     serializeLibraryText('import "foo.dart";', allowErrors: true);
     // Second import is the implicit import of dart:core
     expect(unlinkedUnits[0].imports, hasLength(2));
     checkDependency(
         prelinked.importDependencies[0], absUri('/foo.dart'), 'foo.dart');
@@ skipping 336 matching lines @@
     UnlinkedClass cls =
         serializeClassText('class C = _D with _E; class _D {} class _E {}');
     expect(cls.isAbstract, false);
     expect(unlinkedUnits[0].publicNamespace.names, hasLength(1));
     expect(unlinkedUnits[0].publicNamespace.names[0].kind,
         PrelinkedReferenceKind.classOrEnum);
     expect(unlinkedUnits[0].publicNamespace.names[0].name, '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 {}');
     expect(cls.isMixinApplication, true);
   }
 
   test_class_alias_generic() {
     serializeClassText('class C<A, B> = _D with _E; class _D {} class _E {}');
     expect(unlinkedUnits[0].publicNamespace.names[0].numTypeParameters, 2);
   }
@@ skipping 52 matching lines @@
   test_class_concrete() {
     UnlinkedClass cls = serializeClassText('class C {}');
     expect(cls.isAbstract, false);
     expect(unlinkedUnits[0].publicNamespace.names, hasLength(1));
     expect(unlinkedUnits[0].publicNamespace.names[0].kind,
         PrelinkedReferenceKind.classOrEnum);
     expect(unlinkedUnits[0].publicNamespace.names[0].name, 'C');
     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 {}
 class D {}
 ''');
     expect(cls.interfaces, hasLength(1));
     checkTypeRef(cls.interfaces[0], null, null, 'D');
   }
 
   test_class_interface_order() {
@@ skipping 147 matching lines @@
   }
 
   test_constructor_const_external() {
     UnlinkedExecutable executable = findExecutable('',
         executables:
             serializeClassText('class C { external const C(); }').executables);
     expect(executable.isConst, isTrue);
     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:
             serializeClassText('class C { external C(); }').executables);
     expect(executable.isExternal, isTrue);
   }
 
   test_constructor_factory() {
     UnlinkedExecutable executable = findExecutable('',
         executables:
@@ skipping 286 matching lines @@
     expect(e.values, hasLength(1));
     expect(e.values[0].name, 'v1');
     expect(e.values[0].nameOffset, text.indexOf('v1'));
     expect(unlinkedUnits[0].publicNamespace.names, hasLength(1));
     expect(unlinkedUnits[0].publicNamespace.names[0].kind,
         PrelinkedReferenceKind.classOrEnum);
     expect(unlinkedUnits[0].publicNamespace.names[0].name, 'E');
     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));
     expect(e.values[0].name, 'v1');
     expect(e.values[1].name, 'v2');
   }
 
   test_enum_private() {
     serializeEnumText('enum _E { v1 }', '_E');
     expect(unlinkedUnits[0].publicNamespace.names, isEmpty);
@@ skipping 537 matching lines @@
     expect(findExecutable('i', executables: cls.executables), isNull);
     expect(findExecutable('i=', executables: cls.executables), isNull);
   }
 
   test_field_const() {
     UnlinkedVariable variable =
         serializeClassText('class C { static const int i = 0; }').fields[0];
     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];
     expect(variable.isFinal, isTrue);
   }
 
   test_field_static() {
     UnlinkedVariable variable =
         serializeClassText('class C { static int i; }').fields[0];
     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) {} }');
     List<UnlinkedParam> params = cls.executables[0].parameters;
     checkParamTypeRef(params[0].type, 4);
     checkParamTypeRef(params[1].type, 3);
     checkParamTypeRef(params[2].type, 2);
     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); }');
     expect(unlinkedUnits[0].imports[0].isDeferred, isTrue);
   }
 
   test_import_dependency() {
     serializeLibraryText('import "dart:async"; Future x;');
     // Second import is the implicit import of dart:core
     expect(unlinkedUnits[0].imports, hasLength(2));
@@ skipping 156 matching lines @@
 
   test_import_uri() {
     String uriString = '"dart:async"';
     String libraryText = 'import $uriString; Future x;';
     serializeLibraryText(libraryText);
     // Second import is the implicit import of dart:core
     expect(unlinkedUnits[0].imports, hasLength(2));
     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);
     expect(unlinkedUnits[0].libraryName, 'foo.bar');
     expect(unlinkedUnits[0].libraryNameOffset, text.indexOf('foo . bar'));
     expect(unlinkedUnits[0].libraryNameLength, 'foo . bar'.length);
   }
 
   test_library_named() {
     String text = 'library foo.bar;';
     serializeLibraryText(text);
     expect(unlinkedUnits[0].libraryName, 'foo.bar');
     expect(unlinkedUnits[0].libraryNameOffset, text.indexOf('foo.bar'));
     expect(unlinkedUnits[0].libraryNameLength, 'foo.bar'.length);
   }
 
   test_library_unnamed() {
     serializeLibraryText('');
     expect(unlinkedUnits[0].libraryName, isEmpty);
     expect(unlinkedUnits[0].libraryNameOffset, 0);
     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';
     serializeLibraryText(text);
     expect(unlinkedUnits[0].publicNamespace.parts, hasLength(1));
     expect(unlinkedUnits[0].publicNamespace.parts[0], 'a.dart');
     expect(unlinkedUnits[0].parts, hasLength(1));
     expect(unlinkedUnits[0].parts[0].uriOffset, text.indexOf('"a.dart"'));
     expect(unlinkedUnits[0].parts[0].uriEnd, text.indexOf('; // <-part'));
   }
@@ skipping 15 matching lines @@
   }
 
   test_public_namespace_of_part() {
     addNamedSource('/a.dart', 'part of foo; class C {}');
     serializeLibraryText('library foo; part "a.dart";');
     expect(unlinkedUnits[0].publicNamespace.names, isEmpty);
     expect(unlinkedUnits[1].publicNamespace.names, hasLength(1));
     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',
         allowTypeParameters: true, numTypeParameters: 1);
     expect(typeRef.typeArguments, hasLength(1));
     checkTypeRef(typeRef.typeArguments[0], 'dart:core', 'dart:core', 'int');
   }
 
   test_type_arguments_explicit_dynamic() {
     UnlinkedTypeRef typeRef = serializeTypeText('List<dynamic>');
@@ skipping 181 matching lines @@
     // from them.
     checkTypeRef(typeRef, absUri('/a.dart'), 'a.dart', 'C',
         expectedTargetUnit: 2);
   }
 
   test_type_unresolved() {
     UnlinkedTypeRef typeRef = serializeTypeText('Foo', allowErrors: true);
     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);
     expect(type.name, 'F');
     expect(type.nameOffset, text.indexOf('F'));
     expect(unlinkedUnits[0].publicNamespace.names, hasLength(1));
     expect(unlinkedUnits[0].publicNamespace.names[0].kind,
         PrelinkedReferenceKind.typedef);
     expect(unlinkedUnits[0].publicNamespace.names[0].name, 'F');
     expect(unlinkedUnits[0].publicNamespace.names[0].numTypeParameters, 0);
@@ skipping 75 matching lines @@
     expect(unlinkedUnits[0].publicNamespace.names[1].name, 'i=');
     expect(unlinkedUnits[0].publicNamespace.names[1].numTypeParameters, 0);
   }
 
   test_variable_const() {
     UnlinkedVariable variable =
         serializeVariableText('const int i = 0;', variableName: 'i');
     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);
     expect(variable.hasImplicitType, isFalse);
   }
 
   test_variable_final_top_level() {
     UnlinkedVariable variable =
         serializeVariableText('final int i = 0;', variableName: 'i');
     expect(variable.isFinal, isTrue);
@@ skipping 54 matching lines @@
     UnlinkedVariable variable =
         serializeVariableText('int i;', variableName: 'i');
     checkTypeRef(variable.type, 'dart:core', 'dart:core', 'int');
   }
 
   test_varible_private() {
     serializeVariableText('int _i;', variableName: '_i');
     expect(unlinkedUnits[0].publicNamespace.names, isEmpty);
   }
 }