Dartdoc and apidoc updated to use Path.

utils/apidoc/apidoc.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.
 
 /**
  * This generates the reference documentation for the core libraries that come
  * with dart. It is built on top of dartdoc, which is a general-purpose library
  * for generating docs from any Dart code. This library extends that to include
  * additional information and styling specific to our standard library.
  *
  * Usage:
  *
  *     $ dart apidoc.dart [--out=<output directory>]
  */
 
 #library('apidoc');
 
 #import('dart:io');
 #import('dart:json');
 #import('html_diff.dart');
 #import('../../lib/dartdoc/mirrors/mirrors.dart');
 #import('../../lib/dartdoc/mirrors/mirrors_util.dart');
 #import('../../lib/dartdoc/dartdoc.dart', prefix: 'doc');
 
 HtmlDiff _diff;
 
 void main() {

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

Couldn't we unify this and dartdoc.dart, perhaps with

final String MODE = 
 (new Options().script.endsWith("apidoc.dart")) ? "API" : "NORMAL";

Or else split dartdoc into a library and a script with a main, so both can
import dartdoc as a library without prefix?

It just seems hackish that one script imports another script, rather than both
importing a library.

But the common code is so much that maybe one file is better.

  

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

Dartdoc and apidoc are assimilating with the intention of a unification and
proper reuse.

   final args = new Options().arguments;
 
   int mode = doc.MODE_STATIC;
-  String outputDir = 'docs';
-  String compilerPath;
+  Path outputDir = const Path('docs');
   bool generateAppCache = false;
 
   // Parse the command-line arguments.
   for (int i = 0; i < args.length; i++) {
     final arg = args[i];
 
     switch (arg) {
       case '--mode=static':
         mode = doc.MODE_STATIC;
         break;
 
       case '--mode=live-nav':
         mode = doc.MODE_LIVE_NAV;
         break;
 
       case '--generate-app-cache=true':
         generateAppCache = true;
         break;
 
       default:
         if (arg.startsWith('--out=')) {
-          outputDir = arg.substring('--out='.length);
-        } else if (arg.startsWith('--compiler=')) {
-          compilerPath = arg.substring('--compiler='.length);
+          outputDir = new Path.fromNative(arg.substring('--out='.length));
         } else {
           print('Unknown option: $arg');
           return;
         }
         break;
     }
   }
 
-  final libPath = '${doc.scriptDir}/../../';
-
   doc.cleanOutputDirectory(outputDir);
 
   // Compile the client-side code to JS.
   // TODO(bob): Right path.
 
   final clientScript = (mode == doc.MODE_STATIC) ?
       'static' : 'live-nav';
-  doc.compileScript(
-      '${doc.scriptDir}/../../lib/dartdoc/client-$clientScript.dart',
-      '${outputDir}/client-$clientScript.js');
+  final Future compiled = doc.compileScript(
+      doc.scriptDir.append('../../lib/dartdoc/client-$clientScript.dart'),
+      outputDir.append('client-$clientScript.js'));
 
   // TODO(rnystrom): Use platform-specific path separator.
   // The basic dartdoc-provided static content.
   final Future copiedStatic = doc.copyFiles(
-      '${doc.scriptDir}/../../lib/dartdoc/static', outputDir);
+      doc.scriptDir.append('../../lib/dartdoc/static'),
+      outputDir);
 
   // The apidoc-specific static content.
-  final Future copiedApiDocStatic = doc.copyFiles('${doc.scriptDir}/static',
+  final Future copiedApiDocStatic = doc.copyFiles(
+      doc.scriptDir.append('static'),
       outputDir);
 
   print('Parsing MDN data...');
-  final mdnFile = new File('${doc.scriptDir}/mdn/database.json');
+  final mdnFile = new File.fromPath(doc.scriptDir.append('mdn/database.json'));
   final mdn = JSON.parse(mdnFile.readAsTextSync());
 
   print('Cross-referencing dart:html...');
-  HtmlDiff.initialize(libPath);
+  HtmlDiff.initialize(doc.libPath);
   _diff = new HtmlDiff(printWarnings:false);
   _diff.run();
 
   // Process handwritten HTML documentation.
   final htmldoc = new Htmldoc();
   htmldoc.documentLibraries(
-    <String>['${doc.scriptDir}/../../lib/html/doc/html.dartdoc'],
-    libPath);
+    <Path>[doc.scriptDir.append('../../lib/html/doc/html.dartdoc')],
+    doc.libPath);
   print('Processing handwritten HTML documentation...');
 
   // Process libraries.
 
+  // TODO(johnniwinther): Libraries for the compilation seem to be more like
+  // URIs. Perhaps Path should have a toURI() method.

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

Why not use URI instead of Path here?

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

Uri does not fit well either. Partially due to the gap between Path and Uri.

   // Add all of the core libraries.
-  var apidocLibraries = <String>[
-    'dart:core',
-    'dart:coreimpl',
-    'dart:crypto',
-    'dart:html',
-    'dart:io',
-    'dart:isolate',
-    'dart:json',
-    '${doc.scriptDir}/../../lib/math/math.dart',
-    '${doc.scriptDir}/../../lib/unittest/unittest.dart',
-    '${doc.scriptDir}/../../lib/i18n/intl.dart',
-    'dart:uri',
-    'dart:utf',
-    'dart:web',
+  var apidocLibraries = <Path>[
+    const Path('dart:core'),
+    const Path('dart:coreimpl'),
+    const Path('dart:crypto'),
+    const Path('dart:html'),
+    const Path('dart:io'),
+    const Path('dart:isolate'),
+    const Path('dart:json'),
+    doc.scriptDir.append('../../lib/math/math.dart'),
+    doc.scriptDir.append('../../lib/unittest/unittest.dart'),
+    doc.scriptDir.append('../../lib/i18n/intl.dart'),
+    const Path('dart:uri'),
+    const Path('dart:utf'),
+    const Path('dart:web'),
   ];
   print('Generating docs...');
   final apidoc = new Apidoc(mdn, htmldoc, outputDir, mode, generateAppCache);
   // Select the libraries to include in the produced documentation:
   apidoc.libraries = <String>[
     'core',
     'coreimpl',
     'crypto',
     'html',
     'io',
     'dart:isolate',
     'json',
     'math',
     'unittest',
     'intl',
     'uri',
     'utf',
     'web',
   ];
 
-  Futures.wait([copiedStatic, copiedApiDocStatic]).then((_) {
-    apidoc.documentLibraries(apidocLibraries, libPath);
+  Futures.wait([compiled, copiedStatic, copiedApiDocStatic]).then((_) {
+    apidoc.documentLibraries(apidocLibraries, doc.libPath);
   });
 }
 
 /**
  * This class is purely here to scrape handwritten HTML documentation.
  * This scraped documentation will later be merged with the generated
  * HTML library.
  */
 class Htmldoc extends doc.Dartdoc {
   String libraryComment;
@@ skipping 92 matching lines @@
 
   static final disqusShortname = 'dartapidocs';
 
   /**
    * The URL to the page on MDN that content was pulled from for the current
    * type being documented. Will be `null` if the type doesn't use any MDN
    * content.
    */
   String mdnUrl;
 
-  Apidoc(this.mdn, this.htmldoc, String outputDir, int mode,
+  Apidoc(this.mdn, this.htmldoc, Path outputDir, int mode,
          bool generateAppCache) {
     this.outputDir = outputDir;
     this.mode = mode;
     this.generateAppCache = generateAppCache;
 
     mainTitle = 'Dart API Reference';
     mainUrl = 'http://dartlang.org';
 
     final note    = 'http://code.google.com/policies.html#restrictions';
     final cca     = 'http://creativecommons.org/licenses/by/3.0/';
@@ skipping 236 matching lines @@
       // Not a DOM type.
       return null;
     }
 
     // Ignore top-level functions.
     if (member.isTopLevel) return null;
 
     final mdnType = mdn[member.surroundingDeclaration().simpleName()];
     if (mdnType == null) return null;
     var nameToFind = member.simpleName();
-    if (nameToFind.startsWith(GET_PREFIX)) {
-      nameToFind = nameToFind.substring(GET_PREFIX.length);
-    }
     var mdnMember = null;
     for (final candidateMember in mdnType['members']) {
       if (candidateMember['name'] == nameToFind) {
         mdnMember = candidateMember;
         break;
       }
     }
 
     if (mdnMember == null) return null;
 
     // Remember which MDN page we're using so we can attribute it.
     mdnUrl = mdnType['srcUrl'];
     return mdnMember['help'];
   }
 
   /**
    * Returns a link to [member], relative to a type page that may be in a
    * different library than [member].
    */
   String _linkMember(MemberMirror member) {
     final typeName = member.surroundingDeclaration().simpleName();
     var memberName = '$typeName.${member.simpleName()}';
-    if (member.isConstructor || member.isFactory) {
+    if (member is MethodMirror && (member.isConstructor || member.isFactory)) {
       final separator = member.constructorName == '' ? '' : '.';
       memberName = 'new $typeName$separator${member.constructorName}';
     }
 
     return a(memberUrl(member), memberName);
   }
 }