Implement support for Element.documentationComment in summaries.

pkg/analyzer/test/src/summary/resynthesize_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 test.src.serialization.elements_test;
 
 import 'package:analyzer/src/generated/element.dart';
 import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/source.dart';
 import 'package:analyzer/src/summary/base.dart';
@@ skipping 180 matching lines @@
     // TODO(paulberry): test redirectedConstructor and constantInitializers
   }
 
   void compareElements(
       ElementImpl resynthesized, ElementImpl original, String desc) {
     expect(resynthesized, isNotNull);
     expect(resynthesized.kind, original.kind);
     expect(resynthesized.location, original.location, reason: desc);
     expect(resynthesized.name, original.name);
     expect(resynthesized.nameOffset, original.nameOffset, reason: desc);
+    expect(resynthesized.documentationComment, original.documentationComment,
+        reason: desc);

[scheglov, 2016/01/08 22:04:45]

Do we want to support the (deprecated) `docRange` property?

[Paul Berry, 2016/01/08 22:37:47]

Good question.  I don't know if it's really needed, but it was simple enough to
do: https://codereview.chromium.org/1564343004/

     for (Modifier modifier in Modifier.values) {
       if (modifier == Modifier.MIXIN) {
         // Skipping for now.  TODO(paulberry): fix.
         continue;
       }
       bool got = resynthesized.hasModifier(modifier);
       bool want = original.hasModifier(modifier);
       expect(got, want,
           reason: 'Mismatch in $desc.$modifier: got $got, want $want');
     }
@@ skipping 313 matching lines @@
     // Check that no other summaries needed to be resynthesized to resynthesize
     // the library element.
     expect(resynthesizer.resynthesisCount, 1);
     return resynthesized;
   }
 
   test_class_alias() {
     checkLibrary('class C = D with E, F; class D {} class E {} class F {}');
   }
 
+  test_class_alias_documented() {
+    checkLibrary('''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+class C = D with E;
+
+class D {}
+class E {}''');
+  }
+
   test_class_alias_with_forwarding_constructors() {
     addLibrarySource(
         '/a.dart',
         '''
 class Base {
   Base._priv();
   Base();
   Base.noArgs();
   Base.requiredArg(x);
   Base.positionalArg([x]);
@@ skipping 114 matching lines @@
   }
 
   test_class_constructor_params() {
     checkLibrary('class C { C(x, y); }');
   }
 
   test_class_constructors() {
     checkLibrary('class C { C.foo(); C.bar(); }');
   }
 
+  test_class_documented() {
+    checkLibrary('''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+class C {}''');
+  }
+
+  test_class_documented_with_references() {
+    checkLibrary('''
+/**
+ * Docs referring to [D] and [E]
+ */
+class C {}
+
+class D {}
+class E {}''');
+  }
+
+  test_class_documented_with_windows_line_endings() {
+    checkLibrary('/**\r\n * Docs\r\n */\r\nclass C {}');
+  }
+
   test_class_field_const() {
     checkLibrary('class C { static const int i = 0; }');
   }
 
   test_class_field_implicit_type() {
     checkLibrary('class C { var x; }');
   }
 
   test_class_field_static() {
     checkLibrary('class C { static int i; }');
@@ skipping 88 matching lines @@
   }
 
   test_class_type_parameters_f_bound_simple() {
     checkLibrary('class C<T extends U, U> {}');
   }
 
   test_classes() {
     checkLibrary('class C {} class D {}');
   }
 
+  test_constructor_documented() {
+    checkLibrary('''
+class C {
+  /**
+   * Docs
+   */
+  C();
+}''');
+  }
+
   test_core() {
     String uri = 'dart:core';
     LibraryElementImpl original =
         resolve2(analysisContext2.sourceFactory.forUri(uri));
     LibraryElementImpl resynthesized =
         resynthesizeLibraryElement(uri, original);
     checkLibraryElements(original, resynthesized);
   }
 
+  test_enum_documented() {
+    checkLibrary('''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+enum E { v }''');
+  }
+
+  test_enum_value_documented() {
+    checkLibrary('''
+enum E {
+  /**
+   * Docs
+   */
+  v
+}''');
+  }
+
   test_enum_values() {
     checkLibrary('enum E { v1, v2 }');
   }
 
   test_enums() {
     checkLibrary('enum E1 { v1 } enum E2 { v2 }');
   }
 
   test_export_hide() {
     addLibrary('dart:async');
     checkLibrary('export "dart:async" hide Stream, Future;');
   }
 
   test_export_multiple_combinators() {
     addLibrary('dart:async');
     checkLibrary('export "dart:async" hide Stream show Future;');
   }
 
   test_export_show() {
     addLibrary('dart:async');
     checkLibrary('export "dart:async" show Future, Stream;');
   }
 
   test_exports() {
     addLibrarySource('/a.dart', 'library a;');
     addLibrarySource('/b.dart', 'library b;');
     checkLibrary('export "a.dart"; export "b.dart";');
   }
 
+  test_field_documented() {
+    checkLibrary('''
+class C {
+  /**
+   * Docs
+   */
+  var x;
+}''');
+  }
+
+  test_function_documented() {
+    checkLibrary('''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+f() {}''');
+  }
+
   test_function_entry_point() {
     checkLibrary('main() {}');
   }
 
   test_function_entry_point_in_export_hidden() {
     addLibrarySource('/a.dart', 'library a; main() {}');
     checkLibrary('export "a.dart" hide main;');
   }
 
   test_function_entry_point_in_part() {
@@ skipping 58 matching lines @@
 
   test_function_type_parameter_with_function_typed_parameter() {
     resetWithOptions(new AnalysisOptionsImpl()..enableGenericMethods = true);
     checkLibrary('void f<T, U>(T x(U u)) {}');
   }
 
   test_functions() {
     checkLibrary('f() {} g() {}');
   }
 
+  test_getter_documented() {
+    checkLibrary('''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+get x => null;''');
+  }
+
   test_getter_external() {
     checkLibrary('external int get x;');
   }
 
   test_getters() {
     checkLibrary('int get x => null; get y => null;');
   }
 
   test_import_hide() {
     addLibrary('dart:async');
@@ skipping 18 matching lines @@
   test_imports() {
     addLibrarySource('/a.dart', 'library a; class C {}');
     addLibrarySource('/b.dart', 'library b; class D {}');
     checkLibrary('import "a.dart"; import "b.dart"; C c; D d;');
   }
 
   test_library() {
     checkLibrary('');
   }
 
+  test_library_documented() {
+    checkLibrary('''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+library foo;''');
+  }
+
   test_library_name_with_spaces() {
     checkLibrary('library foo . bar ;');
   }
 
   test_library_named() {
     checkLibrary('library foo.bar;');
   }
 
+  test_method_documented() {
+    checkLibrary('''
+class C {
+  /**
+   * Docs
+   */
+  f() {}
+}''');
+  }
+
   test_method_parameter_parameters() {
     checkLibrary('class C { f(g(x, y)) {} }');
   }
 
   test_method_parameter_parameters_in_generic_class() {
     checkLibrary('class C<A, B> { f(A g(B x)) {} }');
   }
 
   test_method_parameter_return_type() {
     checkLibrary('class C { f(int g()) {} }');
@@ skipping 45 matching lines @@
   test_operator_less_equal() {
     checkLibrary('class C { bool operator<=(C other) => false; }');
   }
 
   test_parts() {
     addNamedSource('/a.dart', 'part of my.lib;');
     addNamedSource('/b.dart', 'part of my.lib;');
     checkLibrary('library my.lib; part "a.dart"; part "b.dart";');
   }
 
+  test_setter_documented() {
+    checkLibrary('''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+void set x(value) {}''');
+  }
+
   test_setter_external() {
     checkLibrary('external void set x(int value);');
   }
 
   test_setters() {
     checkLibrary('void set x(int value) {} set y(value) {}');
   }
 
   test_type_arguments_explicit() {
     checkLibrary('Map<String, int> m;');
@@ skipping 122 matching lines @@
   }
 
   test_type_unresolved() {
     checkLibrary('C c;', allowErrors: true);
   }
 
   test_type_unresolved_prefixed() {
     checkLibrary('import "dart:core" as core; core.C c;', allowErrors: true);
   }
 
+  test_typedef_documented() {
+    checkLibrary('''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+typedef F();''');
+  }
+
   test_typedef_parameter_parameters() {
     checkLibrary('typedef F(g(x, y));');
   }
 
   test_typedef_parameter_parameters_in_generic_class() {
     checkLibrary('typedef F<A, B>(A g(B x));');
   }
 
   test_typedef_parameter_return_type() {
     checkLibrary('typedef F(int g());');
@@ skipping 44 matching lines @@
   }
 
   test_typedefs() {
     checkLibrary('f() {} g() {}');
   }
 
   test_variable_const() {
     checkLibrary('const int i = 0;');
   }
 
+  test_variable_documented() {
+    checkLibrary('''
+// Extra comment so doc comment offset != 0
+/**
+ * Docs
+ */
+var x;''');
+  }
+
   test_variable_implicit_type() {
     checkLibrary('var x;');
   }
 
   test_variables() {
     checkLibrary('int i; int j;');
   }
 }