change to --include-external

Author: devoncarew

CHANGELOG.md

@@ -3,8 +3,8 @@
   "search" is passed, the page navigates to the first search result for its
   value.
 * [enhancement] added support for passing more than one `--header` or `--footer`
-* [enhancement] added the ability to `--include` libraries referenced by (but
-  not directly inside) the project
+* [enhancement] added the ability to include libraries referenced by (but not
+  directly inside) the project (`--include-external`)
 * [bug] rev the analyzer version used to fix an issue generating docs for
   Flutter
 

bin/dartdoc.dart

@@ -70,6 +70,7 @@ main(List<String> arguments) async {
 
   List<String> excludeLibraries = args['exclude'];
   List<String> includeLibraries = args['include'];
+  List<String> includeExternals = args['include-external'];
 
   String url = args['hosted-url'];
   List<String> footerFilePaths = args['footer'].map(_resolveTildePath).toList();
@@ -126,7 +127,8 @@ main(List<String> arguments) async {
   initializeConfig(addCrossdart: addCrossdart, includeSource: includeSource);
 
   var dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
-      outputDir, packageMeta, includeLibraries);
+      outputDir, packageMeta, includeLibraries,
+      includeExternals: includeExternals);
 
   Chain.capture(() async {
     DartDocResults results = await dartdoc.generateDocs();
@@ -190,6 +192,8 @@ ArgParser _createArgsParser() {
       allowMultiple: true, help: 'library names to ignore');
   parser.addOption('include',
       allowMultiple: true, help: 'library names to generate docs for');
+  parser.addOption('include-external',
+      allowMultiple: true, help: 'additional (external) libraries to include');
   parser.addOption('hosted-url',
       help:
           'URL where the docs will be hosted (used to generate the sitemap).');

lib/dartdoc.dart

@@ -60,17 +60,19 @@ Future<List<Generator>> initGenerators(String url, List<String> headerFilePaths,
 /// directory.
 class DartDoc {
   final Directory rootDir;
-  final List<String> excludes;
   final Directory sdkDir;
   final List<Generator> generators;
   final Directory outputDir;
   final PackageMeta packageMeta;
   final List<String> includes;
+  final List<String> includeExternals;
+  final List<String> excludes;
 
   Stopwatch _stopwatch;
 
   DartDoc(this.rootDir, this.excludes, this.sdkDir, this.generators,
-      this.outputDir, this.packageMeta, this.includes);
+      this.outputDir, this.packageMeta, this.includes,
+      {this.includeExternals: const []});
 
   /// Generate DartDoc documentation.
   ///
@@ -85,14 +87,25 @@ class DartDoc {
         ? const []
         : findFilesToDocumentInPackage(rootDir.path).toList();
 
-    List<LibraryElement> libraries = _parseLibraries(files, includes);
+    List<LibraryElement> libraries = _parseLibraries(files, includeExternals);
 
-    // remove excluded libraries
-    excludes.forEach((pattern) {
-      libraries.removeWhere((lib) {
-        return lib.name.startsWith(pattern) || lib.name == pattern;
+    if (includes != null && includes.isNotEmpty) {
+      Iterable knownLibraryNames = libraries.map((l) => l.name);
+      Set notFound =
+          new Set.from(includes).difference(new Set.from(knownLibraryNames));
+      if (notFound.isNotEmpty) {
+        throw 'Did not find: [${notFound.join(', ')}] in '
+            'known libraries: [${knownLibraryNames.join(', ')}]';
+      }
+      libraries.removeWhere((lib) => !includes.contains(lib.name));
+    } else {
+      // remove excluded libraries
+      excludes.forEach((pattern) {
+        libraries.removeWhere((lib) {
+          return lib.name.startsWith(pattern) || lib.name == pattern;
+        });
       });
-    });
+    }
 
     if (includes.isNotEmpty || excludes.isNotEmpty) {
       print('generating docs for libraries ${libraries.join(', ')}\n');
@@ -121,7 +134,7 @@ class DartDoc {
   }
 
   List<LibraryElement> _parseLibraries(
-      List<String> files, List<String> includes) {
+      List<String> files, List<String> includeExternals) {
     Set<LibraryElement> libraries = new Set();
     DartSdk sdk = new DirectoryBasedDartSdk(new JavaFile(sdkDir.path));
     List<UriResolver> resolvers = [];
@@ -206,10 +219,10 @@ class DartDoc {
       result = context.performAnalysisTask();
     }
 
-    // Use the includes.
+    // Use the includeExternals.
     for (Source source in context.librarySources) {
       LibraryElement library = context.computeLibraryElement(source);
-      if (includes.contains(Library.getLibraryName(library))) {
+      if (includeExternals.contains(Library.getLibraryName(library))) {
         libraries.add(library);
       }
     }

test/dartdoc_test.dart

@@ -73,15 +73,15 @@ void main() {
     test('generate docs including a single library', () async {
       PackageMeta meta = new PackageMeta.fromDir(testPackageDir);
       DartDoc dartdoc = new DartDoc(
-          testPackageDir, [], getSdkDir(), [], tempDir, meta, ['dart.core']);
+          testPackageDir, [], getSdkDir(), [], tempDir, meta, ['fake']);
 
       DartDocResults results = await dartdoc.generateDocs();
       expect(results.package, isNotNull);
 
       Package p = results.package;
       expect(p.name, 'test_package');
       expect(p.hasDocumentationFile, isTrue);
-      expect(p.libraries.map((lib) => lib.name), contains('dart:core'));
+      expect(p.libraries, hasLength(1));
       expect(p.libraries.map((lib) => lib.name), contains('fake'));
     });