Several new features and improvements for dartdoc.

lib/dartdoc/dartdoc.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * To generate docs for a library, run this script with the path to an
  * entrypoint .dart file, like:
  *
  *     $ dart dartdoc.dart foo.dart
  *
  * This will create a "docs" directory with the docs for your libraries. To
  * create these beautiful docs, dartdoc parses your library and every library
  * it imports (recursively). From each library, it parses all classes and
  * members, finds the associated doc comments and builds crosslinked docs from
  * them.
  */
 #library('dartdoc');
 
 #import('dart:io');
 #import('dart:uri');
 #import('dart:json');
 #import('mirrors/mirrors.dart');
 #import('mirrors/mirrors_util.dart');
 #import('mirrors/dart2js_mirror.dart', prefix: 'dart2js');
 #import('classify.dart');
 #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');
 
 // TODO(johnniwinther): Note that [IN_SDK] gets initialized to true when this
 // file is modified by the SDK deployment script. If you change, be sure to test
 // that dartdoc still works when run from the built SDK directory.
 final bool IN_SDK = false;
 
 /**
@@ skipping 10 matching lines @@
  *
  * This dramatically reduces the generated size of the HTML since a large
  * fraction of each static page is just redundant navigation links.
  *
  * In this mode, the browser will do a XHR for nav.json which means that to
  * preview docs locally, you will need to enable requesting file:// links in
  * your browser or run a little local server like `python -m SimpleHTTPServer`.
  */
 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.');
     printUsage();
     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();
           return;
         }
         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';
   Future compiled = compileScript(
     scriptDir.append('client-$clientScript.dart'),
     dartdoc.outputDir.append('client-$clientScript.js'));
 
   Future filesCopied = copyDirectory(scriptDir.append('static'),
                                      dartdoc.outputDir);
 
   Futures.wait([compiled, filesCopied]).then((_) {
     print('Documented ${dartdoc._totalLibraries} libraries, '
           '${dartdoc._totalTypes} types, and '
           '${dartdoc._totalMembers} members.');
   });
 }
 
 void printUsage() {
   print('''
-Usage dartdoc [options] <entrypoint>
+Usage dartdoc [options] <entrypoint(s)>
 [options] include
  --no-code                   Do not include source code in the documentation.
 
  --mode=static               Generates completely static HTML containing
                              everything you need to browse the docs. The only
                              client side behavior is trivial stuff like syntax
                              highlighting code.
 
  --mode=live-nav             (default) Generated docs do not include baked HTML
                              navigation. Instead, a single `nav.json` file is
                              created and the appropriate navigation is generated
                              client-side by parsing that and building HTML.
                                 This dramatically reduces the generated size of
                              the HTML since a large fraction of each static page
                              is just redundant navigation links.
                                 In this mode, the browser will do a XHR for
                              nav.json which means that to preview docs locally,
                              you will need to enable requesting file:// links in
                              your browser or run a little local server like
                              `python -m SimpleHTTPServer`.
 
  --generate-app-cache        Generates the App Cache manifest file, enabling
                              offline doc viewing.
 
  --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.
 ''');
 }
 
 /**
  * Gets the full path to the directory containing the entrypoint of the current
  * script. In other words, if you invoked dartdoc, directly, it will be the
  * path to the directory containing `dartdoc.dart`. If you're running a script
  * that imports dartdoc, it will be the path to that script.
  */
@@ skipping 113 matching lines @@
 
   /** Set this to add content before the footer */
   String preFooterText = '';
 
   /** Set this to omit generation timestamp from output */
   bool omitGenerationTime = false;
 
   /** 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.
    */
   List<LibraryMirror> _sortedLibraries;
 
   CommentMap _comments;
 
   /** The library that we're currently generating docs for. */
   LibraryMirror _currentLibrary;
@@ skipping 19 matching lines @@
     // Patch in support for [:...:]-style code to the markdown parser.
     // TODO(rnystrom): Markdown already has syntax for this. Phase this out?
     md.InlineParser.syntaxes.insertRange(0, 1,
         new md.CodeSyntax(@'\[\:((?:.|\n)*?)\:\]'));
 
     md.setImplicitLinkResolver((name) => resolveNameReference(name,
             currentLibrary: _currentLibrary, currentType: _currentType,
             currentMember: _currentMember));
   }
 
   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) {
       footerItems.add("This page was generated at ${new Date.now()}");
     }
     if(footerText != null) {
       footerItems.add(footerText);
     }
     var content = '';
     for (int i = 0; i < footerItems.length; i++) {
@@ skipping 901 matching lines @@
     if (type.isTypeVariable) {
       // If we're using a type parameter within the body of a generic class then
       // just link back up to the class.
       write(a(typeUrl(enclosingType), type.simpleName()));
       return;
     }
 
     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());
     }
 
     if (type.isDeclaration) {
       // Avoid calling [:typeArguments():] on a declaration.
       return;
     }
 
@@ skipping 203 matching lines @@
   }
 
   /**
    * Returns [:true:] if [type] should be regarded as an exception.
    */
   bool isException(TypeMirror type) {
     return type.simpleName().endsWith('Exception');
   }
 }