Dartdoc and apidoc updated to use Path.

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/dart2js.dart', prefix: 'dart2js');
 #import('../compiler/implementation/scanner/scannerlib.dart',
         prefix: 'dart2js');
-#import('file_util.dart');
 
 #source('comment_map.dart');
 #source('utils.dart');
 
 /**
  * Generates completely static HTML containing everything you need to browse
  * the docs. The only client side behavior is trivial stuff like syntax
  * highlighting code.
  */
 final MODE_STATIC = 0;
@@ skipping 55 matching lines @@
 
       case '--omit-generation-time':
         omitGenerationTime = true;
         break;
       case '--verbose':
         verbose = true;
         break;
 
       default:
         if (arg.startsWith('--out=')) {
           outputDir = arg.substring('--out='.length);

[Bill Hesse, 2012/07/17 13:42:13]

Path?

[Johnni Winther, 2012/07/19 08:37:07]

The type of outputDir is changed to Path.

         } else {
           print('Unknown option: $arg');
           printUsage();
           return;
         }
         break;
     }
   }
 
   if (args.length == 0) {
     print('Provide at least one dart file to process.');

[Bill Hesse, 2012/07/17 13:42:13]

"exactly one file"?

[Johnni Winther, 2012/07/19 08:37:07]

Yes, currently. This is going to change soon. And the code is dead because of
the check around line 68.

     return;
   }
 
-  // TODO(rnystrom): Note that the following lines get munged by create-sdk to
-  // work with the SDK's different file layout. If you change, be sure to test
-  // that dartdoc still works when run from the built SDK directory.
-  final String libPath = joinPaths(scriptDir, '../');
-
-  // The entrypoint of the library to generate docs for.
-  // TODO(johnniwinther): Handle absolute/relative paths
-  final entrypoint = canonicalizePath(args[args.length - 1]);
+  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 (outputDir != null) dartdoc.outputDir = new Path.fromNative(outputDir);
   if (generateAppCache != null) dartdoc.generateAppCache = generateAppCache;
   if (omitGenerationTime != null) {
     dartdoc.omitGenerationTime = omitGenerationTime;
   }
   if (verbose != null) dartdoc.verbose = verbose;
 
   cleanOutputDirectory(dartdoc.outputDir);
 
   dartdoc.documentEntryPoint(entrypoint, libPath);
 
   // Compile the client-side code to JS.
   final clientScript = (dartdoc.mode == MODE_STATIC) ? 'static' : 'live-nav';
-  compileScript(
-    '$scriptDir/client-$clientScript.dart',
-    '${dartdoc.outputDir}/client-$clientScript.js');
+  Future compiled = compileScript(
+    scriptDir.append('client-$clientScript.dart'),
+    dartdoc.outputDir.append('client-$clientScript.js'));
 
-  final Future filesCopied = copyFiles('$scriptDir/static', dartdoc.outputDir);
+  Future filesCopied = copyFiles(scriptDir.append('static'), dartdoc.outputDir);
 
-  Futures.wait([filesCopied]).then((_) {
+  Futures.wait([compiled, filesCopied]).then((_) {

[Bill Hesse, 2012/07/17 13:42:13]

I should start using _ as my "ignore" argument.  Should this go in the style
guide?

[Johnni Winther, 2012/07/19 08:37:07]

I think so.

     print('Documented ${dartdoc._totalLibraries} libraries, '
           '${dartdoc._totalTypes} types, and '
           '${dartdoc._totalMembers} members.');
   });
 }
 
 void printUsage() {
   print('''
 Usage dartdoc [options] <entrypoint>
 [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 
+ --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 
+ --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 
+                                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, 
+                                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 
+                             your browser or run a little local server like
                              `python -m SimpleHTTPServer`.
 
- --generate-app-cache        Generates the App Cache manifest file, enabling 
+ --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/
 
  --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.
  */
-String get scriptDir() {
-  return dirname(new File(new Options().script).fullPathSync());
+Path get scriptDir() {

[Bill Hesse, 2012/07/17 13:42:13]

Lazy intialized statics work perfectly here, I think.  They are evaluated at
first use:

final Path scriptDir = new Path.fromNative(...
final Path libPath = scriptDir.append('../..');

[Johnni Winther, 2012/07/19 08:37:07]

This is not currently supported since current implementations require the
initializer to be a compile-time constant.

[Bill Hesse, 2012/07/19 13:36:19]

Can we write a TODO to fix this once they are supported?

+  return new Path.fromNative(new Options().script).directoryPath;
+}
+
+Path get libPath() {
+  // TODO(rnystrom): Note that the following lines get munged by create-sdk to
+  // work with the SDK's different file layout. If you change, be sure to test
+  // that dartdoc still works when run from the built SDK directory.
+  return scriptDir.append('../..');

[Bill Hesse, 2012/07/17 13:42:13]

Can't we have a const flag or enum, munged by the SDK, and do the right thing
based on that?  And then use .directoryPath.directoryPath?

[Johnni Winther, 2012/07/19 08:37:07]

Changed to use a bool IN_SDK flag.

 }
 
 /**
  * Deletes and recreates the output directory at [path] if it exists.
  */
-void cleanOutputDirectory(String path) {
-  final outputDir = new Directory(path);
+void cleanOutputDirectory(Path path) {
+  final outputDir = new Directory.fromPath(path);
   if (outputDir.existsSync()) {
     outputDir.deleteRecursivelySync();
   }
 
   try {
     // TODO(johnniwinther): Hack to avoid 'file already exists' exception thrown
     // due to invalid result from dir.existsSync() (probably due to race
     // conditions).

[Bill Hesse, 2012/07/17 13:42:13]

There is a bug for this - http://code.google.com/p/dart/issues/detail?id=3914.
Write TODO(3914):

[Johnni Winther, 2012/07/19 08:37:07]

Done.

     outputDir.createSync();
   } catch (DirectoryIOException e) {
     // Ignore.
   }
 }
 
 /**
  * Copies all of the files in the directory [from] to [to]. Does *not*
  * recursively copy subdirectories.
  *
  * Note: runs asynchronously, so you won't see any files copied until after the
  * event loop has had a chance to pump (i.e. after `main()` has returned).
  */
-Future copyFiles(String from, String to) {
+Future copyFiles(Path from, Path to) {

[Bill Hesse, 2012/07/17 13:42:13]

copyDirectory?

[Johnni Winther, 2012/07/19 08:37:07]

Done.

   final completer = new Completer();
-  final fromDir = new Directory(from);
+  final fromDir = new Directory.fromPath(from);
   final lister = fromDir.list(recursive: false);
 
-  lister.onFile = (path) {
-    final name = basename(path);
+  lister.onFile = (String path) {
+    final name = new Path.fromNative(path).filename;
     // TODO(rnystrom): Hackish. Ignore 'hidden' files like .DS_Store.
     if (name.startsWith('.')) return;
 
     new File(path).readAsBytes().then((bytes) {

[Bill Hesse, 2012/07/17 13:42:13]

Copying should work better with
File from;
File to;
from.openInputStream().pipe(to.openOutputStream());
They should close themselves and be freed automatically.

[Johnni Winther, 2012/07/19 08:37:07]

Done.

-      final outFile = new File('$to/$name');
+      final outFile = new File.fromPath(to.append(name));
       final stream = outFile.openOutputStream(FileMode.WRITE);
       stream.write(bytes, copyBuffer: false);
       stream.close();
     });
   };
   lister.onDone = (done) => completer.complete(true);
   return completer.future;
 }
 
 /**
  * Compiles the given Dart script to a JavaScript file at [jsPath] using the
  * Dart2js compiler.
  */
-void compileScript(String dartPath, String jsPath) {
-  dart2js.compile([
-      '--no-colors',
-      // TODO(johnniwinther): The following lines get munged by create-sdk to
-      // work with the SDK's different file layout. If you change, be sure to
-      // test that dartdoc still works when run from the built SDK directory.
-      '--library-root=${joinPaths(scriptDir, '../../')}',
-      '--out=$jsPath',
-      '--throw-on-error',
-      '--suppress-warnings',
-      dartPath]);
+Future<bool> compileScript(Path dartPath, Path jsPath) {
+  var completer = new Completer<bool>();
+  var compilation = new Compilation(dartPath, libPath);
+  Future<String> result = compilation.compileToJavaScript();
+  result.then((jsCode) {
+    writeString(new File.fromPath(jsPath), jsCode);
+    completer.complete(true);
+  });
+  result.handleException((e) => completer.completeException(e));
+  return completer.future;
 }
 
 class Dartdoc {
 
   /** Set to `false` to not include the source code in the generated docs. */
   bool includeSource = true;
 
   /**
    * Dartdoc can generate docs in a few different ways based on how dynamic you
    * want the client-side behavior to be. The value for this should be one of
    * the `MODE_` constants.
    */
   int mode = MODE_LIVE_NAV;
 
   /**
    * Generates the App Cache manifest file, enabling offline doc viewing.
    */
   bool generateAppCache = false;
 
   /** Path to generate HTML files into. */
-  String outputDir = 'docs';
+  Path outputDir = const Path('docs');
 
   /**
    * The title used for the overall generated output. Set this to change it.
    */
   String mainTitle = 'Dart Documentation';
 
   /**
    * The URL that the Dart logo links to. Defaults "index.html", the main
    * page for the generated docs, but can be anything.
    */
@@ skipping 33 matching lines @@
   /** The library that we're currently generating docs for. */
   LibraryMirror _currentLibrary;
 
   /** The type that we're currently generating docs for. */
   InterfaceMirror _currentType;
 
   /** The member that we're currently generating docs for. */
   MemberMirror _currentMember;
 
   /** The path to the file currently being written to, relative to [outdir]. */
   String _filePath;

[Bill Hesse, 2012/07/17 13:42:13]

Make this a Path object?

[Johnni Winther, 2012/07/19 08:37:07]

Done.

 
   /** The file currently being written to. */
   StringBuffer _file;
 
   int _totalLibraries = 0;
   int _totalTypes = 0;
   int _totalMembers = 0;
 
   Dartdoc()
     : _comments = new CommentMap() {
     // 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,
-            library: _currentLibrary, type: _currentType,
-            member: _currentMember));
+            currentLibrary: _currentLibrary, currentType: _currentType,
+            currentMember: _currentMember));
   }
 
   bool includeLibrary(LibraryMirror library) {
     if (libraries != null) {
       return libraries.indexOf(library.simpleName()) != -1;
     }
     return true;
   }
 
   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++) {
       if(i > 0){
         content = content.concat('\n');
       }
       content = content.concat('<div>${footerItems[i]}</div>');
     }
     return content;
   }
 
-  void documentEntryPoint(String entrypoint, String libPath) {
+  void documentEntryPoint(Path entrypoint, Path libPath) {
     final compilation = new Compilation(entrypoint, libPath);
     _document(compilation);
   }
 
-  void documentLibraries(List<String> libraries, String libPath) {
-    final compilation = new Compilation.library(libraries, libPath);
+  void documentLibraries(List<Path> libraryList, Path libPath) {
+    final compilation = new Compilation.library(libraryList, libPath);
     _document(compilation);
   }
 
   void _document(Compilation compilation) {
     // Sort the libraries by name (not key).
     _sortedLibraries = new List<LibraryMirror>.from(
         compilation.mirrors().libraries().getValues().filter(includeLibrary));
     _sortedLibraries.sort((x, y) {
       return x.simpleName().toUpperCase().compareTo(
           y.simpleName().toUpperCase());
     });
 
     // Generate the docs.
     if (mode == MODE_LIVE_NAV) docNavigationJson();
 
     docIndex();
     for (final library in _sortedLibraries) {
       docLibrary(library);
     }
 
     if (generateAppCache) {
       generateAppCacheManifest();
     }
   }
 
   void startFile(String path) {
     _filePath = path;

[Bill Hesse, 2012/07/17 13:42:13]

I see that it is convenient to have startFile take a string argument, but you
may as well convert it to a path here.

[Johnni Winther, 2012/07/19 08:37:07]

Done.

     _file = new StringBuffer();
   }
 
   void endFile() {
-    final outPath = '$outputDir/$_filePath';
-    final dir = new Directory(dirname(outPath));
+    final outPath = outputDir.join(new Path.fromNative(_filePath));
+    final dir = new Directory.fromPath(outPath.directoryPath);
     if (!dir.existsSync()) {
       // TODO(johnniwinther): Hack to avoid 'file already exists' exception

[Bill Hesse, 2012/07/17 13:42:13]

TODO(3914): There is a bug for this issue:
http://code.google.com/p/dart/issues/detail?id=3914

       // thrown due to invalid result from dir.existsSync() (probably due to
       // race conditions).
       try {
         dir.createSync();
       } catch (DirectoryIOException e) {
         // Ignore.
       }
     }
 
-    writeString(new File(outPath), _file.toString());
+    writeString(new File.fromPath(outPath), _file.toString());
     _filePath = null;
     _file = null;
   }
 
   void write(String s) {
     _file.add(s);
   }
 
   void writeln(String s) {
     write(s);
@@ skipping 140 matching lines @@
       docLibraryNavigationJson(library, libraryMap);
     }
 
     writeln(JSON.stringify(libraryMap));
     endFile();
   }
 
   void docLibraryNavigationJson(LibraryMirror library, Map libraryMap) {
     final types = [];
 
-    for (final type in orderByName(library.types().getValues())) {
+    for (InterfaceMirror type in orderByName(library.types().getValues())) {
       if (type.isPrivate) continue;
 
       final kind = type.isClass ? 'class' : 'interface';
       final url = typeUrl(type);
       types.add({ 'name': typeName(type), 'kind': kind, 'url': url });
     }
 
     libraryMap[library.simpleName()] = types;
   }
 
@@ skipping 21 matching lines @@
 
     writeln('</div>');
   }
 
   /** Writes the navigation for the types contained by the given library. */
   void docLibraryNavigation(LibraryMirror library) {
     // Show the exception types separately.
     final types = <InterfaceMirror>[];
     final exceptions = <InterfaceMirror>[];
 
-    for (final type in orderByName(library.types().getValues())) {
+    for (InterfaceMirror type in orderByName(library.types().getValues())) {
       if (type.isPrivate) continue;
 
       if (isException(type)) {
         exceptions.add(type);
       } else {
         types.add(type);
       }
     }
 
     if ((types.length == 0) && (exceptions.length == 0)) return;
@@ skipping 44 matching lines @@
     }
 
     // Document the top-level members.
     docMembers(library);
 
     // Document the types.
     final classes = <InterfaceMirror>[];
     final interfaces = <InterfaceMirror>[];
     final exceptions = <InterfaceMirror>[];
 
-    for (final type in orderByName(library.types().getValues())) {
+    for (InterfaceMirror type in orderByName(library.types().getValues())) {
       if (type.isPrivate) continue;
 
       if (isException(type)) {
         exceptions.add(type);
       } else if (type.isClass) {
         classes.add(type);
       } else {
         interfaces.add(type);
       }
     }
@@ skipping 229 matching lines @@
     }
   }
 
   void docMembers(ObjectMirror host) {
     // Collect the different kinds of members.
     final staticMethods = [];
     final staticFields = [];
     final instanceMethods = [];
     final instanceFields = [];
 
-    for (final member in orderByName(host.declaredMembers().getValues())) {
+    for (MemberMirror member in orderByName(host.declaredMembers().getValues())) {
       if (member.isPrivate) continue;
 
       final methods = member.isStatic ? staticMethods : instanceMethods;
       final fields = member.isStatic ? staticFields : instanceFields;
 
       if (member.isMethod) {
         methods.add(member);
       } else if (member.isField) {
         fields.add(member);
       }
@@ skipping 405 matching lines @@
     // Syntax highlight.
     return classifySource(code);
   }
 
   /**
    * This will be called whenever a doc comment hits a `[name]` in square
    * brackets. It will try to figure out what the name refers to and link or
    * style it appropriately.
    */
   md.Node resolveNameReference(String name,
-                               [MemberMirror member = null,
-                                ObjectMirror type = null,
-                                LibraryMirror library = null]) {
+                               [MemberMirror currentMember = null,
+                                ObjectMirror currentType = null,
+                                LibraryMirror currentLibrary = null]) {
     makeLink(String href) {
       final anchor = new md.Element.text('a', name);
       anchor.attributes['href'] = relativePath(href);
       anchor.attributes['class'] = 'crossref';
       return anchor;
     }
 
     // See if it's a parameter of the current method.
-    if (member is MethodMirror) {
-      for (final parameter in member.parameters()) {
+    if (currentMember is MethodMirror) {
+      for (final parameter in currentMember.parameters()) {
         if (parameter.simpleName() == name) {
           final element = new md.Element.text('span', name);
           element.attributes['class'] = 'param';
           return element;
         }
       }
     }
 
     // See if it's another member of the current type.
-    if (type != null) {
-      final member = findMirror(type.declaredMembers(), name);
-      if (member != null) {
-        return makeLink(memberUrl(member));
+    if (currentType != null) {
+      final foundMember = findMirror(currentType.declaredMembers(), name);
+      if (foundMember != null) {
+        return makeLink(memberUrl(foundMember));
       }
     }
 
     // See if it's another type or a member of another type in the current
     // library.
-    if (library != null) {
+    if (currentLibrary != null) {
       // See if it's a constructor
       final constructorLink = (() {
         final match =
             new RegExp(@'new ([\w$]+)(?:\.([\w$]+))?').firstMatch(name);
         if (match == null) return;
-        final type = findMirror(library.types(), match[1]);
-        if (type == null) return;
+        InterfaceMirror foundtype = findMirror(currentLibrary.types(), match[1]);
+        if (foundtype == null) return;
         final constructor =
-            findMirror(type.constructors(),
+            findMirror(foundtype.constructors(),
                             match[2] == null ? '' : match[2]);
         if (constructor == null) return;
         return makeLink(memberUrl(constructor));
       })();
       if (constructorLink != null) return constructorLink;
 
       // See if it's a member of another type
       final foreignMemberLink = (() {
         final match = new RegExp(@'([\w$]+)\.([\w$]+)').firstMatch(name);
         if (match == null) return;
-        final type = findMirror(library.types(), match[1]);
-        if (type == null) return;
-        final member = findMirror(type.declaredMembers(), match[2]);
-        if (member == null) return;
-        return makeLink(memberUrl(member));
+        InterfaceMirror foundtype = findMirror(currentLibrary.types(), match[1]);
+        if (foundtype == null) return;
+        MemberMirror foundMember = findMirror(foundtype.declaredMembers(), match[2]);
+        if (foundMember == null) return;
+        return makeLink(memberUrl(foundMember));
       })();
       if (foreignMemberLink != null) return foreignMemberLink;
 
-      final type = findMirror(library.types(), name);
-      if (type != null) {
-        return makeLink(typeUrl(type));
+      InterfaceMirror foundType = findMirror(currentLibrary.types(), name);
+      if (foundType != null) {
+        return makeLink(typeUrl(foundType));
       }
 
       // See if it's a top-level member in the current library.
-      final member = findMirror(library.declaredMembers(), name);
-      if (member != null) {
-        return makeLink(memberUrl(member));
+      MemberMirror foundMember = findMirror(currentLibrary.declaredMembers(), name);
+      if (foundMember != null) {
+        return makeLink(memberUrl(foundMember));
       }
     }
 
     // TODO(rnystrom): Should also consider:
     // * Names imported by libraries this library imports.
     // * Type parameters of the enclosing type.
 
     return new md.Element.text('code', name);
   }
 
   generateAppCacheManifest() {
     print('Generating app cache manifest from output $outputDir');
     startFile('appcache.manifest');
     write("CACHE MANIFEST\n\n");
     write("# VERSION: ${new Date.now()}\n\n");
     write("NETWORK:\n*\n\n");
     write("CACHE:\n");
-    var toCache = new Directory(outputDir);
-    var pathPrefix = new File(outputDir).fullPathSync();
+    var toCache = new Directory.fromPath(outputDir);
+    var pathPrefix = new File.fromPath(outputDir).fullPathSync();
     var pathPrefixLength = pathPrefix.length;
-    toCache.onFile = (filename) {
+    var toCacheLister = toCache.list(recursive: true);
+    toCacheLister.onFile = (filename) {
       if (filename.endsWith('appcache.manifest')) {
         return;
       }

[Bill Hesse, 2012/07/17 13:42:13]

var relativePath =
new Path.fromNative(filename).relativeTo(outputDir).toNativePath();
Or perhaps this is worse.
If directory listing returned paths, then it would be better.

[Johnni Winther, 2012/07/19 08:37:07]

Changed, but a lot of new issues arose. Check the comment in the new patch.

       var relativePath = filename.substring(pathPrefixLength + 1);
       write("$relativePath\n");
     };
-    toCache.onDone = (done) => endFile();
-    toCache.list(recursive: true);
+    toCacheLister.onDone = (done) => endFile();
   }
 
   /**
    * Returns [:true:] if [type] should be regarded as an exception.
    */
   bool isException(TypeMirror type) {
     return type.simpleName().endsWith('Exception');
   }
 }