Added a flag package-root for users to define where the package directory is.

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 72 matching lines @@
 void _setCommandLineArguments(ArgResults argResults) {
   outputToYaml = argResults['yaml'] || argResults['output-format'] == 'yaml';
   outputToJson = argResults['json'] || argResults['output-format'] == 'json';
   if (outputToYaml && outputToJson) {
     throw new ArgumentError('Cannot have contradictory output flags.');
   }
   outputToYaml = outputToYaml || !outputToJson;
   includePrivate = argResults['include-private'];
   parseSdk = argResults['parse-sdk'];
   includeSdk = parseSdk || argResults['include-sdk'];
+  packageDir = argResults['package-root'];
+  if (packageDir != null) logger.info('Package Root: ${packageDir}');
 }
 
 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]);
   
   if (type == FileSystemEntityType.FILE) {
     libraries.add(path.absolute(args[0]));
     logger.info('Added to libraries: ${libraries.last}');
   } else {
     libraries.addAll(_listDartFromDir(args[0]));
   } 
-  logger.info('Package Directory: $packageDir');
   return libraries;
 }
 
 List<String> _listDartFromDir(String args) {
   var files = listDir(args, recursive: true);
-  packageDir = files.firstWhere((f) => 
-      f.endsWith('/pubspec.yaml'), orElse: () => '');
-  if (packageDir != '') packageDir = path.dirname(packageDir) + '/packages';
-  return files.where((f) => 
-      f.endsWith('.dart') && !f.contains('/packages')).toList()
+  if (packageDir == null) {
+    packageDir = files.firstWhere((f) => 
+        f.endsWith('/pubspec.yaml'), orElse: () => '');
+    if (packageDir != '') packageDir = path.dirname(packageDir) + '/packages';
+    logger.info('Package Directory: $packageDir');
+  }
+  // files with paths not containing '/packages' to avoid analyzing them twice, 

[Emily Fortuna, 2013/07/01 18:51:57]

files -> Files

also make this an actual sentence :-)

[janicejl, 2013/07/01 18:59:23]

Done.

+  // unless the file to analyze already has a /package in its path. 
+  return files.where((f) => f.endsWith('.dart') && 
+      (!f.contains('/packages') || args.contains('/packages'))).toList()
       ..forEach((lib) => logger.info('Added to libraries: $lib'));
 }
 
 List<String> _listSdk() {
   var sdk = new List<String>();
   LIBRARIES.forEach((String name, LibraryInfo info) {
     if (info.documented) { 
       sdk.add('dart:$name');
       logger.info('Add to SDK: ${sdk.last}');
     }
@@ skipping 15 matching lines @@
   } else {
     // If DART_SDK is not defined in the environment, 
     // assuming the dart executable is from the Dart SDK folder inside bin. 
     sdkRoot = path.dirname(path.dirname(new Options().executable));
     logger.info('SDK Root: ${sdkRoot}');
   }
   
   return _getMirrorSystemHelper(libraries, sdkRoot, packageRoot: packageDir);
 }
 
+// TODO(janicejl): Should make docgen fail gracefully, or output a friendly
+// error message letting them know why it is failing to create a mirror system.
+// If there is conflicting library names, should modify it with a hash at the 
+// end of it's library name. 
 /**
  * Analyzes set of libraries and provides a mirror system which can be used 
  * for static inspection of the source code.
  */
 Future<MirrorSystem> _getMirrorSystemHelper(List<String> libraries,
       String libraryRoot, {String packageRoot}) {
   SourceFileProvider provider = new SourceFileProvider();
   api.DiagnosticHandler diagnosticHandler =
         new FormattingDiagnosticHandler(provider).diagnosticHandler;
   Uri libraryUri = currentDirectory.resolve(appendSlash('$libraryRoot'));
@@ skipping 371 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;
   } 
 }