Cloak pragma and fix tests for 2.1.0-dev (#1738)

* Cloak pragma and fix tests for 2.1.0-dev

* fix tests and rework annotations

* dartfmt

Author: jcollins-g

lib/src/model.dart

@@ -2729,16 +2729,42 @@ abstract class ModelElement extends Canonicalization
 
   /// Returns linked annotations from a given metadata set, with escaping.
   List<String> annotationsFromMetadata(List<ElementAnnotation> md) {
-    if (md == null) return <String>[];
-    return md.map((ElementAnnotation a) {
+    List<String> annotationStrings = [];
+    if (md == null) return annotationStrings;
+    for (ElementAnnotation a in md) {
       String annotation = (const HtmlEscape()).convert(a.toSource());
-      // a.element can be null if the element can't be resolved.
-      var me = packageGraph
-          .findCanonicalModelElementFor(a.element?.enclosingElement);
-      if (me != null)
-        annotation = annotation.replaceFirst(me.name, me.linkedName);
-      return annotation;
-    }).toList(growable: false);
+      Element annotationElement = a.element;
+
+      ClassElement annotationClassElement;
+      if (annotationElement is ExecutableElement) {
+        annotationElement = (annotationElement as ExecutableElement)
+            .returnType
+            .element as ClassElement;
+      }
+      if (annotationElement is ClassElement) {
+        annotationClassElement = annotationElement;
+      }
+      ModelElement annotationModelElement =
+          packageGraph.findCanonicalModelElementFor(annotationElement);
+      // annotationElement can be null if the element can't be resolved.
+      Class annotationClass = packageGraph
+          .findCanonicalModelElementFor(annotationClassElement) as Class;
+      if (annotationClass == null && annotationElement != null) {
+        annotationClass =
+            new ModelElement.fromElement(annotationClassElement, packageGraph)
+                as Class;
+      }
+      // Some annotations are intended to be invisible (@pragma)
+      if (annotationClass == null ||
+          !packageGraph.invisibleAnnotations.contains(annotationClass)) {
+        if (annotationModelElement != null) {
+          annotation = annotation.replaceFirst(
+              annotationModelElement.name, annotationModelElement.linkedName);
+        }
+        annotationStrings.add(annotation);
+      }
+    }
+    return annotationStrings;
   }
 
   bool _isPublic;
@@ -4510,12 +4536,13 @@ class PackageGraph {
     return _localPublicLibraries;
   }
 
-  // Return the set of [Class]es objects should inherit through if they
-  // show up in the inheritance chain.  Do not call before interceptorElement is
-  // found.  Add classes here if they are similar to Interceptor in that they
-  // are to be ignored even when they are the implementors of [Inheritable]s,
-  // and the class these inherit from should instead claim implementation.
   Set<Class> _inheritThrough;
+
+  /// Return the set of [Class]es objects should inherit through if they
+  /// show up in the inheritance chain.  Do not call before interceptorElement is
+  /// found.  Add classes here if they are similar to Interceptor in that they
+  /// are to be ignored even when they are the implementors of [Inheritable]s,
+  /// and the class these inherit from should instead claim implementation.
   Set<Class> get inheritThrough {
     if (_inheritThrough == null) {
       _inheritThrough = new Set();
@@ -4524,6 +4551,18 @@ class PackageGraph {
     return _inheritThrough;
   }
 
+  Set<Class> _invisibleAnnotations;
+
+  /// Returns the set of [Class] objects that are similar to pragma
+  /// in that we should never count them as documentable annotations.
+  Set<Class> get invisibleAnnotations {
+    if (_invisibleAnnotations == null) {
+      _invisibleAnnotations = new Set();
+      _invisibleAnnotations.add(specialClasses[SpecialClass.pragma]);
+    }
+    return _invisibleAnnotations;
+  }
+
   /// Looks up some [Library] that is reexporting this [Element]; not
   /// necessarily the canonical [Library].
   Library findLibraryFor(Element element) {
@@ -5007,8 +5046,10 @@ class Package extends LibraryContainer
             // The full version string of the package.
             case 'v':
               return packageMeta.version;
+            default:
+              assert(false, 'Unsupported case: ${m.group(1)}');
+              return null;
           }
-          ;
         });
         if (!_baseHref.endsWith('/')) _baseHref = '${_baseHref}/';
       } else {

lib/src/special_elements.dart

@@ -20,6 +20,9 @@ enum SpecialClass {
 
   /// From dart:_interceptors, Interceptor
   interceptor,
+
+  /// From dart:core, pragma
+  pragma,
 }
 
 /// A declaration of a special [Class] and how to find it.
@@ -66,6 +69,9 @@ final List<_SpecialClassDefinition> _specialClassDefinitions = [
   new _SpecialClassDefinition(SpecialClass.interceptor, 'Interceptor',
       '_interceptors', 'dart:_interceptors',
       required: false),
+  new _SpecialClassDefinition(
+      SpecialClass.pragma, 'pragma', 'dart.core', 'dart:core',
+      required: false),
 ];
 
 /// Given a SDK, resolve URIs for the libraries containing our special

test/compare_output_test.dart

@@ -83,7 +83,7 @@ void main() {
         '--example-path-prefix',
         'examples',
         '--exclude-packages',
-        'Dart,matcher,meta,path,stack_trace,tuple,quiver',
+        'Dart,matcher,meta,path,stack_trace,quiver',
         '--hide-sdk-text',
         '--no-include-source',
         '--output',

test/dartdoc_test.dart

@@ -74,27 +74,23 @@ void main() {
           await buildDartdoc(['--link-to-remote'], testPackageDir);
       DartdocResults results = await dartdoc.generateDocs();
       PackageGraph p = results.packageGraph;
-      Package tuple = p.publicPackages.firstWhere((p) => p.name == 'tuple');
+      Package meta = p.publicPackages.firstWhere((p) => p.name == 'meta');
       TopLevelVariable useSomethingInAnotherPackage = p.publicLibraries
           .firstWhere((l) => l.name == 'fake')
           .properties
           .firstWhere((p) => p.name == 'useSomethingInAnotherPackage');
-      expect(tuple.documentedWhere, equals(DocumentLocation.remote));
-      expect(
-          (useSomethingInAnotherPackage.modelType.typeArguments.first
-                  as ParameterizedElementType)
-              .element
-              .package
-              .documentedWhere,
-          equals(DocumentLocation.remote));
+      TopLevelVariable useSomethingInTheSdk = p.publicLibraries
+          .firstWhere((l) => l.name == 'fake')
+          .properties
+          .firstWhere((p) => p.name == 'useSomethingInTheSdk');
+      expect(meta.documentedWhere, equals(DocumentLocation.remote));
       expect(
           useSomethingInAnotherPackage.modelType.linkedName,
           startsWith(
-              '<a href="https://pub.dartlang.org/documentation/tuple/1.0.2/tuple/Tuple2-class.html">Tuple2</a>'));
+              '<a href=\"https://pub.dartlang.org/documentation/meta/1.1.6/meta/Required-class.html\">Required</a>'));
       RegExp stringLink = new RegExp(
           'https://api.dartlang.org/(dev|stable|edge|be)/${Platform.version.split(' ').first}/dart-core/String-class.html">String</a>');
-      expect(useSomethingInAnotherPackage.modelType.linkedName,
-          contains(stringLink));
+      expect(useSomethingInTheSdk.modelType.linkedName, contains(stringLink));
     });
 
     test('generate docs for ${pathLib.basename(testPackageDir.path)} works',

test/model_test.dart

@@ -227,7 +227,7 @@ void main() {
       });
 
       test('multiple packages, sorted default', () {
-        expect(ginormousPackageGraph.localPackages, hasLength(9));
+        expect(ginormousPackageGraph.localPackages, hasLength(4));
         expect(ginormousPackageGraph.localPackages.first.name,
             equals('test_package'));
       });
@@ -322,6 +322,15 @@ void main() {
                 .any((et) => et.name == 'Interceptor'),
             isFalse);
       });
+
+      test('Verify pragma is hidden in docs', () {
+        Class pragmaModelElement =
+            sdkAsPackageGraph.specialClasses[SpecialClass.pragma];
+        Class HasPragma = fakeLibrary.allClasses
+            .firstWhere((Class c) => c.name == 'HasPragma');
+        expect(pragmaModelElement.name, equals('pragma'));
+        expect(HasPragma.annotations, isEmpty);
+      });
     });
   });
 

testing/test_package/lib/fake.dart

@@ -48,9 +48,7 @@ library fake;
 
 import 'dart:async';
 import 'dart:collection';
-
-import 'package:tuple/tuple.dart';
-
+import 'package:meta/meta.dart' show Required;
 import 'css.dart' as css;
 import 'example.dart';
 import 'two_exports.dart' show BaseClass;
@@ -91,6 +89,10 @@ class HasGenerics<X, Y, Z> {
   Map<X, Y> convertToMap() => null;
 }
 
+/// This class uses a pragma annotation.
+@pragma('Hello world')
+class HasPragma {}
+
 /// This is a class with a table.
 ///
 /// It has multiple sentences before the table.  Because testing is a good
@@ -130,7 +132,8 @@ dynamic get mustGetThis => null;
 
 Map<dynamic, String> mapWithDynamicKeys = {};
 
-Tuple2<String, String> useSomethingInAnotherPackage;
+Required useSomethingInAnotherPackage;
+String useSomethingInTheSdk;
 
 /// Useful for annotations.
 class Annotation {

testing/test_package/pubspec.yaml

@@ -4,6 +4,5 @@ description: Best package ever.
 version: 0.0.1
 dependencies:
   meta: ^1.0.0
-  tuple: 1.0.2
   test_package_imported:
     path: "../test_package_imported"

testing/test_package_docs/fake/ABaseClass-class.html

@@ -60,6 +60,7 @@ <h5>fake library</h5>
       <li><a href="fake/Foo2-class.html">Foo2</a></li>
       <li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>
       <li><a href="fake/HasGenericWithExtends-class.html">HasGenericWithExtends</a></li>
+      <li><a href="fake/HasPragma-class.html">HasPragma</a></li>
       <li><a href="fake/ImplementingThingy-class.html">ImplementingThingy</a></li>
       <li><a href="fake/ImplementingThingy2-class.html">ImplementingThingy2</a></li>
       <li><a href="fake/ImplementsFutureVoid-class.html">ImplementsFutureVoid</a></li>
@@ -114,6 +115,7 @@ <h5>fake library</h5>
       <li><a href="fake/setAndGet.html">setAndGet</a></li>
       <li><a href="fake/simpleProperty.html">simpleProperty</a></li>
       <li><a href="fake/useSomethingInAnotherPackage.html">useSomethingInAnotherPackage</a></li>
+      <li><a href="fake/useSomethingInTheSdk.html">useSomethingInTheSdk</a></li>
 
       <li class="section-title"><a href="fake/fake-library.html#functions">Functions</a></li>
       <li><a href="fake/addCallback.html">addCallback</a></li>

testing/test_package_docs/fake/AClassUsingASuperMixin-class.html

@@ -60,6 +60,7 @@ <h5>fake library</h5>
       <li><a href="fake/Foo2-class.html">Foo2</a></li>
       <li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>
       <li><a href="fake/HasGenericWithExtends-class.html">HasGenericWithExtends</a></li>
+      <li><a href="fake/HasPragma-class.html">HasPragma</a></li>
       <li><a href="fake/ImplementingThingy-class.html">ImplementingThingy</a></li>
       <li><a href="fake/ImplementingThingy2-class.html">ImplementingThingy2</a></li>
       <li><a href="fake/ImplementsFutureVoid-class.html">ImplementsFutureVoid</a></li>
@@ -114,6 +115,7 @@ <h5>fake library</h5>
       <li><a href="fake/setAndGet.html">setAndGet</a></li>
       <li><a href="fake/simpleProperty.html">simpleProperty</a></li>
       <li><a href="fake/useSomethingInAnotherPackage.html">useSomethingInAnotherPackage</a></li>
+      <li><a href="fake/useSomethingInTheSdk.html">useSomethingInTheSdk</a></li>
 
       <li class="section-title"><a href="fake/fake-library.html#functions">Functions</a></li>
       <li><a href="fake/addCallback.html">addCallback</a></li>

testing/test_package_docs/fake/AClassWithFancyProperties-class.html

@@ -60,6 +60,7 @@ <h5>fake library</h5>
       <li><a href="fake/Foo2-class.html">Foo2</a></li>
       <li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>
       <li><a href="fake/HasGenericWithExtends-class.html">HasGenericWithExtends</a></li>
+      <li><a href="fake/HasPragma-class.html">HasPragma</a></li>
       <li><a href="fake/ImplementingThingy-class.html">ImplementingThingy</a></li>
       <li><a href="fake/ImplementingThingy2-class.html">ImplementingThingy2</a></li>
       <li><a href="fake/ImplementsFutureVoid-class.html">ImplementsFutureVoid</a></li>
@@ -114,6 +115,7 @@ <h5>fake library</h5>
       <li><a href="fake/setAndGet.html">setAndGet</a></li>
       <li><a href="fake/simpleProperty.html">simpleProperty</a></li>
       <li><a href="fake/useSomethingInAnotherPackage.html">useSomethingInAnotherPackage</a></li>
+      <li><a href="fake/useSomethingInTheSdk.html">useSomethingInTheSdk</a></li>
 
       <li class="section-title"><a href="fake/fake-library.html#functions">Functions</a></li>
       <li><a href="fake/addCallback.html">addCallback</a></li>