Several new features and improvements for dartdoc.

lib/dartdoc/dartdoc.dart

Index: lib/dartdoc/dartdoc.dart
diff --git a/lib/dartdoc/dartdoc.dart b/lib/dartdoc/dartdoc.dart
index 5ce8427ea81bb5c1e319dff9818067e60c17256f..ddbc031669ee4c9104051d8c5970f43460b13e73 100644
--- a/lib/dartdoc/dartdoc.dart
+++ b/lib/dartdoc/dartdoc.dart
@@ -26,6 +26,7 @@
 #import('markdown.dart', prefix: 'md');
 #import('../compiler/implementation/scanner/scannerlib.dart',
         prefix: 'dart2js');
+#import('../compiler/implementation/library_map.dart');
 
 #source('comment_map.dart');
 #source('utils.dart');
@@ -56,19 +57,15 @@ final MODE_STATIC = 0;
  */
 final MODE_LIVE_NAV = 1;
 
+final API_LOCATION = 'http://api.dartlang.org/';
+
 /**
  * Run this from the `lib/dartdoc` directory.
  */
 void main() {
   final args = new Options().arguments;
 
-  // Parse the dartdoc options.
-  bool includeSource;
-  int mode;
-  Path outputDir;
-  bool generateAppCache;
-  bool omitGenerationTime;
-  bool verbose;
+  final dartdoc = new Dartdoc();
 
   if (args.isEmpty()) {
     print('No arguments provided.');
@@ -76,37 +73,57 @@ void main() {
     return;
   }
 
-  for (int i = 0; i < args.length - 1; i++) {
+  final entrypoints = <Path>[];
+
+  var i = 0;
+  while (i < args.length) {
     final arg = args[i];
+    if (!arg.startsWith('--')) {
+      // The remaining arguments must be entry points.
+      break;
+    }
 
     switch (arg) {
       case '--no-code':
-        includeSource = false;
+        dartdoc.includeSource = false;
         break;
 
       case '--mode=static':
-        mode = MODE_STATIC;
+        dartdoc.mode = MODE_STATIC;
         break;
 
       case '--mode=live-nav':
-        mode = MODE_LIVE_NAV;
+        dartdoc.mode = MODE_LIVE_NAV;
         break;
 
       case '--generate-app-cache':
       case '--generate-app-cache=true':
-        generateAppCache = true;
+        dartdoc.generateAppCache = true;
         break;
 
       case '--omit-generation-time':
-        omitGenerationTime = true;
+        dartdoc.omitGenerationTime = true;
         break;
       case '--verbose':
-        verbose = true;
+        dartdoc.verbose = true;
+        break;
+      case '--include-api':
+        dartdoc.includeApi = true;
+        break;
+      case '--link-api':
+        dartdoc.linkToApi = true;
         break;
 
       default:
         if (arg.startsWith('--out=')) {
-          outputDir = new Path.fromNative(arg.substring('--out='.length));
+          dartdoc.outputDir =
+              new Path.fromNative(arg.substring('--out='.length));
+        } else if (arg.startsWith('--include-lib=')) {
+          dartdoc.includedLibraries =
+              arg.substring('--include-lib='.length).split(',');
+        } else if (arg.startsWith('--exclude-lib=')) {
+          dartdoc.excludedLibraries =
+              arg.substring('--exclude-lib='.length).split(',');
         } else {
           print('Unknown option: $arg');
           printUsage();
@@ -114,24 +131,23 @@ void main() {
         }
         break;
     }
+    i++;
+  }
+  while (i < args.length) {
+    final arg = args[i];
+    entrypoints.add(new Path.fromNative(arg));
+    i++;
   }
 
-  final entrypoint = new Path.fromNative(args[args.length - 1]);
-
-  final dartdoc = new Dartdoc();
-
-  if (includeSource != null) dartdoc.includeSource = includeSource;
-  if (mode != null) dartdoc.mode = mode;
-  if (outputDir != null) dartdoc.outputDir = outputDir;
-  if (generateAppCache != null) dartdoc.generateAppCache = generateAppCache;
-  if (omitGenerationTime != null) {
-    dartdoc.omitGenerationTime = omitGenerationTime;
+  if (entrypoints.isEmpty()) {
+    print('No entrypoints provided.');
+    printUsage();
+    return;
   }
-  if (verbose != null) dartdoc.verbose = verbose;
 
   cleanOutputDirectory(dartdoc.outputDir);
 
-  dartdoc.documentEntryPoint(entrypoint, libPath);
+  dartdoc.documentLibraries(entrypoints, libPath);
 
   // Compile the client-side code to JS.
   final clientScript = (dartdoc.mode == MODE_STATIC) ? 'static' : 'live-nav';
@@ -151,7 +167,7 @@ void main() {
 
 void printUsage() {
   print('''
-Usage dartdoc [options] <entrypoint>
+Usage dartdoc [options] <entrypoint(s)>
 [options] include
  --no-code                   Do not include source code in the documentation.
 
@@ -179,6 +195,25 @@ Usage dartdoc [options] <entrypoint>
  --out=<dir>                 Generates files into directory <dir>. If omitted
                              the files are generated into ./docs/
 
+ --link-api                  Link to the online language API in the generated
+                             documentation. The option overrides inclusion
+                             through --include-api or --include-lib.
+
+ --include-api               Include the used API libraries in the generated
+                             documentation.  If the --link-api option is used,
+                             this option is ignored.
+
+ --include-lib=<libs>        Use this option to explicitly specify which
+                             libraries to include in the documentation. If
+                             omitted, all used libraries are included by
+                             default. <libs> is comma-separated list of library
+                             names.
+
+ --exclude-lib=<libs>        Use this option to explicitly specify which
+                             libraries to exclude from the documentation. If
+                             omitted, no libraries are excluded. <libs> is
+                             comma-separated list of library names.
+
  --verbose                   Print verbose information during generation.
 ''');
 }
@@ -312,8 +347,17 @@ class Dartdoc {
   /** Set by Dartdoc user to print extra information during generation. */
   bool verbose = false;
 
-  /** Set this to select the libraries to document */
-  List<String> libraries = null;
+  /** Set this to include API libraries in the documentation. */
+  bool includeApi = false;
+
+  /** Set this to generate links to the online API. */
+  bool linkToApi = false;
+
+  /** Set this to select the libraries to include in the documentation. */
+  List<String> includedLibraries = const <String>[];
+
+  /** Set this to select the libraries to exclude from the documentation. */
+  List<String> excludedLibraries = const <String>[];
 
   /**
    * This list contains the libraries sorted in by the library name.
@@ -353,11 +397,50 @@ class Dartdoc {
             currentMember: _currentMember));
   }
 
-  bool includeLibrary(LibraryMirror library) {
-    if (libraries != null) {
-      return libraries.indexOf(library.simpleName()) != -1;
+  /**
+   * Returns `true` if [library] is included in the generated documentation.
+   */
+  bool shouldIncludeLibrary(LibraryMirror library) {
+    if (shouldLinkToPublicApi(library)) {
+      return false;
+    }
+    var includeByDefault = true;
+    String libraryName = library.simpleName();
+    if (!includedLibraries.isEmpty()) {
+      includeByDefault = false;
+      if (includedLibraries.indexOf(libraryName) != -1) {
+        return true;
+      }
+    }
+    if (excludedLibraries.indexOf(libraryName) != -1) {
+      return false;
+    }
+    if (libraryName.startsWith('dart:')) {
+      String suffix = libraryName.substring('dart:'.length);
+      LibraryInfo info = DART2JS_LIBRARY_MAP[suffix];
+      if (info != null) {
+        return !info.isInternal && includeApi;
+      }
+    }
+    return includeByDefault;
+  }
+
+  /**
+   * Returns `true` if links to the public API should be generated for
+   * [library].
+   */
+  bool shouldLinkToPublicApi(LibraryMirror library) {
+    if (linkToApi) {
+      String libraryName = library.simpleName();
+      if (libraryName.startsWith('dart:')) {
+        String suffix = libraryName.substring('dart:'.length);
+        LibraryInfo info = DART2JS_LIBRARY_MAP[suffix];
+        if (info != null) {
+          return !info.isInternal;
+        }
+      }
     }
-    return true;
+    return false;
   }
 
   String get footerContent(){
@@ -391,7 +474,8 @@ class Dartdoc {
   void _document(Compilation compilation) {
     // Sort the libraries by name (not key).
     _sortedLibraries = new List<LibraryMirror>.from(
-        compilation.mirrors().libraries().getValues().filter(includeLibrary));
+        compilation.mirrors().libraries().getValues().filter(
+            shouldIncludeLibrary));
     _sortedLibraries.sort((x, y) {
       return x.simpleName().toUpperCase().compareTo(
           y.simpleName().toUpperCase());
@@ -1281,7 +1365,9 @@ class Dartdoc {
     assert(type is InterfaceMirror);
 
     // Link to the type.
-    if (includeLibrary(type.library())) {
+    if (shouldLinkToPublicApi(type.library())) {
+      write('<a href="$API_LOCATION${typeUrl(type)}">${type.simpleName()}</a>');
+    } else if (shouldIncludeLibrary(type.library())) {
       write(a(typeUrl(type), type.simpleName()));
     } else {
       write(type.simpleName());