Docgen returning a future

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.
 
 /**
  * **docgen** is a tool for creating machine readable representations of Dart 
  * code metadata, including: classes, members, comments and annotations.
  * 
  * docgen is run on a `.dart` file or a directory containing `.dart` files. 
  * 
@@ skipping 41 matching lines @@
 
 /**
  * Docgen constructor initializes the link resolver for markdown parsing.
  * Also initializes the command line arguments. 
  * 
  * [packageRoot] is the packages directory of the directory being analyzed. 
  * If [includeSdk] is 'true', then any SDK libraries explicitly imported will 
  * also be documented. 
  * If [parseSdk] is 'true', then all Dart SDK libraries will be documented. 
  * This option is useful when only the SDK libraries are needed. 
+ * 
+ * Returns true if docgen sucessfuly completes. 

[Andrei Mouravski, 2013/07/03 23:41:38]

Just for the future, we wrap "true" and "false" with backticks:

"Returns `true` if docgen..."

  */
-void docgen(List<String> files, {String packageRoot, bool outputToYaml: true, 
-  bool includePrivate: false, bool includeSdk: false, bool parseSdk: false}) {  
+Future<bool> docgen(List<String> files, {String packageRoot, 
+    bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false,
+    bool parseSdk: false}) {    
   if (packageRoot == null && !parseSdk) {
-    packageRoot = _findPackageRoot(files.first);
+    // TODO(janicejl): At the moment, if a single file is passed it, it is 
+    // assumed that it does not have a package root unless it is passed in by 
+    // the user. In future, find a better way to find the packageRoot and also 
+    // fully test finding the packageRoot. 
+    if (FileSystemEntity.typeSync(files.first) 
+        == FileSystemEntityType.DIRECTORY) {
+      packageRoot = _findPackageRoot(files.first);
+    }
   }
   logger.info('Package Root: ${packageRoot}');
   
   linkResolver = (name) => 
       fixReference(name, _currentLibrary, _currentClass, _currentMember);
   
-  getMirrorSystem(files, packageRoot, parseSdk: parseSdk)
+  return getMirrorSystem(files, packageRoot, parseSdk: parseSdk)
     .then((MirrorSystem mirrorSystem) {
       if (mirrorSystem.libraries.isEmpty) {
         throw new StateError('No library mirrors were created.');
       }
       _documentLibraries(mirrorSystem.libraries.values, 
           includeSdk: includeSdk, includePrivate: includePrivate, 
           outputToYaml: outputToYaml);
+      
+      return true;
     });
 }
 
 List<String> _listLibraries(List<String> args) {
   // TODO(janicejl): At the moment, only have support to have either one file,
   // or one directory. This is because there can only be one package directory
   // since only one docgen is created per run. 
   if (args.length != 1) throw new UnsupportedError(USAGE);
   var libraries = new List<String>();
   var type = FileSystemEntity.typeSync(args[0]);
@@ skipping 467 matching lines @@
     parameterMap['qualifiedname'] = qualifiedName;
     parameterMap['optional'] = isOptional.toString();
     parameterMap['named'] = isNamed.toString();
     parameterMap['default'] = hasDefaultValue.toString();
     parameterMap['type'] = type;
     parameterMap['value'] = defaultValue;
     parameterMap['annotations'] = new List.from(annotations);
     return parameterMap;
   } 
 }