added a warning if no package root is passed in for a single file.

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 56 matching lines @@
  */
 Future<bool> docgen(List<String> files, {String packageRoot,
     bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false,
     bool parseSdk: false, bool append: false}) {
   if (!append) {
     var dir = new Directory('docs');
     if (dir.existsSync()) dir.deleteSync(recursive: true);
   }
   
   if (packageRoot == null && !parseSdk) {
-    // 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) {
+    var type = FileSystemEntity.typeSync(files.first);
+    if (type == FileSystemEntityType.DIRECTORY) {
       packageRoot = _findPackageRoot(files.first);
+    } else if (type == FileSystemEntityType.FILE) {
+      logger.warning('WARNING: No package root defined. If Docgen fails, try '
+          'again by setting the --package-root option.');
     }
   }
   logger.info('Package Root: ${packageRoot}');
 
   linkResolver = (name) =>
       fixReference(name, _currentLibrary, _currentClass, _currentMember);
 
   return getMirrorSystem(files, packageRoot: 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, append: append);
 
       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]);
 
   if (type == FileSystemEntityType.FILE) {
     libraries.add(path.absolute(args[0]));
     logger.info('Added to libraries: ${libraries.last}');
   } else {
     libraries.addAll(_listDartFromDir(args[0]));
   }
@@ skipping 616 matching lines @@
   String outer;
   List<Type> inner;
   
   Type(this.outer, this.inner);
   
   Map toMap() => {
       'outer': outer,
       'inner': new List.from(inner.map((e) => e.toMap()))
     };
 }