Don't rely on a package having a library by the same name in order to associate a readme

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.
 ///
 ///      $ dart docgen.dart [OPTIONS] [FILE/DIR]
@@ skipping 125 matching lines @@
       return true;
     });
 }
 
 /// For a library's [mirror], determine the name of the package (if any) we
 /// believe it came from (because of its file URI).
 ///
 /// If [library] is specified, we set the packageName field. If no package could
 /// be determined, we return an empty string.
 String _findPackage(LibraryMirror mirror, [Library library]) {
+  if (library == null) {
+    library = entityMap[mirror.simpleName];
+  }
+  if (library != null) {
+    if (library.hasBeenCheckedForPackage) return library.packageName;
+    library.hasBeenCheckedForPackage = true;
+  }
   if (mirror.uri.scheme != 'file') return '';
   var filePath = mirror.uri.toFilePath();
   // We assume that we are documenting only libraries under package/lib
   var rootdir = path.dirname((path.dirname(filePath)));
   var pubspec = path.join(rootdir, 'pubspec.yaml');
   var packageName = _packageName(pubspec);
   if (library != null) {
     library.packageName = packageName;
-    // If we are the main library in a package, associate the package readme
-    // with us.
-    // TODO(alanknight): We can't really rely on all packages having a library
-    // that matches the package name. Need a better way to store this.
-    if (library.packageName == library.name) {
-      library.packageIntro = _packageIntro(rootdir);
-    }
+    // Associate the package readme with all the libraries. This is a bit
+    // wasteful, but easier than trying to figure out which partial match
+    // is best.
+    library.packageIntro = _packageIntro(rootdir);
   }
   return packageName;
 }
 
 String _packageIntro(packageDir) {
   var dir = new Directory(packageDir);
   var files = dir.listSync();
   var readmes = files.where((FileSystemEntity each) => (each is File &&
       each.path.substring(packageDir.length + 1, each.path.length)
           .startsWith('README'))).toList();
   if (readmes.isEmpty) return '';
   // If there are multiples, pick the shortest name.
   readmes.sort((a, b) => a.length.compareTo(b.length));
   var readme = readmes.first;
   var contents = markdown.markdownToHtml(readme
     .readAsStringSync(), linkResolver: linkResolver,
     inlineSyntaxes: markdownSyntaxes);
   return contents;
 }
 
-
 List<String> _listLibraries(List<String> args) {
   var libraries = new List<String>();
   for (var arg in args) {
     var type = FileSystemEntity.typeSync(arg);
 
     if (type == FileSystemEntityType.FILE) {
       if (arg.endsWith('.dart')) {
         libraries.add(path.absolute(arg));
         logger.info('Added to libraries: ${libraries.last}');
       }
@@ skipping 669 matching lines @@
   /// Top-level variables in the library.
   Map<String, Variable> variables;
 
   /// Top-level functions in the library.
   MethodGroup functions;
 
   /// Classes defined within the library
   ClassGroup classes;
 
   String packageName = '';
+  bool hasBeenCheckedForPackage = false;
 
   String get packagePrefix => packageName == null || packageName.isEmpty
       ? ''
       : '$packageName/';
 
   String packageIntro;
 
   Map get previewMap {
     var basic = super.previewMap;
     basic['packageName'] = packageName;
@@ skipping 515 matching lines @@
 /// Remove statics from the map of inherited items before adding them.
 Map _filterStatics(Map items) {
   var result = {};
   items.forEach((name, item) {
     if (!item.isStatic) {
       result[name] = item;
     }
   });
   return result;
 }