Merge master into nnbd

example/README.md

@@ -9,7 +9,7 @@ in the Dart ecosystem.
 
 The Dart team builds docs for the [Dart API reference](https://api.dart.dev/)
 with each new version of the SDK, via
-[this script](https://github.com/dart-lang/sdk/blob/master/tools/bots/dart_sdk.py).
+[this script](https://github.com/dart-lang/sdk/blob/main/tools/bots/dart_sdk.py).
 Look for `BuildDartdocAPIDocs`.
 
 ## Flutter

lib/src/dartdoc_options.dart

@@ -1240,7 +1240,7 @@ class DartdocOptionContext extends DartdocOptionContextBase
   List<String> get excludePackages =>
       optionSet['excludePackages'].valueAt(context);
 
-  String get flutterRoot => optionSet['flutterRoot'].valueAt(context);
+  String? get flutterRoot => optionSet['flutterRoot'].valueAt(context);
 
   bool get hideSdkText => optionSet['hideSdkText'].valueAt(context);
 

lib/src/experiment_options.dart

@@ -6,7 +6,7 @@
 
 ///
 /// Implementation of Dart language experiment option handling for dartdoc.
-/// See https://github.com/dart-lang/sdk/blob/master/docs/process/experimental-flags.md.
+/// See https://github.com/dart-lang/sdk/blob/main/docs/process/experimental-flags.md.
 ///
 library dartdoc.experiment_options;
 

lib/src/model/package_graph.dart

@@ -12,6 +12,7 @@ import 'package:analyzer/file_system/file_system.dart';
 import 'package:analyzer/src/generated/sdk.dart';
 import 'package:analyzer/src/generated/source.dart';
 import 'package:analyzer/src/generated/source_io.dart';
+import 'package:dartdoc/dartdoc.dart' show DartdocFailure;
 import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/logging.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
@@ -65,6 +66,10 @@ class PackageGraph with CommentReferable, Nameable {
     var libraryElement = resolvedLibrary.element;
     var packageMeta =
         packageMetaProvider.fromElement(libraryElement, config.sdkDir);
+    if (packageMeta == null) {
+      throw DartdocFailure(packageMetaProvider.getMessageForMissingPackageMeta(
+          libraryElement, config));
+    }
     var lib = Library.fromLibraryResult(
         resolvedLibrary, this, Package.fromPackageMeta(packageMeta, this));
     packageMap[packageMeta.name].libraries.add(lib);

lib/src/package_meta.dart

@@ -44,7 +44,8 @@ final PackageMetaProvider pubPackageMetaProvider = PackageMetaProvider(
         .getFile(PhysicalResourceProvider.INSTANCE.pathContext
             .absolute(Platform.resolvedExecutable))
         .parent2
-        .parent2);
+        .parent2,
+    messageForMissingPackageMeta: PubPackageMeta.messageForMissingPackageMeta);
 
 /// Sets the supported way of constructing [PackageMeta] objects.
 ///
@@ -63,15 +64,30 @@ class PackageMetaProvider {
       _fromElement;
   final PackageMeta? Function(String, ResourceProvider) _fromFilename;
   final PackageMeta? Function(Folder, ResourceProvider) _fromDir;
+  final String Function(LibraryElement, DartdocOptionContext)
+      _messageForMissingPackageMeta;
 
   PackageMeta? fromElement(LibraryElement library, String s) =>
       _fromElement(library, s, resourceProvider);
   PackageMeta? fromFilename(String s) => _fromFilename(s, resourceProvider);
   PackageMeta? fromDir(Folder dir) => _fromDir(dir, resourceProvider);
 
+  String getMessageForMissingPackageMeta(
+          LibraryElement library, DartdocOptionContext optionContext) =>
+      _messageForMissingPackageMeta(library, optionContext);
+
   PackageMetaProvider(this._fromElement, this._fromFilename, this._fromDir,
       this.resourceProvider, this.defaultSdkDir,
-      {this.defaultSdk});
+      {this.defaultSdk,
+      String Function(LibraryElement, DartdocOptionContext)?
+          messageForMissingPackageMeta})
+      : _messageForMissingPackageMeta = messageForMissingPackageMeta ??
+            _defaultMessageForMissingPackageMeta;
+
+  static String _defaultMessageForMissingPackageMeta(
+      LibraryElement library, DartdocOptionContext optionContext) {
+    return 'Unknown package for library: ${library.source.fullName}';
+  }
 }
 
 /// Describes a single package in the context of `dartdoc`.
@@ -252,6 +268,17 @@ abstract class PubPackageMeta extends PackageMeta {
     return _packageMetaCache[pathContext.absolute(folder.path)];
   }
 
+  /// Create a helpful user error message for a case where a package can not
+  /// be found.
+  static String messageForMissingPackageMeta(
+      LibraryElement library, DartdocOptionContext optionContext) {
+    var libraryString = library.librarySource.fullName;
+    var dartOrFlutter = optionContext.flutterRoot == null ? 'dart' : 'flutter';
+    return 'Unknown package for library: $libraryString.  Consider `$dartOrFlutter pub get` and/or '
+        '`$dartOrFlutter pub global deactivate dartdoc` followed by `$dartOrFlutter pub global activate dartdoc` to fix. '
+        'Also, be sure that `$dartOrFlutter analyze` completes without errors.';
+  }
+
   @override
   String? sdkType(String? flutterRootPath) {
     if (flutterRootPath != null) {

test/documentation_comment_test.dart

@@ -52,6 +52,8 @@ void main() {
         resourceProvider,
         sdkFolder,
         defaultSdk: mockSdk,
+        messageForMissingPackageMeta:
+            PubPackageMeta.messageForMissingPackageMeta,
       );
       var optionSet = await DartdocOptionRoot.fromOptionGenerators(
           'dartdoc', [createDartdocOptions], packageMetaProvider);

test/end2end/model_special_cases_test.dart

@@ -230,6 +230,49 @@ void main() {
         expect(referenceLookup(A, 'new'), equals(MatchingLinkResult(null)));
         expect(referenceLookup(At, 'new'), equals(MatchingLinkResult(null)));
       });
+
+      test('constant rendering', () {
+        TopLevelVariable aFunc,
+            aFuncParams,
+            aTearOffDefaultConstructor,
+            aTearOffNonDefaultConstructor,
+            aTearOffNonDefaultConstructorInt,
+            aTearOffDefaultConstructorArgs;
+        TopLevelVariable aTearOffDefaultConstructorTypedef;
+        aFunc =
+            constructorTearoffs.constants.firstWhere((c) => c.name == 'aFunc');
+        aFuncParams = constructorTearoffs.constants
+            .firstWhere((c) => c.name == 'aFuncParams');
+        aTearOffDefaultConstructor = constructorTearoffs.constants
+            .firstWhere((c) => c.name == 'aTearOffDefaultConstructor');
+        aTearOffNonDefaultConstructor = constructorTearoffs.constants
+            .firstWhere((c) => c.name == 'aTearOffNonDefaultConstructor');
+        aTearOffNonDefaultConstructorInt = constructorTearoffs.constants
+            .firstWhere((c) => c.name == 'aTearOffNonDefaultConstructorInt');
+        aTearOffDefaultConstructorArgs = constructorTearoffs.constants
+            .firstWhere((c) => c.name == 'aTearOffDefaultConstructorArgs');
+        aTearOffDefaultConstructorTypedef = constructorTearoffs.constants
+            .firstWhere((c) => c.name == 'aTearOffDefaultConstructorTypedef');
+
+        expect(aFunc.constantValue, equals('func'));
+        expect(aFuncParams.constantValue, equals('funcTypeParams'));
+        // Does not work @ analyzer 2.2
+        //expect(aFuncWithArgs.constantValue, equals('funcTypeParams<String, int>'));
+
+        expect(aTearOffDefaultConstructor.constantValue, equals('F.new'));
+        expect(aTearOffNonDefaultConstructor.constantValue,
+            equals('F.alternative'));
+        expect(aTearOffNonDefaultConstructorInt.constantValue,
+            equals('F<int>.alternative'));
+        expect(aTearOffDefaultConstructorArgs.constantValue,
+            equals('F<String>.new'));
+
+        expect(aTearOffDefaultConstructorTypedef.constantValue,
+            equals('Fstring.new'));
+        // Does not work @ analyzer 2.2
+        //expect(aTearOffDefaultConstructorArgsTypedef.constantValue,
+        //    equals('Ft<String>.new'));
+      });
     }, skip: !_constructorTearoffsAllowed.allows(utils.platformVersion));
   });
 

test/end2end/model_test.dart

@@ -95,6 +95,16 @@ void main() {
         packageGraph.libraries.firstWhere((lib) => lib.name == 'base_class');
   });
 
+  group('PackageMeta and PackageGraph integration', () {
+    test('PackageMeta error messages generate correctly', () {
+      var message = packageGraph.packageMetaProvider
+          .getMessageForMissingPackageMeta(
+              fakeLibrary.element, packageGraph.config);
+      expect(message, contains('fake.dart'));
+      expect(message, contains('pub global activate dartdoc'));
+    });
+  });
+
   group('triple-shift', () {
     Library tripleShift;
     Class C, E, F;

test/src/utils.dart

@@ -95,6 +95,7 @@ PackageMetaProvider get testPackageMetaProvider {
     resourceProvider,
     sdkFolder,
     defaultSdk: mockSdk,
+    messageForMissingPackageMeta: PubPackageMeta.messageForMissingPackageMeta,
   );
 }
 

testing/test_package_experiments/lib/constructor_tearoffs.dart

@@ -46,6 +46,8 @@ class F<T> {
   F() {
     print('I too am a valid constructor invocation with this feature.');
   }
+
+  F.alternative() {}
 }
 
 typedef Ft = F;
@@ -59,3 +61,21 @@ typedef NotAClass = Function;
 /// Mixins don't have constructors either, so disallow `M.new`.
 mixin M<T> on C {
 }
+
+void func() {}
+void funcTypeParams<T extends String, U extends num>(T something, U different) {}
+
+const aFunc = func;
+const aFuncParams = funcTypeParams;
+// TODO(jcollins-g): does not work @ analyzer 2.2
+//const aFuncWithArgs = funcTypeParams<String, int>;
+
+const aTearOffDefaultConstructor = F.new;
+const aTearOffNonDefaultConstructor = F.alternative;
+const aTearOffNonDefaultConstructorInt = F<int>.alternative;
+const aTearOffDefaultConstructorArgs = F<String>.new;
+
+const aTearOffDefaultConstructorTypedef = Fstring.new;
+
+// TODO(jcollins-g): does not work @ analyzer 2.2
+//const aTearOffDefaultConstructorArgsTypedef = Ft<String>.new;