Add a new --extra-lib option to apidoc that allows us to specify an explicit .dart file that should…

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.
  *
@@ skipping 21 matching lines @@
 HtmlDiff _diff;
 
 void main() {
   final args = new Options().arguments;
 
   int mode = MODE_STATIC;
   Path outputDir = new Path('docs');
   bool generateAppCache = false;
 
   List<String> excludedLibraries = <String>[];
+
+  // For libraries that have names matching the package name,
+  // such as library unittest in package unittest, we just give
+  // the package name with a --include-lib argument, such as:
+  // --include-lib=unittest. These arguments are collected in
+  // includedLibraries.
   List<String> includedLibraries = <String>[];
+
+  // For libraries that lie within packages but have a different name,
+  // such as the matcher library in package unittest, we can use 
+  // --extra-lib with a full relative path under pkg, such as
+  // --extra-lib=unittest/lib/matcher.dart. These arguments are
+  // collected in extraLibraries.
+  List<String> extraLibraries = <String>[];
+
   String packageRoot;
   String version;
 
   // Parse the command-line arguments.
   for (int i = 0; i < args.length; i++) {
     final arg = args[i];
 
     switch (arg) {
       case '--mode=static':
         mode = MODE_STATIC;
         break;
 
       case '--mode=live-nav':
         mode = MODE_LIVE_NAV;
         break;
 
       case '--generate-app-cache=true':
         generateAppCache = true;
         break;
 
       default:
         if (arg.startsWith('--exclude-lib=')) {
           excludedLibraries.add(arg.substring('--exclude-lib='.length));
         } else if (arg.startsWith('--include-lib=')) {
           includedLibraries.add(arg.substring('--include-lib='.length));
+        } else if (arg.startsWith('--extra-lib=')) {
+          extraLibraries.add(arg.substring('--extra-lib='.length));
         } else if (arg.startsWith('--out=')) {
           outputDir = new Path(arg.substring('--out='.length));
         } else if (arg.startsWith('--package-root=')) {
           packageRoot = arg.substring('--package-root='.length);
         } else if (arg.startsWith('--version=')) {
           version = arg.substring('--version='.length);
         } else {
           print('Unknown option: $arg');
           return;
         }
@@ skipping 55 matching lines @@
       }
 
       if (new File.fromPath(libPath).existsSync()) {
         apidocLibraries.add(_pathToFileUri(libPath.toNativePath()));
         includedLibraries.add(libName);
       } else {
         print('Warning: could not find package at $path');
       }
     }
   }, onDone: () {
+    // Add any --extra libraries that had full pkg paths.
+    // TODO(gram): if the handling of --include-lib libraries in the
+    // listen() block above is cleaned up, then this will need to be
+    // too, as it is a special case of the above.
+    for (var lib in extraLibraries) {
+      var libPath = new Path('../../$lib');
+      if (new File.fromPath(libPath).existsSync()) {
+        apidocLibraries.add(_pathToFileUri(libPath.toNativePath()));
+        var libName = libPath.filename.replaceAll('.dart', '');
+        includedLibraries.add(libName);
+      }
+    }
+
     final apidoc = new Apidoc(mdn, outputDir, mode, generateAppCache,
                               excludedLibraries, version);
     apidoc.dartdocPath =
         scriptDir.append('../../sdk/lib/_internal/dartdoc/');
     // Select the libraries to include in the produced documentation:
     apidoc.includeApi = true;
     apidoc.includedLibraries = includedLibraries;
 
     // TODO(amouravski): make apidoc use roughly the same flow as bin/dartdoc.
     Future.wait([copiedStatic, copiedApiDocStatic, htmlDiff])
@@ skipping 303 matching lines @@
 /** Converts a local path string to a `file:` [Uri]. */
 Uri _pathToFileUri(String path) {
   path = pathos.absolute(path);
   if (Platform.operatingSystem != 'windows') {
     return Uri.parse('file://$path');
   } else {
     return Uri.parse('file:///${path.replaceAll("\\", "/")}');
   }
 }