add ability to include certain libraries, correctly omit errors and exceptions from class list, more tests,

Closes #724

LGTM given by: @sethladd

Squashed commit of the following:

commit ad6d368
Author: Seth Ladd <[email protected]>
Date:   Thu Jul 23 16:18:07 2015 -0700

    add ability to include certain libraries, correctly omit errors and exceptions from class list, more tests,

Author: sethladd

bin/dartdoc.dart

@@ -53,6 +53,9 @@ main(List<String> arguments) async {
 
   List<String> excludeLibraries =
       args['exclude'] == null ? [] : args['exclude'].split(',');
+  List<String> includeLibraries =
+      args['include'] == null ? [] : args['include'].split(',');
+
   String url = args['hosted-url'];
   String footerFilePath = _resolveTildePath(args['footer']);
   if (footerFilePath != null && !new File(footerFilePath).existsSync()) {
@@ -108,7 +111,7 @@ main(List<String> arguments) async {
   var generators = initGenerators(url, headerFilePath, footerFilePath);
 
   var dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
-      outputDir, packageRootDir, packageMeta, urlMappings);
+      outputDir, packageRootDir, packageMeta, urlMappings, includeLibraries);
 
   try {
     DartDocResults results = await dartdoc.generateDocs();
@@ -164,6 +167,8 @@ ArgParser _createArgsParser() {
       splitCommas: false);
   parser.addOption('exclude',
       help: 'Comma-separated list of library names to ignore.');
+  parser.addOption('include',
+      help: 'Comma-separated list of library names to generate docs for.');
   parser.addOption('hosted-url',
       help: 'URL where the docs will be hosted (used to generate the sitemap).');
   return parser;

lib/dartdoc.dart

@@ -53,13 +53,13 @@ class DartDoc {
   final Directory packageRootDir;
   final PackageMeta packageMeta;
   final Map<String, String> urlMappings;
-
-  final Set<LibraryElement> libraries = new Set();
+  final List<String> includes;
 
   Stopwatch _stopwatch;
 
   DartDoc(this.rootDir, this.excludes, this.sdkDir, this.generators,
-      this.outputDir, this.packageRootDir, this.packageMeta, this.urlMappings);
+      this.outputDir, this.packageRootDir, this.packageMeta, this.urlMappings,
+      this.includes);
 
   /// Generate DartDoc documentation.
   ///
@@ -72,16 +72,30 @@ class DartDoc {
 
     if (packageRootDir != null) loader.packageRootPath = packageRootDir.path;
 
-    var files =
+    List<String> files =
         packageMeta.isSdk ? [] : findFilesToDocumentInPackage(rootDir.path);
 
-    List<LibraryElement> libs = [];
-    libs.addAll(_parseLibraries(files));
-    // remove excluded libraries
-    excludes.forEach(
-        (pattern) => libs.removeWhere((l) => l.name.startsWith(pattern)));
-    libs.removeWhere((library) => excludes.contains(library.name));
-    libraries.addAll(libs);
+    List<LibraryElement> libraries = _parseLibraries(files);
+
+    if (includes != null && includes.isNotEmpty) {
+      Set notFound = new Set.from(includes)
+          .difference(new Set.from(libraries.map((l) => l.name)));
+      if (notFound.isNotEmpty) {
+        return new Future.error('Some libraries not found: $notFound');
+      }
+      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');
+    }
 
     Package package = new Package(libraries, packageMeta);
 
@@ -101,6 +115,7 @@ class DartDoc {
   }
 
   List<LibraryElement> _parseLibraries(List<String> files) {
+    Set<LibraryElement> libraries = new Set();
     DartSdk sdk = new DirectoryBasedDartSdk(new JavaFile(sdkDir.path));
     List<UriResolver> resolvers = [
       new DartUriResolver(sdk),

lib/src/html_generator.dart

@@ -233,7 +233,7 @@ class HtmlGeneratorInstance {
       'self': package
     };
 
-    if (package.hasDocumentation) {
+    if (package.hasDocumentationFile) {
       FileContents readme = package.documentationFile;
       data['markdown'] = readme.isMarkdown ? renderMarkdown : renderPlainText;
     }
@@ -242,7 +242,7 @@ class HtmlGeneratorInstance {
   }
 
   void generateLibrary(Package package, Library lib) {
-    print('generating docs for library ${lib.path}...');
+    print('generating docs for library ${lib.name} from ${lib.path}...');
 
     if (!lib.hasDocumentation) {
       print("  warning: library '${lib.name}' has no documentation");

lib/src/model.dart

@@ -368,14 +368,14 @@ class Package {
 
   String get version => packageMeta.version;
 
-  bool get hasDocumentation => documentationFile != null;
+  bool get hasDocumentationFile => documentationFile != null;
 
   FileContents get documentationFile => packageMeta.getReadmeContents();
 
   // TODO: Clients should use [documentationFile] so they can act differently on
   // plain text or markdown.
   String get documentation =>
-      hasDocumentation ? documentationFile.contents : null;
+      hasDocumentationFile ? documentationFile.contents : null;
 
   String get documentationAsHtml => renderMarkdownToHtml(documentation);
 
@@ -508,7 +508,11 @@ class Library extends ModelElement {
       _name = element.name;
     }
 
-    // calculate this once, instead on every invocation of name getter
+    // So, if the library is a system library, it's name is not
+    // dart:___, it's dart.___. Apparently the way to get to the dart:___
+    // name is to get source.encoding.
+    // This may be wrong or misleading, but developers expect the name
+    // of dart:____
     var source = _library.definingCompilationUnit.source;
     _name = source.isInSystemLibrary ? source.encoding : _name;
 
@@ -643,12 +647,7 @@ class Library extends ModelElement {
     return _classes;
   }
 
-  /// if SDK, return all classes
-  /// if package, return classes that are not [Error] or [Exception]
   List<Class> get classes {
-    if (package.isSdk) {
-      return _allClasses;
-    }
     return _allClasses.where((c) => !c.isErrorOrException).toList(
         growable: false);
   }
@@ -1065,6 +1064,9 @@ class Class extends ModelElement {
           (type.name == 'Exception' || type.name == 'Error'));
     }
 
+    // if this class is itself Error or Exception, return true
+    if (_doCheck(_cls.type)) return true;
+
     return _cls.allSupertypes.any(_doCheck);
   }
 

test/dartdoc_test.dart

@@ -27,31 +27,77 @@ void main() {
       delete(tempDir);
     });
 
-    test('generateDocs ${path.basename(testPackageDir.path)}', () async {
+    test('generate docs for ${path.basename(testPackageDir.path)} works',
+        () async {
       PackageMeta meta = new PackageMeta.fromDir(testPackageDir);
       DartDoc dartdoc = new DartDoc(
-          testPackageDir, [], getSdkDir(), [], tempDir, null, meta, null);
+          testPackageDir, [], getSdkDir(), [], tempDir, null, meta, null, []);
 
       DartDocResults results = await dartdoc.generateDocs();
       expect(results.package, isNotNull);
 
       Package p = results.package;
       expect(p.name, 'test_package');
-      expect(p.hasDocumentation, true);
-      expect(p.libraries.length, 7);
+      expect(p.hasDocumentationFile, isTrue);
+      expect(p.libraries, hasLength(7));
     });
 
-    test('generateDocs ${path.basename(testPackageBadDir.path)}', () async {
+    test('generate docs for ${path.basename(testPackageBadDir.path)} fails',
+        () async {
       PackageMeta meta = new PackageMeta.fromDir(testPackageBadDir);
-      DartDoc dartdoc = new DartDoc(
-          testPackageBadDir, [], getSdkDir(), [], tempDir, null, meta, null);
+      DartDoc dartdoc = new DartDoc(testPackageBadDir, [], getSdkDir(), [],
+          tempDir, null, meta, null, []);
 
       try {
         await dartdoc.generateDocs();
         fail('dartdoc should fail on analysis errors');
       } catch (e) {
-        expect(e is DartDocFailure, true);
+        expect(e is DartDocFailure, isTrue);
       }
     });
+
+    test('generate docs for a package that does not have a readme', () async {
+      PackageMeta meta = new PackageMeta.fromDir(testPackageWithNoReadme);
+      DartDoc dartdoc = new DartDoc(testPackageWithNoReadme, [], getSdkDir(),
+          [], tempDir, null, meta, null, []);
+
+      DartDocResults results = await dartdoc.generateDocs();
+      expect(results.package, isNotNull);
+
+      Package p = results.package;
+      expect(p.name, 'test_package_small');
+      expect(p.hasDocumentationFile, isFalse);
+      expect(p.libraries, hasLength(1));
+    });
+
+    test('generate docs including a single library', () async {
+      PackageMeta meta = new PackageMeta.fromDir(testPackageDir);
+      DartDoc dartdoc = new DartDoc(testPackageDir, [], getSdkDir(), [],
+          tempDir, null, meta, null, ['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, hasLength(1));
+      expect(p.libraries.map((lib) => lib.name), contains('fake'));
+    });
+
+    test('generate docs excluding a single library', () async {
+      PackageMeta meta = new PackageMeta.fromDir(testPackageDir);
+      DartDoc dartdoc = new DartDoc(testPackageDir, ['fake'], getSdkDir(), [],
+          tempDir, null, meta, null, []);
+
+      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, hasLength(6));
+      expect(p.libraries.map((lib) => lib.name).contains('fake'), isFalse);
+    });
   });
 }

test/src/utils.dart

@@ -8,6 +8,7 @@ import 'dart:io';
 
 final Directory testPackageDir = new Directory('test_package');
 final Directory testPackageBadDir = new Directory('test_package_bad');
+final Directory testPackageWithNoReadme = new Directory('test_package_small');
 
 void delete(Directory dir) {
   if (dir.existsSync()) dir.deleteSync(recursive: true);