Create separate HTML pages for each type.

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.
 
 /**
  * To use it, from this directory, run:
  *
  *     $ dartdoc <path to .dart file>
  *
- * This will create a "docs" directory with the docs for your libraries. To do
- * so, dartdoc parses that library and every library it imports. From each
- * library, it parses all classes and members, finds the associated doc
- * comments and builds crosslinked docs from them.
+ * This will create a "docs" directory with the docs for your libraries. The
+ * easiest way to preview your generated docs is to spin up a little web
+ * server, like:
+ *
+ *     $ python -m SimpleHTTPServer
+ *
+ * Then point your browser at `localhost:8000` to see your magnificent creation.

[sethladd, 2011/12/01 04:50:33]

Probably don't need this anymore.

[Bob Nystrom, 2011/12/02 19:40:55]

Done.

+ *
+ * To make beatiful docs from your library, dartdoc parses it and every library

[pquitslund, 2011/12/01 23:29:54]

beatiful -> beautiful

[Bob Nystrom, 2011/12/02 19:40:55]

Done.

+ * 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('../../frog/lang.dart');
 #import('../../frog/file_system.dart');
 #import('../../frog/file_system_node.dart');
 #import('../markdown/lib.dart', prefix: 'md');
 
 #source('classify.dart');
 
 /** Path to corePath library. */
 final corePath = 'lib';
 
 /** Path to generate html files into. */
 final outdir = 'docs';
 
 /** Set to `true` to include the source code in the generated docs. */
 bool includeSource = true;
 
 /** Special comment position used to store the library-level doc comment. */
 final _libraryDoc = -1;
 
+/** The path to the file currently being written to, relative to [outdir]. */
+String _filePath;
+
 /** The file currently being written to. */
 StringBuffer _file;
 
 /** The library that we're currently generating docs for. */
 Library _currentLibrary;
 
 /** The type that we're currently generating docs for. */
 Type _currentType;
 
 /** The member that we're currently generating docs for. */
@@ skipping 14 matching lines @@
 
 FileSystem files;
 
 /**
  * Run this from the `utils/dartdoc` directory.
  */
 void main() {
   // The entrypoint of the library to generate docs for.
   final libPath = process.argv[2];
 
+  // Parse the dartdoc options.
+  for (int i = 3; i < process.argv.length; i++) {
+    final arg = process.argv[i];
+    switch (arg) {
+      case '--no-code':
+        includeSource = false;
+        break;
+
+      default:
+        print('Unknown option: $arg');
+    }
+  }
+
   files = new NodeFileSystem();
   parseOptions('../../frog', [] /* args */, files);
 
   // 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(resolveNameReference);
 
@@ skipping 40 matching lines @@
 
 num time(callback()) {
   // Unlike world.withTiming, returns the elapsed time.
   final watch = new Stopwatch();
   watch.start();
   callback();
   watch.stop();
   return watch.elapsedInMs();
 }
 
-startFile() {
+startFile(String path) {
+  _filePath = path;
   _file = new StringBuffer();
 }
 
 write(String s) {
   _file.add(s);
 }
 
 writeln(String s) {
   write(s);
   write('\n');
 }
 
-endFile(String outfile) {
-  world.files.writeString(outfile, _file.toString());
+endFile() {
+  String outPath = '$outdir/$_filePath';
+  files.createDirectory(dirname(outPath), recursive: true);
+
+  world.files.writeString(outPath, _file.toString());
+  _filePath = null;
   _file = null;
 }
 
 /** Turns a library name into something that's safe to use as a file name. */
 sanitize(String name) => name.replaceAll(':', '_').replaceAll('/', '_');
 
 docIndex(List<Library> libraries) {
-  startFile();
+  startFile('index.html');
   // TODO(rnystrom): Need to figure out what this should look like.
   writeln(
       '''
       <html><head>
       <title>Index</title>
       <link rel="stylesheet" type="text/css" href="styles.css" />
       </head>
       <body>
       <div class="content">
       <ul>
       ''');
 
   final sorted = new List<Library>.from(libraries);
   sorted.sort((a, b) => a.name.compareTo(b.name));
 
   for (final library in sorted) {
     writeln(
         '''
-        <li><a href="${libraryUrl(library)}">Library ${library.name}</a></li>
+        <li>${a(libraryUrl(library), "Library ${library.name}")}</li>

[pquitslund, 2011/12/01 23:29:54]

Aside: love that you extracted this method here.

[Bob Nystrom, 2011/12/02 19:40:55]

Yeah, over time I suspect dartdoc will end up with a bunch of functions that
almost become an HTML DSL. But at the very least this was needed to handle
correct relative paths.

         ''');
   }
 
   writeln(
       '''
       </ul>
       </div>
       </body></html>
       ''');
 
-  endFile('$outdir/index.html');
+  endFile();
+}
+
+/** Returs the number of times [needle] occurs in [haystack]. */

[sethladd, 2011/12/01 04:50:33]

typo

[Bob Nystrom, 2011/12/02 19:40:55]

Done.

+int countOccurrences(String haystack, String needle) {

[Siggi Cherem (dart-lang), 2011/12/02 16:50:26]

nit: haystack, needle sound strange to me for this functionality (the phrase
makes me think there should be only 1 needle in a haystack :)). other ideas:
body+text, or text+segment

[Bob Nystrom, 2011/12/02 19:40:55]

Done: text/search.

+  int start = 0;
+  int count = 0;
+
+  while (true) {
+    start = haystack.indexOf(needle, start);
+    if (start == -1) break;
+    count++;
+    // Offsetting by needle length means overlapping needles are not counted.
+    start += needle.length;
+  }
+
+  return count;
+}
+
+/** Repeats [text] [count] times, separated by [separator] if given. */
+String repeat(String text, int count, [String separator]) {
+  // TODO(rnystrom): Should be in stdlib.

[Siggi Cherem (dart-lang), 2011/12/02 16:50:26]

nit: stdlib -> corelib

[Bob Nystrom, 2011/12/02 19:40:55]

Done.

+  final buffer = new StringBuffer();
+  for (int i = 0; i < count; i++) {
+    buffer.add(text);
+    if ((i < count - 1) && (separator !== null)) buffer.add(separator);
+  }
+
+  return buffer.toString();
+}
+
+/**
+ * Converts [absolute] which is understood to be a full path from the root of
+ * the generated docs to one relative to the current file.
+ */
+String relativePath(String absolute) {
+  // TODO(rnystrom): Walks all the way up to root each time. Shouldn't do this
+  // if the paths overlap.
+  return repeat('../', countOccurrences(_filePath, '/')) + absolute;
+}
+
+/**
+ * Creates a hyperlink. Handles turning the [href] into an appropriate relative
+ * path from the current file.
+ */
+String a(String href, String contents, [String class]) {
+  final css = class == null ? '' : ' class="$class"';
+  return '<a href="${relativePath(href)}"$css>$contents</a>';
+}
+
+writeHeader(String title) {
+  writeln(
+      '''

[sethladd, 2011/12/01 04:50:33]

let's get totally nerdy and put <!DOCTYPE html> here

[Bob Nystrom, 2011/12/02 19:40:55]

Classy!

+      <html>
+      <head>

[sethladd, 2011/12/01 04:50:33]

<meta charset="utf-8"> if you are utf-8

[Bob Nystrom, 2011/12/02 19:40:55]

Done.

+      <title>$title</title>
+      <link rel="stylesheet" type="text/css"
+          href="${relativePath('styles.css')}" />
+      <link href="http://fonts.googleapis.com/css?family=Open+Sans:400,600,700,800" rel="stylesheet" type="text/css">
+      <script src="${relativePath('interact.js')}"></script>

[sethladd, 2011/12/01 04:50:33]

is there a way to insert an Analytics code here? important for production
builds. maybe as an option?

[Bob Nystrom, 2011/12/02 19:40:55]

I plan to make dartdoc more extensible so that you can inject additional markup
into what it generates. We'll need that for automatically crosslinking between
dart:dom and dart:html. We can also let you insert stuff in the header like
this.

I'll add a todo for myself to do this in a later patch.

+      </head>
+      <body>
+      <div class="content">
+      ''');
+}
+
+writeFooter() {
+  writeln(
+      '''
+      </div>
+      </body></html>
+      ''');
 }
 
 docLibrary(Library library) {
   _totalLibraries++;
   _currentLibrary = library;
 
-  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;
+  startFile(libraryUrl(library));
+  writeHeader(library.name);
+  writeln('<h1>Library <strong>${library.name}</strong></h1>');
 
   // Look for a comment for the entire library.
   final comment = findCommentInFile(library.baseSource, _libraryDoc);
   if (comment != null) {
     final html = md.markdownToHtml(comment);
     writeln('<div class="doc">$html</div>');
-    needsSeparator = true;
   }
 
+  // Document the top-level members.
+  docMembers(library.topType);
+
+  // TODO(rnystrom): Link to types.
+  writeln('<h3>Types</h3>');
+
   for (final type in orderValuesByKeys(library.types)) {
-    // Skip private types (for now at least).
-    if ((type.name != null) && type.name.startsWith('_')) continue;
-
-    if (needsSeparator) writeln('<hr/>');
-    if (docType(type)) needsSeparator = true;
+    if (type.isTop) continue;
+    writeln(
+        '''
+        <div class="type">
+        <h4>

[sethladd, 2011/12/01 04:50:33]

why not apply the class="type" to the h4? then we can remove the <div>

[Bob Nystrom, 2011/12/02 19:40:55]

It's consistent with the markup we use for members. The div isn't necessary now,
but at some point I'd like to include one-sentence summaries for each type, and
those <p> will go inside this <div>. When it does that, it will probably
highlight on rollover like members do.

+          ${type.isClass ? "class" : "interface"}
+          ${a(typeUrl(type), "<strong>${type.name}</strong>")}
+        </h4>
+        </div>
+        ''');
   }
 
-  writeln(
-      '''
-      </div>
-      </body></html>
-      ''');
+  writeFooter();
+  endFile();
 
-  endFile('$outdir/${sanitize(library.name)}.html');
+  for (final type in library.types.getValues()) {
+    if (!type.isTop) docType(type);
+  }
 }
 
-/**
- * Documents [type]. Handles top-level members if given an unnamed Type.
- * Returns `true` if it wrote anything.
- */
-bool docType(Type type) {
+docType(Type type) {
   _totalTypes++;
   _currentType = type;
 
-  bool wroteSomething = false;
+  startFile(typeUrl(type));
 
-  if (type.name != null) {
-    final name = typeName(type);
+  final typeName = '${type.isClass ? "Class" : "Interface"} ${type.name}';
+  writeHeader('Library ${type.library.name} / $typeName');
+  writeln(
+      '''
+      <h1>${a(libraryUrl(type.library),
+            "Library <strong>${type.library.name}</strong>")}</h1>
+      <h2>${type.isClass ? "Class" : "Interface"}
+          <strong>${type.name}</strong></h2>
+      ''');
 
-    write(
-        '''
-        <h2 id="${typeAnchor(type)}">
-          ${type.isClass ? "Class" : "Interface"} <strong>$name</strong>
-          <a class="anchor-link" href="${typeUrl(type)}"
-              title="Permalink to $name">#</a>
-        </h2>
-        ''');
+  docInheritance(type);
+  docCode(type.span);
+  docConstructors(type);
+  docMembers(type);
 
-    docInheritance(type);
-    docCode(type.span);
-    docConstructors(type);
+  writeFooter();
+  endFile();
+}
 
-    wroteSomething = true;
-  }
-
+void docMembers(Type type) {
   // Collect the different kinds of members.
   final methods = [];
   final fields = [];
 
   for (final member in orderValuesByKeys(type.members)) {
-    if (member.isMethod &&
-        (member.definition != null) &&
-        !member.name.startsWith('_')) {
-      methods.add(member);
-    } else if (member.isProperty) {
+    if (member.name.startsWith('_')) continue;
+
+    if (member.isProperty) {
       if (member.canGet) methods.add(member.getter);
       if (member.canSet) methods.add(member.setter);
-    } else if (member.isField && !member.name.startsWith('_')) {
+    } else if (member.isMethod) {
+      methods.add(member);
+    } else if (member.isField) {
       fields.add(member);
     }
   }
 
   if (methods.length > 0) {
     writeln('<h3>Methods</h3>');
     for (final method in methods) docMethod(type, method);
   }
 
   if (fields.length > 0) {
     writeln('<h3>Fields</h3>');
     for (final field in fields) docField(type, field);
   }
-
-  return wroteSomething || methods.length > 0 || fields.length > 0;
 }
 
 /** Document the superclass and superinterfaces of [Type]. */
 docInheritance(Type type) {
   // Show the superclass and superinterface(s).
   final isSubclass = (type.parent != null) && !type.parent.isObject;
 
   if (isSubclass || (type.interfaces != null && type.interfaces.length > 0)) {
     writeln('<p>');
 
@@ skipping 129 matching lines @@
   if (field.isFinal) {
     write('final ');
   } else if (field.type.name == 'Dynamic') {
     write('var ');
   }
 
   write(annotation(type, field.type));
   write(
       '''
       <strong>${field.name}</strong> <a class="anchor-link"
-          href="#${memberUrl(field)}"
+          href="#${memberAnchor(field)}"
           title="Permalink to ${type.name}.${field.name}">#</a>
       </h4>
       ''');
 
   docCode(field.span, showCode: true);
   writeln('</div>');
 }
 
 /** Generates a human-friendly string representation for a type. */
 typeName(Type type) {
   // See if it's a generic type.
   if (type.isGeneric) {
     final typeParams = type.genericType.typeParameters;
     final params = Strings.join(map(typeParams, (p) => p.name), ', ');
     return '${type.name}&lt;$params&gt;';
   }
 
   // See if it's an instantiation of a generic type.
   final typeArgs = type.typeArgsInOrder;
   if (typeArgs != null) {
     final args = Strings.join(map(typeArgs, typeName), ', ');
     return '${type.genericType.name}&lt;$args&gt;';
   }
 
   // Regular type.
   return type.name;
 }
 
 /** Gets the URL to the documentation for [library]. */
-libraryUrl(Library library) => '${sanitize(library.name)}.html';
+libraryUrl(Library library) {
+  return '${sanitize(library.name)}.html';
+}
 
 /** Gets the URL for the documentation for [type]. */
-typeUrl(Type type) => '${libraryUrl(type.library)}#${typeAnchor(type)}';
+typeUrl(Type type) {
+  // Always get the generic type to strip off any type parameters or arguments.
+  // If the type isn't generic, genericType returns `this`, so it works for
+  // non-generic types too.
+  return '${sanitize(type.library.name)}/${type.genericType.name}.html';
+}
 
 /** Gets the URL for the documentation for [member]. */
-memberUrl(Member member) => '${typeUrl(member.declaringType)}-${member.name}';
-
-/** Gets the anchor id for the document for [type]. */
-typeAnchor(Type type) {
-  var name = type.name;
-
-  // No name for the special type that contains top-level members.
-  if (type.isTop) return '';
-
-  // Remove any type args or params that have been mangled into the name.
-  var dollar = name.indexOf('\$', 0);
-  if (dollar != -1) name = name.substring(0, dollar);
-
-  return name;
+memberUrl(Member member) {
+  return '${typeUrl(member.declaringType)}#${member.name}';
 }
 
 /** Gets the anchor id for the document for [member]. */
-memberAnchor(Member member) {
-  return '${typeAnchor(member.declaringType)}-${member.name}';
-}
+memberAnchor(Member member) => '${member.name}';
 
 /** Writes a linked cross reference to [type]. */
 typeReference(Type type) {
   // TODO(rnystrom): Do we need to handle ParameterTypes here like
   // annotation() does?
-  return '<a href="${typeUrl(type)}" class="crossref">${typeName(type)}</a>';
+  return a(typeUrl(type), typeName(type), class: 'crossref');
 }
 
 /**
  * Creates a linked string for an optional type annotation. Returns an empty
  * string if the type is Dynamic.
  */
 annotation(Type enclosingType, Type type) {
   if (type.name == 'Dynamic') return '';
 
   // If we're using a type parameter within the body of a generic class then
   // just link back up to the class.
   if (type is ParameterType) {
-    final library = sanitize(enclosingType.library.name);
-    return '<a href="${typeUrl(enclosingType)}">${type.name}</a> ';
+    return '${a(typeUrl(enclosingType), type.name)} ';
   }
 
   // Link to the type.
-  return '<a href="${typeUrl(type)}">${typeName(type)}</a> ';
+  return '${a(typeUrl(type), typeName(type))} ';
 }
 
 /**
  * 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) {
-  if (_currentMember != null) {
-    // See if it's a parameter of the current method.
-    for (final parameter in _currentMember.parameters) {
-      if (parameter.name == name) {
-        final element = new md.Element.text('span', name);
-        element.attributes['class'] = 'param';
-        return element;
-      }
-    }
-  }
-
   makeLink(String href) {
     final anchor = new md.Element.text('a', name);
-    anchor.attributes['href'] = href;
+    anchor.attributes['href'] = relativePath(href);
     anchor.attributes['class'] = 'crossref';
     return anchor;
   }
 
   findMember(Type type) {
     final member = type.members[name];
     if (member == null) return null;
 
     // Special case: if the member we've resolved is a property (i.e. it wraps
     // a getter and/or setter then *that* member itself won't be on the docs,
     // just the getter or setter will be. So pick one of those to link to.
     if (member.isProperty) {
       return member.canGet ? member.getter : member.setter;
     }
 
     return member;
   }
 
+  // See if it's a parameter of the current method.
+  if (_currentMember != null) {
+    for (final parameter in _currentMember.parameters) {
+      if (parameter.name == 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 (_currentType != null) {
     final member = findMember(_currentType);
     if (member != null) {
       return makeLink(memberUrl(member));
     }
   }
 
   // See if it's another type in the current library.
   if (_currentLibrary != null) {
@@ skipping 150 matching lines @@
     } else if (line.startsWith('*')) {
       line = line.substring(1, line.length);
     }
 
     buf.add(line);
     buf.add('\n');
   }
 
   return buf.toString();
 }