Integrate MDN content into API documentation.

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
  * 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:json');
 #import('../../frog/lang.dart');
 #import('../../frog/file_system.dart');
 #import('../../frog/file_system_node.dart');
 #import('../../frog/lib/node/node.dart');
 #import('classify.dart');
 #import('markdown.dart', prefix: 'md');
 
 #source('comment_map.dart');
-#source('files.dart');
 #source('utils.dart');
 
+/** Path to generate HTML files into. */
+final _outdir = 'docs';
+
 /**
  * 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
@@ skipping 86 matching lines @@
 
   /** 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. */
   Member _currentMember;
 
+  /** The path to the file currently being written to, relative to [outdir]. */
+  String _filePath;
+
+  /** 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)*?)\:\]'));
@@ skipping 46 matching lines @@
 
       docIndex();
       for (final library in world.libraries.getValues()) {
         docLibrary(library);
       }
     } finally {
       options.dietParse = oldDietParse;
     }
   }
 
+  startFile(String path) {
+    _filePath = path;
+    _file = new StringBuffer();
+  }
+
+  endFile() {
+    String outPath = '$_outdir/$_filePath';
+    world.files.createDirectory(dirname(outPath), recursive: true);
+
+    world.files.writeString(outPath, _file.toString());
+    _filePath = null;
+    _file = null;
+  }
+
+  write(String s) {
+    _file.add(s);
+  }
+
+  writeln(String s) {
+    write(s);
+    write('\n');
+  }
+
   /**
    * Writes the page header with the given [title] and [breadcrumbs]. The
    * breadcrumbs are an interleaved list of links and titles. If a link is null,
    * then no link will be generated. For example, given:
    *
    *     ['foo', 'foo.html', 'bar', null]
    *
    * It will output:
    *
    *     <a href="foo.html">foo</a> &rsaquo; bar
@@ skipping 271 matching lines @@
         '''
         <h2>${type.isClass ? "Class" : "Interface"}
             <strong>${typeName(type, showBounds: true)}</strong></h2>
         ''');
 
     docCode(type.span, getTypeComment(type));
     docInheritance(type);
     docConstructors(type);
     docMembers(type);
 
+    writeTypeFooter();
     writeFooter();
     endFile();
   }
 
+  /** Override this to write additional content at the end of a type's page. */
+  void writeTypeFooter() {
+    // Do nothing.
+  }
+
   /**
    * Writes an inline type span for the given type. This is a little box with
    * an icon and the type's name. It's similar to how types appear in the
    * navigation, but is suitable for inline (as opposed to in a `<ul>`) use.
    */
   typeSpan(Type type) {
     var icon = 'interface';
     if (type.name.endsWith('Exception')) {
       icon = 'exception';
     } else if (type.isClass) {
@@ skipping 192 matching lines @@
     var name = method.name;
     if (name.startsWith('get:')) {
       // Getter.
       name = 'get ${name.substring(4)}';
     } else if (name.startsWith('set:')) {
       // Setter.
       name = 'set ${name.substring(4)}';
     } else if (name == ':negate') {
       // Dart uses 'negate' for prefix negate operators, not '!'.
       name = 'operator negate';
+    } else if (name == ':call') {
+      name = 'operator call';
     } else {
       // See if it's an operator.
       name = TokenKind.rawOperatorFromMethod(name);
       if (name == null) {
         name = method.name;
       } else {
         name = 'operator $name';
       }
     }
 
@@ skipping 79 matching lines @@
     write(')');
   }
 
   /**
    * Documents the code contained within [span] with [comment]. If [showCode]
    * is `true` (and [includeSource] is set), also includes the source code.
    */
   docCode(SourceSpan span, String comment, [bool showCode = false]) {
     writeln('<div class="doc">');
     if (comment != null) {
-      writeln(md.markdownToHtml(comment));
+      writeln(comment);
     }
 
     if (includeSource && showCode) {
       writeln('<pre class="source">');
       writeln(md.escapeHtml(unindentCode(span)));
       writeln('</pre>');
     }
 
     writeln('</div>');
   }
 
   /** Get the doc comment associated with the given type. */
-  String getTypeComment(Type type) => _comments.find(type.span);
+  String getTypeComment(Type type) {
+    String comment = _comments.find(type.span);
+    if (comment == null) return null;
+    return md.markdownToHtml(comment);
+  }
 
   /** Get the doc comment associated with the given method. */
-  String getMethodComment(MethodMember method) => _comments.find(method.span);
+  String getMethodComment(MethodMember method) {
+    String comment = _comments.find(method.span);
+    if (comment == null) return null;
+    return md.markdownToHtml(comment);
+  }
 
   /** Get the doc comment associated with the given field. */
-  String getFieldComment(FieldMember field) => _comments.find(field.span);
+  String getFieldComment(FieldMember field) {
+    String comment = _comments.find(field.span);
+    if (comment == null) return null;
+    return md.markdownToHtml(comment);
+  }
+
+  /**
+   * Converts [fullPath] 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 fullPath) {
+    // Don't make it relative if it's an absolute path.
+    if (isAbsolute(fullPath)) return fullPath;
+
+    // TODO(rnystrom): Walks all the way up to root each time. Shouldn't do
+    // this if the paths overlap.
+    return repeat('../', countOccurrences(_filePath, '/')) + fullPath;
+  }
+
+  /** Gets whether or not the given URL is absolute or relative. */
+  bool isAbsolute(String url) {
+    // TODO(rnystrom): Why don't we have a nice type in the platform for this?
+    // TODO(rnystrom): This is a bit hackish. We consider any URL that lacks
+    // a scheme to be relative.
+    return const RegExp(@'^\w+:').hasMatch(url);
+  }
+
+  /** Gets the URL to the documentation for [library]. */
+  String libraryUrl(Library library) {
+    return '${sanitize(library.name)}.html';
+  }
+
+  /** Gets the URL for the documentation for [type]. */
+  String 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]. */
+  String memberUrl(Member member) {
+    return '${typeUrl(member.declaringType)}#${member.name}';
+  }
+
+  /** Gets the anchor id for the document for [member]. */
+  String memberAnchor(Member member) {
+    return '${member.name}';
+  }
 
   /**
    * Creates a hyperlink. Handles turning the [href] into an appropriate
    * relative path from the current file.
    */
   String a(String href, String contents, [String css]) {
+    // Mark outgoing external links, mainly so we can style them.
+    final rel = isAbsolute(href) ? ' ref="external"' : '';
     final cssClass = css == null ? '' : ' class="$css"';
-    return '<a href="${relativePath(href)}"$cssClass>$contents</a>';
+    return '<a href="${relativePath(href)}"$cssClass$rel>$contents</a>';
   }
 
   /**
    * Writes a type annotation for the given type and (optional) parameter name.
    */
   annotateType(Type enclosingType, Type type, [String paramName = null]) {
     // Don't bother explicitly displaying Dynamic.
     if (type.isVar) {
       if (paramName !== null) write(paramName);
       return;
@@ skipping 210 matching lines @@
 
     return new md.Element.text('code', name);
   }
 
   // TODO(rnystrom): Move into SourceSpan?
   int getSpanColumn(SourceSpan span) {
     final line = span.file.getLine(span.start);
     return span.file.getColumn(line, span.start);
   }
 }