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..86e4a2f8236d8ad41cf71c79f92bd977047e68f2 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++) {
+  List<Path> entrypoints = new List<Path>();

[Bob Nystrom, 2012/07/23 17:04:31]

final entrypoints = <Path>[];

[Johnni Winther, 2012/07/24 08:49:16]

Done.

+
+  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;

[Bob Nystrom, 2012/07/23 17:04:31]

Should be "includeApi".

[Johnni Winther, 2012/07/24 08:49:16]

Done.

+        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.includeLibraries =
+              arg.substring('--include-lib='.length).split(',');
+        } else if (arg.startsWith('--exclude-lib=')) {
+          dartdoc.excludeLibraries =
+              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 link to the online API. */

[floitsch, 2012/07/23 10:43:56]

links

[Johnni Winther, 2012/07/24 08:49:16]

Done.

+  bool linkToApi = false;
+
+  /** Set this to select the libraries to include in the documentation */

[floitsch, 2012/07/23 10:43:56]

documentation.

[Johnni Winther, 2012/07/24 08:49:16]

Done.

+  List<String> includeLibraries = null;

[floitsch, 2012/07/23 10:43:56]

Wouldn't it be easier, if you initialized this with the empty list?

[Bob Nystrom, 2012/07/23 17:04:31]

+1.

Also, I would name it "includedLibraries", or, better, just "libraries". Field
names should be noun phrases.

[Johnni Winther, 2012/07/24 08:49:16]

Done.

[Johnni Winther, 2012/07/24 08:49:16]

Done.

+
+  /** Set this to select the libraries to exclude from the documentation */

[floitsch, 2012/07/23 10:43:56]

documentation.

[Johnni Winther, 2012/07/24 08:49:16]

Done.

+  List<String> excludeLibraries = null;

[floitsch, 2012/07/23 10:43:56]

ditto (empty list).

[Bob Nystrom, 2012/07/23 17:04:31]

"excludedLibraries"

[Johnni Winther, 2012/07/24 08:49:16]

Done.

[Johnni Winther, 2012/07/24 08:49:16]

Done.

 
   /**
    * This list contains the libraries sorted in by the library name.
@@ -354,12 +398,44 @@ class Dartdoc {
   }
 
   bool includeLibrary(LibraryMirror library) {

[floitsch, 2012/07/23 10:43:56]

not a boolean name.
shouldIncludeLibrary?

[Bob Nystrom, 2012/07/23 17:04:31]

+1. Also, needs a doc comment.

-    if (libraries != null) {
-      return libraries.indexOf(library.simpleName()) != -1;
+    if (linkLibrary(library)) {

[Bob Nystrom, 2012/07/23 17:04:31]

It's up to you, but if you like, the style guide does allow for single line ifs
for cases like this:

if (linkLibrary(library)) return false;

+      return false;
+    }
+    String libraryName = library.simpleName();
+    if (includeLibraries != null) {
+      if (includeLibraries.indexOf(libraryName) != -1) {
+        return true;
+      }
+    }
+    if (excludeLibraries != null) {
+      if (excludeLibraries.indexOf(libraryName) != -1) {
+        return false;
+      }
+    }
+    if (libraryName.startsWith('dart:')) {
+      String suffix = libraryName.substring('dart:'.length);

[floitsch, 2012/07/23 10:43:56]

This code is duplicated here and below. Maybe create a method?

[Johnni Winther, 2012/07/24 08:49:16]

They are slightly different.

+      LibraryInfo info = DART2JS_LIBRARY_MAP[suffix];
+      if (info != null) {
+        return !info.internal && includeAPI;
+      }
     }
     return true;
   }
 
+  bool linkLibrary(LibraryMirror library) {

[floitsch, 2012/07/23 10:43:56]

that's not a boolean name.
shouldLinkToPublicApi ?

[Johnni Winther, 2012/07/24 08:49:16]

Done.

+    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.internal;
+        }
+      }
+    }
+    return false;
+  }
+
   String get footerContent(){
     var footerItems = [];
     if(!omitGenerationTime) {
@@ -1281,7 +1357,9 @@ class Dartdoc {
     assert(type is InterfaceMirror);
 
     // Link to the type.
-    if (includeLibrary(type.library())) {
+    if (linkLibrary(type.library())) {
+      write('<a href="$API_LOCATION${typeUrl(type)}">${type.simpleName()}</a>');
+    } else if (includeLibrary(type.library())) {
       write(a(typeUrl(type), type.simpleName()));
     } else {
       write(type.simpleName());