docgen working with a temporary link hack.

pkg/docgen/lib/docgen.dart

 // Copyright (c) 2013, 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.
 
 /**
  * The docgen tool takes in a library as input and produces documentation
  * for the library as well as all libraries it imports and uses. The tool can
  * be run by passing in the path to a .dart file like this:
  *
  *   dart docgen.dart [OPTIONS] [FILE/DIR]
  *
  * This outputs information about all classes, variables, functions, and
  * methods defined in the library and its imported libraries.
  */
 library docgen;
 
 import 'dart:io';
 import 'dart:json';
 import 'dart:async';
 import 'package:markdown/markdown.dart' as markdown;
 import 'package:args/args.dart';
 import 'dart2yaml.dart';
-import 'package:compiler_unsupported/compiler.dart' as api;
-import 'package:compiler_unsupported/implementation/filenames.dart';
-import 'package:compiler_unsupported/implementation/mirrors/dart2js_mirror.dart'
+import 'package:hack/compiler/compiler.dart' as api;

[Emily Fortuna, 2013/06/21 20:27:37]

Can you add a TODO(janicejl/amouravski) saying something to the effect of
"remove this import when we have a solution for keeping
lib/_internal/libraries.dart and lib/_internal/lib in sync" Perhaps file a bug
and list the bug number in the comment here, too.

+import 'package:hack/compiler/implementation/filenames.dart';
+import 'package:hack/compiler/implementation/mirrors/dart2js_mirror.dart'
     as dart2js;
-import 'package:compiler_unsupported/implementation/mirrors/mirrors.dart';
-import 'package:compiler_unsupported/implementation/mirrors/mirrors_util.dart';
-import 'package:compiler_unsupported/implementation/source_file_provider.dart';
+import 'package:hack/compiler/implementation/mirrors/mirrors.dart';
+import 'package:hack/compiler/implementation/mirrors/mirrors_util.dart';
+import 'package:hack/compiler/implementation/source_file_provider.dart';
 import 'package:logging/logging.dart';
 
 /// Logger for Dart Doc Generator. 
 var logger = new Logger("Docgen");
 
 /// Unique ID, will get incremented everytime an ID is requested. 
 int _uid = 0;
 
 int getID() => _uid++;
 
@@ skipping 95 matching lines @@
   bool outputToYaml;
   /// Should the output file type be JSON?
   bool outputToJson;
   /// Should the output file hide private declarations?
   bool hidePrivate;
   /// Should the output include SDK libraries?
   bool sdk;
   
   /**
    * Docgen constructor initializes the link resolver for markdown parsing.
    * Also initializes the command line arguments. 

[Bob Nystrom, 2013/06/21 20:32:53]

You can use "///" style doc comments for multiline comments too if you want:

/// Docgen constructor initializes the link resolver for markdown parsing.
/// Also initializes the command line arguments. 

    */
   Docgen({ArgResults argResults}) {  
-    outputToYaml = argResults["yaml"];
-    outputToJson = argResults["json"];
-    hidePrivate = argResults["hide-private"];
-    sdk = argResults["sdk"];
+    if (argResults != null) {
+      outputToYaml = argResults["yaml"];
+      outputToJson = argResults["json"];
+      hidePrivate = argResults["hide-private"];
+      sdk = argResults["sdk"];
+    } else {
+      outputToYaml = true;

[Emily Fortuna, 2013/06/21 20:27:37]

if you're already specifying default values from the arg parser, why not just
make argResults a required parameter, and then you don't need this branch?

[Bob Nystrom, 2013/06/21 20:32:53]

Alternatively, just pass these arguments directly to Docgen instead of the
ArtResults object.

[janicejl, 2013/06/21 21:02:39]

Done.

+      outputToJson = false;
+      hidePrivate = false;
+      sdk = true;
+    }
     
     this.linkResolver = (name) => 
         fixReference(name, _currentLibrary, _currentClass, _currentMember);
   }
   
   /**
    * Analyzes set of libraries by getting a mirror system and triggers the 
    * documentation of the libraries. 
    */
   void analyze(List<Path> libraries) {
     /// Assuming the dart executable is from the Dart SDK folder. 

[Bob Nystrom, 2013/06/21 20:32:53]

Just use a normal "//" comment here, not "///".

-    var sdkRoot = new Path(new Options().executable).directoryPath
-        .directoryPath;
-    logger.info("SDK Root: ${sdkRoot.toString()}");
+  
+    var sdkRoot = Platform.environment["DART_SDK"];

[Emily Fortuna, 2013/06/21 20:27:37]

I'd be inclined to keep it the way you had it before, since you said it's used
in a pretty non-standard fashion at various points in the codebase.  
Alternatively, please put a comment saying what you're expecting DART_SDK to
point to.

[janicejl, 2013/06/21 21:02:39]

I have kept it with a comment. I have also modified how it finds the sdk-root to
be more aligned with how pub does it. Assume it is relative to the executable.
And assume they are using the executable in bin. 

+    if (sdkRoot != null) {
+      logger.info("Using DART_SDK to find SDK at $sdkRoot");
+      sdkRoot = new Path(sdkRoot);
+    } else {
+      sdkRoot = new Path(new Options().executable).directoryPath
+          .append("dart-sdk");
+      logger.info("SDK Root: ${sdkRoot.toString()}");
+    }
+    
     Path packageDir = libraries.last.directoryPath.append("packages");
     logger.info("Package Root: ${packageDir.toString()}");
     getMirrorSystem(libraries, sdkRoot, 
         packageRoot: packageDir).then((MirrorSystem mirrorSystem) {
           if (mirrorSystem.libraries.values.isEmpty) {
             throw new UnsupportedError("No Library Mirrors.");
           } 
           this.libraries = mirrorSystem.libraries.values;
           documentLibraries();
         });
@@ skipping 353 matching lines @@
   if (!dir.existsSync()) {
     dir.createSync();
   }
   File file = new File('docs/$filename');
   if (!file.existsSync()) {
     file.createSync();
   }
   file.openSync();
   file.writeAsString(text);
 }