Have dartdoc document exports.

sdk/lib/_internal/dartdoc/lib/dartdoc.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.
 
 /**
  * To generate docs for a library, run this script with the path to an
  * entrypoint .dart file, like:
  *
  *     $ dart dartdoc.dart foo.dart
  *
  * This will create a "docs" directory with the docs for your libraries. To
  * create these beautiful docs, dartdoc parses your library and every library
  * it imports (recursively). From each library, it parses all classes and
  * members, finds the associated doc comments and builds crosslinked docs from
  * them.
  */
 library dartdoc;
 
 import 'dart:async';
 import 'dart:io';
 import 'dart:json' as json;
 import 'dart:math';
 import 'dart:uri';
 
+import 'package:pathos/path.dart' as pathos;
+
 import 'classify.dart';
 import 'markdown.dart' as md;
 import 'universe_serializer.dart';
 
 import 'src/dartdoc/nav.dart';
+import 'src/dartdoc/utils.dart';
+import 'src/export_map.dart';
 import 'src/json_serializer.dart' as json_serializer;
 
 // TODO(rnystrom): Use "package:" URL (#4968).
 import '../../compiler/implementation/mirrors/dart2js_mirror.dart' as dart2js;
 import '../../compiler/implementation/mirrors/mirrors.dart';
 import '../../compiler/implementation/mirrors/mirrors_util.dart';
 import '../../libraries.dart';
 
-part 'src/dartdoc/utils.dart';
-
 /**
  * Generates completely static HTML containing everything you need to browse
  * the docs. The only client side behavior is trivial stuff like syntax
  * highlighting code.
  */
 const MODE_STATIC = 0;
 
 /**
  * Generated docs do not include baked HTML navigation. Instead, a single
  * `nav.json` file is created and the appropriate navigation is generated
@@ skipping 204 matching lines @@
 
   /** Version of the sdk or package docs are being generated for. */
   String version;
 
   /** Set this to select the libraries to include in the documentation. */
   List<String> includedLibraries = const <String>[];
 
   /** Set this to select the libraries to exclude from the documentation. */
   List<String> excludedLibraries = const <String>[];
 
+  /** The package root for `package:` imports. */
+  String _packageRoot;
+
+  /** The map containing all the exports for each library. */
+  ExportMap _exports;
+
   /**
    * This list contains the libraries sorted in by the library name.
    */
   List<LibraryMirror> _sortedLibraries;
 
+  /** A map from absolute paths of libraries to the libraries at those paths. */
+  Map<String, LibraryMirror> _librariesByPath;
+
+  /**
+   * A map from absolute paths of hidden libraries to lists of [Export]s that
+   * export those libraries from visible libraries. This is used to determine
+   * what public library any given entity belongs to.
+   *
+   * The lists of exports are sorted so that exports that hide the fewest number
+   * of members come first.
+   */
+  Map<String, List<Export>> _hiddenLibraryExports;
+
   /** The library that we're currently generating docs for. */
   LibraryMirror _currentLibrary;
 
   /** The type that we're currently generating docs for. */
   ClassMirror _currentType;
 
   /** The member that we're currently generating docs for. */
   MemberMirror _currentMember;
 
   /** The path to the file currently being written to, relative to [outdir]. */
@@ skipping 117 matching lines @@
     var content = '';
     for (int i = 0; i < footerItems.length; i++) {
       if (i > 0) {
         content += '\n';
       }
       content += '<div>${footerItems[i]}</div>';
     }
     return content;
   }
 
-  Future documentEntryPoint(Path entrypoint, Path libPath, Path packageRoot) {
-    return documentLibraries(<Path>[entrypoint], libPath, packageRoot);
-  }
+  Future documentLibraries(List<Uri> libraryList, Path libPath,
+      String packageRoot) {
+    _packageRoot = packageRoot;
+    _exports = new ExportMap.parse(libraryList, packageRoot);
+    var librariesToAnalyze = _exports.allExportedFiles.toList();
+    librariesToAnalyze.addAll(libraryList.map((uri) {
+      if (uri.scheme == 'file') return fileUriToPath(uri);
+      // dart2js takes "dart:*" URIs as Path objects for some reason.
+      return uri.toString();
+    }));
 
-  Future documentLibraries(List<Path> libraryList, Path libPath, Path packageRoot) {
     // TODO(amouravski): make all of these print statements into logging
     // statements.
     print('Analyzing libraries...');
-    return dart2js.analyze(libraryList, libPath, packageRoot: packageRoot,
-        options: COMPILER_OPTIONS)
+    return dart2js.analyze(
+        librariesToAnalyze.map((path) => new Path(path)).toList(), libPath,
+        packageRoot: new Path(packageRoot), options: COMPILER_OPTIONS)
       .then((MirrorSystem mirrors) {
         print('Generating documentation...');
         _document(mirrors);
       });
   }
 
   void _document(MirrorSystem mirrors) {
     _started = true;
 
     // Sort the libraries by name (not key).
     _sortedLibraries = new List<LibraryMirror>.from(
         mirrors.libraries.values.where(shouldIncludeLibrary));
     _sortedLibraries.sort((x, y) {
       return displayName(x).toUpperCase().compareTo(
           displayName(y).toUpperCase());
     });
 
+    _librariesByPath = <String, LibraryMirror>{};
+    for (var library in mirrors.libraries.values) {
+      var path = _libraryPath(library);
+      if (path == null) continue;
+      path = pathos.normalize(pathos.absolute(path));
+      _librariesByPath[path] = library;
+    }
+
+    _hiddenLibraryExports = _generateHiddenLibraryExports();
+
     // Generate the docs.
     if (mode == MODE_LIVE_NAV) {
       docNavigationJson();
     } else {
       docNavigationDart();
     }
 
     docIndex();
     for (final library in _sortedLibraries) {
       docLibrary(library);
     }
 
     if (generateAppCache) {
       generateAppCacheManifest();
     }
 
+    // TODO(nweiz): properly handle exports when generating JSON.
     // TODO(jacobr): handle arbitrary pub packages rather than just the system
     // libraries.
     var revision = '0';
     if (version != null) {
       var match = new RegExp(r"_r(\d+)").firstMatch(version);
       if (match != null) {
         revision = match.group(1);
       } else {
         print("Warning: could not parse version: $version");
       }
@@ skipping 18 matching lines @@
     // Write out top level json file with a relative path to the library json
     // files.
     startFile("apidoc.json");
     packageManifest.location = revision;
     write(json_serializer.serialize(packageManifest));
     endFile();
 
     _finished = true;
   }
 
+  /**
+   * Generate [_hiddenLibraryExports] from [_exports] and [_librariesByPath].
+   */
+  Map<String, List<Export>> _generateHiddenLibraryExports() {
+    // First generate a map `exported path => exporter path => Export`. The
+    // inner map makes it easier to merge multiple exports of the same library
+    // by the same exporter.
+    var hiddenLibraryExportMaps = <String, Map<String, Export>>{};
+    _exports.exports.forEach((exporter, exports) {
+      var library = _librariesByPath[exporter];
+      // TODO(nweiz): remove this check when issue 9645 is fixed.
+      if (library == null) return;
+      if (!shouldIncludeLibrary(library)) return;
+      for (var export in exports) {
+        var library = _librariesByPath[export.path];
+        // TODO(nweiz): remove this check when issue 9645 is fixed.
+        if (library == null) continue;
+        if (shouldIncludeLibrary(library)) continue;
+
+        var hiddenExports = _exports.transitiveExports(export.path)
+            .map((transitiveExport) => export.compose(transitiveExport))
+            .toList();
+        hiddenExports.add(export);
+
+        for (var hiddenExport in hiddenExports) {
+          var exportsByExporterPath = hiddenLibraryExportMaps
+              .putIfAbsent(hiddenExport.path, () => <String, Export>{});
+          addOrMergeExport(exportsByExporterPath, exporter, hiddenExport);
+        }
+      }
+    });
+
+    // Now sort the values of the inner maps of `hiddenLibraryExportMaps` to get
+    // the final value of `_hiddenLibraryExports`.
+    var hiddenLibraryExports = <String, List<Export>>{};
+    hiddenLibraryExportMaps.forEach((exporteePath, exportsByExporterPath) {
+      int rank(Export export) {
+        if (export.show.isEmpty && export.hide.isEmpty) return 0;
+        if (export.show.isEmpty) return export.hide.length;
+        // Multiply by 1000 to ensure this sorts after an export with hides.
+        return 1000 * export.show.length;
+      }
+
+      var exports = exportsByExporterPath.values.toList();
+      exports.sort((export1, export2) {
+        var comparison = Comparable.compare(rank(export1), rank(export2));
+        if (comparison != 0) return comparison;
+
+        var library1 = _librariesByPath[export1.exporter];
+        var library2 = _librariesByPath[export2.exporter];
+        return Comparable.compare(library1.displayName, library2.displayName);
+      });
+      hiddenLibraryExports[exporteePath] = exports;
+    });
+    return hiddenLibraryExports;
+  }
+
   MdnComment lookupMdnComment(Mirror mirror) => null;
 
   void startFile(String path) {
     _filePath = new Path(path);
     _file = new StringBuffer();
   }
 
   void endFile() {
     final outPath = outputDir.join(_filePath);
     final dir = new Directory.fromPath(outPath.directoryPath);
@@ skipping 364 matching lines @@
     writeHeader('${displayName(library)} Library',
         [displayName(library), libraryUrl(library)]);
     writeln('<h2><strong>${displayName(library)}</strong> library</h2>');
 
     // Look for a comment for the entire library.
     final comment = getLibraryComment(library);
     if (comment != null) {
       writeln('<div class="doc">${comment.html}</div>');
     }
 
+    // Document the visible libraries exported by this library.
+    docExports(library);
+
     // Document the top-level members.
     docMembers(library);
 
     // Document the types.
     final interfaces = <ClassMirror>[];
     final abstractClasses = <ClassMirror>[];
     final classes = <ClassMirror>[];
     final typedefs = <TypedefMirror>[];
     final exceptions = <ClassMirror>[];
 
-    for (ClassMirror type in orderByName(library.classes.values)) {
+    var allClasses = _libraryClasses(library);
+    for (ClassMirror type in orderByName(allClasses)) {
       if (!showPrivate && type.isPrivate) continue;
 
       if (isException(type)) {
         exceptions.add(type);
       } else if (type.isClass) {
         if (type.isAbstract) {
           abstractClasses.add(type);
         } else {
           classes.add(type);
         }
       } else if (type.isInterface){
         interfaces.add(type);
       } else if (type is TypedefMirror) {
         typedefs.add(type);
       } else {
         throw new InternalError("internal error: unknown type $type.");
       }
     }
 
     docTypes(interfaces, 'Interfaces');
     docTypes(abstractClasses, 'Abstract Classes');
     docTypes(classes, 'Classes');
     docTypes(typedefs, 'Typedefs');
     docTypes(exceptions, 'Exceptions');
 
     writeFooter();
     endFile();
 
-    for (final type in library.classes.values) {
+    for (final type in allClasses) {
       if (!showPrivate && type.isPrivate) continue;
 
       docType(type);
     }
   }
 
   void docTypes(List types, String header) {
     if (types.length == 0) return;
 
     writeln('<div>');
@@ skipping 27 matching lines @@
     } else if (type.isClass) {
       if (type.isAbstract) {
         kind = 'abstract class';
       } else {
         kind = 'class';
       }
     }
 
     final typeTitle =
       '${typeName(type)} ${kind}';
-    writeHeader('$typeTitle / ${displayName(type.library)} Library',
-        [displayName(type.library), libraryUrl(type.library),
+    var library = _libraryFor(type);
+    writeHeader('$typeTitle / ${displayName(library)} Library',
+        [displayName(library), libraryUrl(library),
          typeName(type), typeUrl(type)]);
     writeln(
         '''
         <h2><strong>${typeName(type, showBounds: true)}</strong>
           $kind
         </h2>
         ''');
     writeln('<button id="show-inherited" class="show-inherited">'
             'Hide inherited</button>');
 
@@ skipping 171 matching lines @@
 
   static final Map<String, int> operatorOrderMap = (){
     var map = new Map<String, int>();
     var index = 0;
     for (String operator in operatorOrder) {
       map[operator] = index++;
     }
     return map;
   }();
 
+  void docExports(LibraryMirror library) {
+    // TODO(nweiz): show `dart:` library exports.
+    var exportLinks = _exports.transitiveExports(_libraryPath(library))
+        .map((export) {
+      var library = _librariesByPath[export.path];
+      // TODO(nweiz): remove this check when issue 9645 is fixed.
+      if (library == null) return null;
+      // Only link to publically visible libraries.
+      if (!shouldIncludeLibrary(library)) return null;
+
+      var memberNames = export.show.isEmpty ? export.hide : export.show;
+      var memberLinks = memberNames.map((name) {
+        return md.renderToHtml([resolveNameReference(
+            name, currentLibrary: library)]);
+      }).join(', ');
+      var combinator = '';
+      if (!export.show.isEmpty) {
+        combinator = ' show $memberLinks';
+      } else if (!export.hide.isEmpty) {
+        combinator = ' hide $memberLinks';
+      }
+
+      return '<ul>${a(libraryUrl(library), displayName(library))}'
+        '$combinator</ul>';
+    }).where((link) => link != null);
+
+    if (!exportLinks.isEmpty) {
+      writeln('<h3>Exports</h3>');
+      writeln('<ul>');
+      writeln(exportLinks.join('\n'));
+      writeln('</ul>');
+    }
+  }
+
   void docMembers(ContainerMirror host) {
     // Collect the different kinds of members.
     final staticMethods = [];
     final staticGetters = new Map<String,MemberMirror>();
     final staticSetters = new Map<String,MemberMirror>();
     final memberMap = new Map<String,MemberMirror>();
     final instanceMethods = [];
     final instanceOperators = [];
     final instanceGetters = new Map<String,MemberMirror>();
     final instanceSetters = new Map<String,MemberMirror>();
     final constructors = [];
 
-    host.members.forEach((_, MemberMirror member) {
-      if (!showPrivate && member.isPrivate) return;
+    var hostMembers = host is LibraryMirror ?
+        _libraryMembers(host) : host.members.values;
+    for (var member in hostMembers) {
+      if (!showPrivate && member.isPrivate) continue;
       if (host is LibraryMirror || member.isStatic) {
         if (member is MethodMirror) {
           if (member.isGetter) {
             staticGetters[member.displayName] = member;
           } else if (member.isSetter) {
             staticSetters[member.displayName] = member;
           } else {
             staticMethods.add(member);
           }
         } else if (member is VariableMirror) {
           staticGetters[member.displayName] = member;
         }
       }
-    });
+    }
 
     if (host is ClassMirror) {
       var iterable = new HierarchyIterable(host, includeType: true);
       for (ClassMirror type in iterable) {
         if (!host.isObject && !inheritFromObject && type.isObject) continue;
 
         type.members.forEach((_, MemberMirror member) {
           if (member.isStatic) return;
           if (!showPrivate && member.isPrivate) return;
 
@@ skipping 23 matching lines @@
       }
     }
 
     bool allMethodsInherited = true;
     bool allPropertiesInherited = true;
     bool allOperatorsInherited = true;
     memberMap.forEach((_, MemberMirror member) {
       if (member is MethodMirror) {
         if (member.isGetter) {
           instanceGetters[member.displayName] = member;
-          if (member.owner == host) {
+          if (_ownerFor(member) == host) {
             allPropertiesInherited = false;
           }
         } else if (member.isSetter) {
           instanceSetters[member.displayName] = member;
-          if (member.owner == host) {
+          if (_ownerFor(member) == host) {
             allPropertiesInherited = false;
           }
         } else if (member.isOperator) {
           instanceOperators.add(member);
-          if (member.owner == host) {
+          if (_ownerFor(member) == host) {
             allOperatorsInherited = false;
           }
         } else {
           instanceMethods.add(member);
-          if (member.owner == host) {
+          if (_ownerFor(member) == host) {
             allMethodsInherited = false;
           }
         }
       } else if (member is VariableMirror) {
         instanceGetters[member.displayName] = member;
-        if (member.owner == host) {
+        if (_ownerFor(member) == host) {
           allPropertiesInherited = false;
         }
       }
     });
 
     instanceOperators.sort((MethodMirror a, MethodMirror b) {
       return operatorOrderMap[a.simpleName].compareTo(
           operatorOrderMap[b.simpleName]);
     });
 
@@ skipping 44 matching lines @@
           assert(getter is MethodMirror);
           docProperty(host, getter, null);
         }
       } else if (getter == null) {
         // We only have a setter => Document as a method.
         assert(setter is MethodMirror);
         docMethod(host, setter);
       } else {
         DocComment getterComment = getMemberComment(getter);
         DocComment setterComment = getMemberComment(setter);
-        if (getter.owner != setter.owner ||
+        if (_ownerFor(getter) != _ownerFor(setter) ||
             getterComment != null && setterComment != null) {
           // Both have comments or are not declared in the same class
           // => Documents separately.
           if (getter is VariableMirror) {
             // Document field as a getter (setter is inherited).
             docField(host, getter, asGetter: true);
           } else {
             docMethod(host, getter);
           }
           if (setter is VariableMirror) {
@@ skipping 50 matching lines @@
       if (member.isGetter) {
         // Getter.
         name = 'get $name';
       } else if (member.isSetter) {
         // Setter.
         name = 'set $name';
       }
     }
 
     bool showCode = includeSource && !isAbstract;
-    bool inherited = host != member.owner;
+    bool inherited = host != member.owner && member.owner is! LibraryMirror;
 
     writeln('<div class="method${inherited ? ' inherited': ''}">'
             '<h4 id="${memberAnchor(member)}">');
 
     if (showCode) {
       writeln('<button class="show-code">Code</button>');
     }
 
     if (member is MethodMirror) {
       if (member.isConstructor) {
@@ skipping 70 matching lines @@
    * [host]. If [getter] is a [FieldMirror], [setter] must be [:null:].
    * Otherwise, if [getter] is a [MethodMirror], the property is considered
    * final if [setter] is [:null:].
    */
   void docProperty(ContainerMirror host,
                    MemberMirror getter, MemberMirror setter) {
     assert(getter != null);
     _totalMembers++;
     _currentMember = getter;
 
-    bool inherited = host != getter.owner;
+    bool inherited = host != getter.owner && getter.owner is! LibraryMirror;
 
     writeln('<div class="field${inherited ? ' inherited' : ''}">'
             '<h4 id="${memberAnchor(getter)}">');
 
     if (includeSource) {
       writeln('<button class="show-code">Code</button>');
     }
 
     bool isConst = false;
     bool isFinal;
@@ skipping 186 matching lines @@
   String typeUrl(ContainerMirror type) {
     if (type is LibraryMirror) {
       return '${sanitize(type.simpleName)}.html';
     }
     if (type.library == null) {
       return '';
     }
     // Always get the generic type to strip off any type parameters or
     // arguments. If the type isn't generic, genericType returns `this`, so it
     // works for non-generic types too.
-    return '${sanitize(displayName(type.library))}/'
+    return '${sanitize(displayName(_libraryFor(type)))}/'
            '${type.originalDeclaration.simpleName}.html';
   }
 
   /** Gets the URL for the documentation for [member]. */
   String memberUrl(MemberMirror member) {
-    String url = typeUrl(member.owner);
+    String url = typeUrl(_ownerFor(member));
     return '$url#${memberAnchor(member)}';
   }
 
   /** Gets the anchor id for the document for [member]. */
   String memberAnchor(MemberMirror member) {
     return member.simpleName;
   }
 
   /**
    * Creates a hyperlink. Handles turning the [href] into an appropriate
@@ skipping 58 matching lines @@
     if (type.isTypeVariable) {
       // If we're using a type parameter within the body of a generic class then
       // just link back up to the class.
       write(a(typeUrl(enclosingType), type.simpleName));
       return;
     }
 
     assert(type is ClassMirror);
 
     // Link to the type.
-    if (shouldLinkToPublicApi(type.library)) {
+    var library = _libraryFor(type);
+    if (shouldLinkToPublicApi(library)) {
       write('<a href="$API_LOCATION${typeUrl(type)}">${type.simpleName}</a>');
-    } else if (shouldIncludeLibrary(type.library)) {
+    } else if (shouldIncludeLibrary(library)) {
       write(a(typeUrl(type), type.simpleName));
     } else {
       write(type.simpleName);
     }
 
     if (type.isOriginalDeclaration) {
       // Avoid calling [:typeArguments():] on a declaration.
       return;
     }
 
@@ skipping 197 matching lines @@
         onDone: () => endFile());
   }
 
   /**
    * Returns [:true:] if [type] should be regarded as an exception.
    */
   bool isException(TypeMirror type) {
     return type.simpleName.endsWith('Exception') ||
         type.simpleName.endsWith('Error');
   }
+
+  /**
+   * Returns the absolute path to [library] on the filesystem, or `null` if the
+   * library doesn't exist on the local filesystem.
+   */
+  String _libraryPath(LibraryMirror library) =>
+    importUriToPath(library.uri, packageRoot: _packageRoot);
+
+  /**
+   * Returns a list of classes in [library], including classes it exports from
+   * hidden libraries.
+   */
+  List<ClassMirror> _libraryClasses(LibraryMirror library) =>
+    _libraryContents(library, (lib) => lib.classes.values);
+
+  /**
+   * Returns a list of top-level members in [library], including members it
+   * exports from hidden libraries.
+   */
+  List<MemberMirror> _libraryMembers(LibraryMirror library) =>
+    _libraryContents(library, (lib) => lib.members.values);
+
+
+  /**
+   * Returns a list of elements in [library], including elements it exports from
+   * hidden libraries. [fn] should return the element list for a single library,
+   * which will then be merged across all exported libraries.
+   */
+  List<DeclarationMirror> _libraryContents(LibraryMirror library,
+      List<DeclarationMirror> fn(LibraryMirror)) {
+    var contents = fn(library).toList();
+    var path = _libraryPath(library);
+    if (path == null) return contents;
+
+    contents.addAll(_exports.exports[path].expand((export) {
+      var exportedLibrary = _librariesByPath[export.path];
+      // TODO(nweiz): remove this check when issue 9645 is fixed.
+      if (exportedLibrary == null) return [];
+      if (shouldIncludeLibrary(exportedLibrary)) return [];
+      return fn(exportedLibrary).where((declaration) =>
+          export.isMemberVisible(declaration.displayName));
+    }));
+    return contents;
+  }
+
+  /**
+   * Returns the library in which [type] was defined. If [type] was defined in a
+   * hidden library that was exported by another library, this returns the
+   * exporter.
+   */
+  LibraryMirror _libraryFor(TypeMirror type) =>
+    _visibleLibrary(type.library, type.displayName);
+
+  /**
+   * Returns the owner of [declaration]. If [declaration]'s owner is a hidden
+   * library that was exported by another library, this returns the exporter.
+   */
+  DeclarationMirror _ownerFor(DeclarationMirror declaration) {
+    var owner = declaration.owner;
+    if (owner is! LibraryMirror) return owner;
+    return _visibleLibrary(owner, declaration.displayName);
+  }
+
+  /**
+   * Returns the best visible library that exports [name] from [library]. If
+   * [library] is public, it will be returned.
+   */
+  LibraryMirror _visibleLibrary(LibraryMirror library, String name) {
+    if (library == null) return null;
+
+    var exports = _hiddenLibraryExports[_libraryPath(library)];
+    if (exports == null) return library;
+
+    var export = exports.firstWhere(
+        (exp) => exp.isMemberVisible(name),
+        orElse: () => null);
+    if (export == null) return library;
+    return _librariesByPath[export.exporter];
+  }
 }
 
 /**
  * Used to report an unexpected error in the DartDoc tool or the
  * underlying data
  */
 class InternalError {
   final String message;
   const InternalError(this.message);
   String toString() => "InternalError: '$message'";
@@ skipping 77 matching lines @@
    return '''
         <div class="mdn">
         $mdnComment
         <div class="mdn-note"><a href="$mdnUrl">from MDN</a></div>
         </div>
         ''';
   }
 
   String toString() => mdnComment;
 }