Frog now called directly in 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:json');
 #import('../../frog/lang.dart');
 #import('../../frog/file_system.dart');
 #import('../../frog/file_system_vm.dart');
 #import('classify.dart');
 #import('markdown.dart', prefix: 'md');
+#import('../../frog/minfrogc.dart', prefix: 'frog');
 
 #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;
 
 /**
  * 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`.
  */
 final MODE_LIVE_NAV = 1;
 
+void printUsage() {

[kasperl, 2012/05/31 13:30:23]

I would consider moving printUsage down below main so it doesn't stick out so
much.

+  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 
+                             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.
+ --generate-app-cache=true   --''--   
+
+ --out=<dir>                 Generates files into directory <dir>. If omitted
+                             the files are generated into ./docs/
+''');
+}
+
 /**
  * Run this from the `lib/dartdoc` directory.
  */
 void main() {
   final args = new Options().arguments;
 
   // Parse the dartdoc options.
   bool includeSource;
   int mode;
   String outputDir;
   bool generateAppCache;
+  
+  if (args.length == 0) {

[kasperl, 2012/05/31 13:30:23]

args.isEmpty()?

+    print('No arguments provided.');
+    printUsage();
+    return;
+  }
 
   for (int i = 0; i < args.length - 1; i++) {
     final arg = args[i];
 
     switch (arg) {
       case '--no-code':
         includeSource = false;
         break;
 
       case '--mode=static':
         mode = MODE_STATIC;
         break;
 
       case '--mode=live-nav':
         mode = MODE_LIVE_NAV;
         break;
 
       case '--generate-app-cache':
       case '--generate-app-cache=true':
         generateAppCache = true;
         break;
 
       default:
         if (arg.startsWith('--out=')) {
           outputDir = arg.substring('--out='.length);
         } else {
           print('Unknown option: $arg');
+          printUsage();
           return;
         }
         break;
     }
   }
 
   // The entrypoint of the library to generate docs for.
   final entrypoint = args[args.length - 1];
 
   final files = new VMFileSystem();
 
   // 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 frogPath = joinPaths(scriptDir, '../../frog/');
   final libDir = joinPaths(frogPath, 'lib');
-  final compilerPath = joinPaths(frogPath, 'minfrog');
 
   parseOptions(frogPath, ['', '', '--libdir=$libDir'], files);
   initializeWorld(files);
 
   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;
 
   cleanOutputDirectory(dartdoc.outputDir);
 
   // Compile the client-side code to JS.
   final clientScript = (dartdoc.mode == MODE_STATIC) ? 'static' : 'live-nav';
-  final Future scriptCompiled = compileScript(compilerPath, libDir,
+  final Future scriptCompiled = compileScript(libDir,
                 '$scriptDir/client-$clientScript.dart',

[kasperl, 2012/05/31 13:30:23]

The indentation here seems off (not your fault). I think it would be
conventional to move libDir to a line of its own and use 4-space indent. Either:

  ..................... = bar(xxx,
                              yyy);

or:

  ..................... = bar(
      xxx,
      yyy);

or:

  ..................... = 
      bar(xxx, yyy);

Not sure if this is covered by http://www.dartlang.org/articles/style-guide/.

                 '${dartdoc.outputDir}/client-$clientScript.js');
 
   final Future filesCopied = copyFiles('$scriptDir/static', dartdoc.outputDir);
 
   Futures.wait([scriptCompiled, filesCopied]).then((_) {
     dartdoc.document(entrypoint);
+    
+    print('Documented ${dartdoc._totalLibraries} libraries, ' +

[ngeoffray, 2012/05/31 13:22:56]

You can remove the '+'s here, they're not needed, and the String+ feature will
soon disappear.

[kasperl, 2012/05/31 13:30:23]

We're deprecating using + for string concatenation. It should work just fine
without the pluses (adjacent string literals are automatically concatenated).

Also I would align the string literals under each other like this:

   print('.....'
         '............'
         '..');

+      '${dartdoc._totalTypes} types, and ' +
+      '${dartdoc._totalMembers} members.');
   });
 
-  print('Documented ${dartdoc._totalLibraries} libraries, ' +
-      '${dartdoc._totalTypes} types, and ' +
-      '${dartdoc._totalMembers} members.');
 }
 
 /**
  * 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());
 }
 
 /**
  * Deletes and recreates the output directory at [path] if it exists.
  */
 void cleanOutputDirectory(String path) {
   final outputDir = new Directory(path);
   if (outputDir.existsSync()) {
     outputDir.deleteRecursivelySync();
   }
 
-  outputDir.createSync();
+  try {
+    //TODO(johnniwinther) hack to avoid 'file already exists' exception thrown

[ngeoffray, 2012/05/31 13:22:56]

missing space before TODO

[kasperl, 2012/05/31 13:30:23]

Add a space before TODO and terminate the comment with . Personally, I also
prefer separating the TODO from the comment like this:

// TODO(kasperl): ...

+    // due to invalid result from dir.existsSync() (probably due to race
+    // conditions)
+    outputDir.createSync();
+  } catch (DirectoryIOException e) {
+    // ignore

[kasperl, 2012/05/31 13:30:23]

Start comments with uppercase and terminate with .

+    // print('$e: $path');

[ngeoffray, 2012/05/31 13:22:56]

Leftover debugging?

[kasperl, 2012/05/31 13:30:23]

We try to avoid code in comments.

+  }
 }
 
 /**
  * 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) {
@@ skipping 12 matching lines @@
       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
- * Dart-to-JS compiler located at [compilerPath].
+ * Frog compiler located.

[ngeoffray, 2012/05/31 13:22:56]

Remove located.

  */
-Future compileScript(String compilerPath, String libDir,
-    String dartPath, String jsPath) {
+Future compileScript(String libDir,
+                     String dartPath, String jsPath) {

[kasperl, 2012/05/31 13:30:23]

Would all the parameters fit on one line now?

   final completer = new Completer();
-  onExit(ProcessResult result) {
-    if (result.exitCode != 0) {
-      final message = 'Non-zero exit code from $compilerPath';
+  print('Compiling $dartPath to $jsPath');
+  
+  var result = true;
+  try {
+    result = frog.internalMain([ 
+      '--libdir=$libDir', '--out=$jsPath',

[kasperl, 2012/05/31 13:30:23]

4 space indent.

+      '--compile-only', '--enable-type-checks', '--warnings-as-errors',
+        dartPath]);
+    } catch (Object error) {

[ngeoffray, 2012/05/31 13:22:56]

strange indentation

[kasperl, 2012/05/31 13:30:23]

Indentation seems off. 

+      final message = 'Error trying to execute the compiler. Error: $error';
       print('$message.');

[ngeoffray, 2012/05/31 13:22:56]

Note that you can just write:
print(message)

The print method calls toString on the argument.

-      print(result.stdout);
-      print(result.stderr);
       throw message;

[kasperl, 2012/05/31 13:30:23]

This should probably be completer.completeException(message). 

     }
-    completer.complete(true);
-  }
-
-  onError(error) {
-    final message = 'Error trying to execute $compilerPath. Error: $error';
+  if (!result) {
+    final message = 'Non-zero exit code from the compiler';
     print('$message.');
     throw message;

[kasperl, 2012/05/31 13:30:23]

This should probably be completer.completeException(message). 

[kasperl, 2012/05/31 13:30:23]

This should probably be completer.completeException(message). 

   }
-
-  print('Compiling $dartPath to $jsPath');
-  var processFuture = Process.run(compilerPath, [
-    '--libdir=$libDir', '--out=$jsPath',
-    '--compile-only', '--enable-type-checks', '--warnings-as-errors',
-    dartPath]);
-
-  processFuture.handleException(onError);
-  processFuture.then(onExit);
+  completer.complete(result);
 
   return completer.future;
 }
 
 class Dartdoc {
 
   /** Set to `false` to not include the source code in the generated docs. */
   bool includeSource = true;
 
   /**
@@ skipping 116 matching lines @@
 
   void startFile(String path) {
     _filePath = path;
     _file = new StringBuffer();
   }
 
   void endFile() {
     final outPath = '$outputDir/$_filePath';
     final dir = new Directory(dirname(outPath));
     if (!dir.existsSync()) {
-      dir.createSync();
+      //TODO(johnniwinther) hack to avoid 'file already exists' exception thrown

[ngeoffray, 2012/05/31 13:22:56]

Space before TODO

[kasperl, 2012/05/31 13:30:23]

Space before TODO. Terminate comment with . Consider a colon after the TODO.

+      // due to invalid result from dir.existsSync() (probably due to race
+      // conditions)
+      try {
+        dir.createSync();
+      } catch (DirectoryIOException e) {
+        // ignore

[kasperl, 2012/05/31 13:30:23]

// Ignore.

+      }
     }
 
     world.files.writeString(outPath, _file.toString());
     _filePath = null;
     _file = null;
   }
 
   void write(String s) {
     _file.add(s);
   }
@@ skipping 983 matching lines @@
     toCache.onFile = (filename) {
       if (filename.endsWith('appcache.manifest')) {
         return;
       }
       var relativePath = filename.substring(pathPrefixLength + 1);
       write("$relativePath\n");
     };
     toCache.onDone = (done) => endFile();
     toCache.list(recursive: true);
   }
-}
+}