Do not throw on "empty" package; emit warning instead (#2360)

* Only emit a log message instead of throwing.

* Add a full warning and test

* Dartfmt

* Fix comment

* Fix empty package check in packages test

Author: jcollins-g

lib/dartdoc.dart

@@ -222,8 +222,7 @@ class Dartdoc {
 
       var dartdocResults = await generateDocsBase();
       if (dartdocResults.packageGraph.localPublicLibraries.isEmpty) {
-        throw DartdocFailure(
-            'dartdoc could not find any libraries to document');
+        logWarning('dartdoc could not find any libraries to document');
       }
 
       final errorCount =

lib/src/model/package.dart

@@ -186,10 +186,6 @@ class Package extends LibraryContainer
       if (isLocal) {
         if (isPublic) {
           _documentedWhere = DocumentLocation.local;
-        } else {
-          // Possible if excludes result in a "documented" package not having
-          // any actual documentation.
-          _documentedWhere = DocumentLocation.missing;
         }
       } else {
         if (config.linkToRemote && config.linkToUrl.isNotEmpty && isPublic) {

lib/src/model/package_graph.dart

@@ -75,6 +75,7 @@ class PackageGraph {
 
     // Scan all model elements to insure that interceptor and other special
     // objects are found.
+    // Emit warnings for any local package that has no libraries.
     // After the allModelElements traversal to be sure that all packages
     // are picked up.
     for (var package in documentedPackages) {
@@ -83,6 +84,9 @@ class PackageGraph {
         _addToImplementors(library.allClasses);
         _extensions.addAll(library.extensions);
       }
+      if (package.isLocal && !package.hasPublicLibraries) {
+        package.warn(PackageWarning.noDocumentableLibrariesInPackage);
+      }
     }
     for (var l in _implementors.values) {
       l.sort();
@@ -362,6 +366,10 @@ class PackageGraph {
         warningMessage =
             '${warnable.fullyQualifiedName} has no library level documentation comments';
         break;
+      case PackageWarning.noDocumentableLibrariesInPackage:
+        warningMessage =
+            '${warnable.fullyQualifiedName} has no documentable libraries';
+        break;
       case PackageWarning.ambiguousDocReference:
         warningMessage = 'ambiguous doc reference $message';
         break;

lib/src/warnings.dart

@@ -159,6 +159,17 @@ final Map<PackageWarning, PackageWarningDefinition> packageWarningDefinitions =
       PackageWarning.notImplemented,
       'not-implemented',
       'The code makes use of a feature that is not yet implemented in dartdoc'),
+  PackageWarning.noDocumentableLibrariesInPackage: PackageWarningDefinition(
+    PackageWarning.noDocumentableLibrariesInPackage,
+    'no-documentable-libraries',
+    'The package is to be documented but has no Dart libraries to document',
+    longHelp: [
+      'Dartdoc could not find any public libraries to document in @@name@@, ',
+      'but documentation was requested.  This might be expected for an ',
+      'asset only package, in which case, disable this warning in your ',
+      'dartdoc_options.yaml file.',
+    ],
+  ),
   PackageWarning.noLibraryLevelDocs: PackageWarningDefinition(
       PackageWarning.noLibraryLevelDocs,
       'no-library-level-docs',
@@ -266,6 +277,7 @@ enum PackageWarning {
   noCanonicalFound,
   noDefiningLibraryFound,
   notImplemented,
+  noDocumentableLibrariesInPackage,
   noLibraryLevelDocs,
   packageOrderGivesMissingPackageName,
   reexportedPrivateApiAcrossPackages,

test/end2end/dartdoc_integration_test.dart

@@ -21,6 +21,8 @@ String get _testPackagePath =>
     path.fromUri(_currentFileUri.resolve('../../testing/test_package'));
 String get _testPackageFlutterPluginPath => path.fromUri(_currentFileUri
     .resolve('../../testing/flutter_packages/test_package_flutter_plugin'));
+String get _testPackageMinimumPath =>
+    path.fromUri(_currentFileUri.resolve('../../testing/test_package_minimum'));
 
 void main() {
   group('Invoking command-line dartdoc', () {
@@ -45,6 +47,20 @@ void main() {
       await Future.wait(CoverageSubprocessLauncher.coverageResults);
     });
 
+    test('running on an empty package does not crash and generates a warning',
+        () async {
+      var outputDir =
+          await Directory.systemTemp.createTemp('dartdoc.testEmpty.');
+      var outputLines = <String>[];
+      await subprocessLauncher.runStreamed(Platform.resolvedExecutable,
+          [dartdocPath, '--output', outputDir.path],
+          perLine: outputLines.add, workingDirectory: _testPackageMinimumPath);
+      expect(
+          outputLines,
+          contains(matches(
+              'package:test_package_minimum has no documentable libraries')));
+    }, timeout: Timeout.factor(2));
+
     test('running --no-generate-docs is quiet and does not generate docs',
         () async {
       var outputDir =

testing/test_package_minimum/pubspec.yaml

@@ -0,0 +1,4 @@
+name: test_package_minimum
+homepage: http://github.com/dart-lang
+description: The only package with no bugs.
+version: 0.0.3

tool/travis.sh

@@ -36,7 +36,7 @@ elif [ "$DARTDOC_BOT" = "packages" ]; then
   fi
   PACKAGE_NAME=access PACKAGE_VERSION=">=1.0.1+2" pub run grinder build-pub-package
   # Negative test for flutter_plugin_tools, make sure right error message is displayed.
-  PACKAGE_NAME=flutter_plugin_tools PACKAGE_VERSION=">=0.0.14+1" pub run grinder build-pub-package 2>&1 | grep "dartdoc failed: dartdoc could not find any libraries to document.$"
+  PACKAGE_NAME=flutter_plugin_tools PACKAGE_VERSION=">=0.0.14+1" pub run grinder build-pub-package 2>&1 | grep "warning: package:flutter_plugin_tools has no documentable libraries"
   PACKAGE_NAME=shelf_exception_handler PACKAGE_VERSION=">=0.2.0" pub run grinder build-pub-package
 elif [ "$DARTDOC_BOT" = "sdk-analyzer" ]; then
   echo "Running all tests against the SDK analyzer"