Move doc generator out of frog samples.

utils/dartdoc/dartdoc.dart

 // Copyright (c) 2011, 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.
 
-// TODO(rnystrom): This is moving from a sample to being a real project. Right
-// now, to try this out:
-// 1. Compile interact.dart to JS:
-//    $ ./frogsh --out=docs/interact.js --compile-only docs/interact.dart
-// 2. Run the doc generator:
-//    $ ./frogsh samples/doc.dart
-// 3. Look at the results in frog/docs/
+/** An awesome documentation generator. */
+#library('dartdoc');
 
-/** An awesome documentation generator. */
-#library('doc');
+#import('../../frog/lang.dart');
+#import('../../frog/file_system_node.dart');
 
-#import('../lang.dart');
-#import('../file_system_node.dart');
-#import('classify.dart');
-
-/** Path to starting library or application. */
-// TODO(rnystrom): Make this a command-line arg.
-final libPath = 'samples/doc.dart';
+#source('classify.dart');
 
 /** Path to corePath library. */
 final corePath = 'lib';
 
 /** Path to generate html files into. */
-final outdir = './docs';
+final outdir = 'docs';
 
 /** Special comment position used to store the library-level doc comment. */
 final _libraryDoc = -1;
 
 /** The file currently being written to. */
 StringBuffer _file;
 
 /**
  * The cached lookup-table to associate doc comments with spans. The outer map
  * is from filenames to doc comments in that file. The inner map maps from the
  * token positions to doc comments. Each position is the starting offset of the
  * next non-comment token *following* the doc comment. For example, the position
  * for this comment would be the position of the "Map" token below.
  */
 Map<String, Map<int, String>> _comments;
 
-// TODO(jimhug): This generates really ugly output with lots of holes.

[Jennifer Messerly, 2011/11/11 02:29:58]

haha. yes, that TODO is very obsolete :)

[jimhug, 2011/11/11 18:02:31]

Whoo hoo!

[Bob Nystrom, 2011/11/11 18:21:28]

:D

Still need private members, but almost everything else is there now.

+int _totalLibraries = 0;
+int _totalTypes = 0;
+int _totalMembers = 0;
 
 /**
  * Run this from the frog/samples directory.  Before running, you need
  * to create a docs dir with 'mkdir docs' - since Dart currently doesn't
  * support creating new directories.
  */
 void main() {
+  // The entrypoint of the library to generate docs for.
+  final libPath = process.argv[2];
+
   // TODO(rnystrom): Get options and homedir like frog.dart does.
   final files = new NodeFileSystem();
-  parseOptions('.', [] /* args */, files);
+  parseOptions('../../frog', [] /* args */, files);
 
-  initializeWorld(files);
+  final elapsed = time(() {
+    initializeWorld(files);
 
-  world.withTiming('parsed', () {
     world.processScript(libPath);
-  });
+    world.resolveAll();
 
-  world.withTiming('resolved', () {
-    world.resolveAll();
-  });
-
-  world.withTiming('generated docs', () {
     _comments = <String, Map<int, String>>{};
 
     for (var library in world.libraries.getValues()) {
       docLibrary(library);
     }
 
     docIndex(world.libraries.getValues());
   });
+
+  print('Documented $_totalLibraries libraries, $_totalTypes types, and ' +
+        '$_totalMembers members in ${elapsed}msec.');

[jimhug, 2011/11/11 18:02:31]

Nice reporting code.

[Bob Nystrom, 2011/11/11 18:21:28]

Thanks! I was using withTiming() before but that doesn't actually output
anything because I'm not enabling info messages. This seemed like a more direct
solution.

+}
+
+num time(callback()) {
+  // Unlike world.withTiming, returns the elapsed time.
+  final watch = new StopWatch();
+  watch.start();
+  callback();
+  watch.stop();
+  return watch.elapsedInMs();
 }
 
 startFile() {
   _file = new StringBuffer();
 }
 
 write(String s) {
   _file.add(s);
 }
 
@@ skipping 40 matching lines @@
       '''
       </ul>
       </div>
       </body></html>
       ''');
 
   endFile('$outdir/index.html');
 }
 
 docLibrary(Library library) {
+  _totalLibraries++;
+
   startFile();
   writeln(
       '''
       <html>
       <head>
       <title>${library.name}</title>
       <link rel="stylesheet" type="text/css" href="styles.css" />
       <link href="http://fonts.googleapis.com/css?family=Open+Sans:400,600,700,800" rel="stylesheet" type="text/css">
       <script src="interact.js"></script>
       </head>
       <body>
       <div class="content">
       <h1>Library <strong>${library.name}</strong></h1>
       ''');
 
   bool needsSeparator = false;
 
   // Look for a comment for the entire library.
   final comment = findCommentInFile(library.baseSource, _libraryDoc);
   if (comment != null) {
     writeln('<div class="doc"><p>$comment</p></div>');
     needsSeparator = true;
   }
 
   for (var type in library.types.getValues()) {
     if (needsSeparator) writeln('<hr/>');
-    if (docType(type)) needsSeparator = false;
+    if (docType(type)) needsSeparator = true;
   }
 
   writeln(
       '''
       </div>
       </body></html>
       ''');
 
   endFile('$outdir/${sanitize(library.name)}.html');
 }
 
 /**
  * Documents [Type]. Handles top-level members if given an unnamed Type.
  * Returns [:true:] if it wrote anything.
  */
 bool docType(Type type) {
+  _totalTypes++;
+
   bool wroteSomething = false;
 
   if (type.name != null) {
     write(
         '''
         <h2 id="${type.name}">
           ${type.isClass ? "Class" : "Interface"} <strong>${type.name}</strong>
           <a class="anchor-link" href="#${type.name}"
               title="Permalink to ${type.name}">#</a>
         </h2>
@@ skipping 90 matching lines @@
     }
   }
 }
 
 /**
  * Documents the [method] in a type named [typeName]. Handles all kinds of
  * methods including getters, setters, and constructors.
  */
 docMethod(String typeName, MethodMember method,
     [String namedConstructor = null]) {
+  _totalMembers++;
+
   writeln(
       '''
       <div class="method"><h4 id="$typeName.${method.name}">
         <span class="show-code">Code</span>
       ''');
 
   // A null typeName means it's a top-level definition which is implicitly
   // static so doesn't need to annotate it.
   if (method.isStatic && (typeName != null)) {
     write('static ');
@@ skipping 46 matching lines @@
             title="Permalink to $typeName.$name">#</a>''');
   writeln('</h4>');
 
   docCode(method.span, showCode: true);
 
   writeln('</div>');
 }
 
 /** Documents the field [field] in a type named [typeName]. */
 docField(String typeName, FieldMember field) {
+  _totalMembers++;
+
   writeln(
       '''
       <div class="field"><h4 id="$typeName.${field.name}">
         <span class="show-code">Code</span>
       ''');
 
   // A null typeName means it's a top-level definition which is implicitly
   // static so doesn't need to annotate it.
   if (field.isStatic && (typeName != null)) {
     write('static ');
@@ skipping 168 matching lines @@
     if (line.endsWith('*/')) line = line.substring(0, line.length-2);
     line = line.trim();
     while (line.startsWith('*')) line = line.substring(1, line.length);
     line = line.trim();
     buf.add(line);
     buf.add(' ');
   }
 
   return buf.toString();
 }