Make re-exported classes appear as if they are part of the original library.

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 306 matching lines @@
     bool outputToYaml: true, bool append: false, bool parseSdk: false,
     String introduction: ''}) {
   libs.forEach((lib) {
     // Files belonging to the SDK have a uri that begins with 'dart:'.
     if (includeSdk || !lib.uri.toString().startsWith('dart:')) {
       var library = generateLibrary(lib);
       entityMap[library.name] = library;
     }
   });
   // After everything is created, do a pass through all classes to make sure no
-  // intermediate classes created by mixins are included.
-  entityMap.values.where((e) => e is Class).forEach((c) => c.makeValid());
+  // intermediate classes created by mixins are included, all the links to
+  // exported members point to the new library.
+  entityMap.values.where((e) => e is Class).forEach(
+      (c) => c.updateLinksAndRemoveIntermediaryClasses());
   // Everything is a subclass of Object, therefore empty the list to avoid a
   // giant list of subclasses to be printed out.
   if (includeSdk) (entityMap['dart-core.Object'] as Class).subclasses.clear();
 
   var filteredEntities = entityMap.values.where(_isVisible);
 
   // Outputs a JSON file with all libraries and their preview comments.
   // This will help the viewer know what libraries are available to read in.
   var libraryMap;
   var linkResolver = (name) => fixReference(name, null, null, null);
   if (append) {
     var docsDir = listDir(_outputDirectory);
     if (!docsDir.contains('$_outputDirectory/library_list.json')) {
       throw new StateError('No library_list.json');
     }
     libraryMap =
-        JSON.decode(new File('$_outputDirectory/library_list.json').readAsStringSync());
+        JSON.decode(new File(
+            '$_outputDirectory/library_list.json').readAsStringSync());
     libraryMap['libraries'].addAll(filteredEntities
         .where((e) => e is Library)
         .map((e) => e.previewMap));
     if (introduction.isNotEmpty) {
       var intro = libraryMap['introduction'];
       if (intro.isNotEmpty) intro += '<br/><br/>';
       intro += markdown.markdownToHtml(
           new File(introduction).readAsStringSync(),
               linkResolver: linkResolver, inlineSyntaxes: markdownSyntaxes);
       libraryMap['introduction'] = intro;
@@ skipping 255 matching lines @@
 
 /// Converts all [foo] references in comments to <a>libraryName.foo</a>.
 markdown.Node fixReference(String name, LibraryMirror currentLibrary,
     ClassMirror currentClass, MemberMirror currentMember) {
   // Attempt the look up the whole name up in the scope.
   String elementName =
       findElementInScope(name, currentLibrary, currentClass, currentMember);
   if (elementName != null) {
     return new markdown.Element.text('a', elementName);
   }
-  return _fixComplexReference(name, currentLibrary, currentClass, currentMember);
+  return _fixComplexReference(name, currentLibrary, currentClass,
+      currentMember);
 }
 
 markdown.Node fixReferenceWithScope(String name, DeclarationMirror scope) {
   if (scope is LibraryMirror) return fixReference(name, scope, null, null);
   if (scope is ClassMirror)
       return fixReference(name, scope.library, scope, null);
   if (scope is MemberMirror) {
     var owner = scope.owner;
     if (owner is ClassMirror) {
         return fixReference(name, owner.library, owner, scope);
     } else {
       return fixReference(name, owner, null, scope);
     }
   }
   return null;
 }
 
 /// Writes text to a file in the output directory.
 void _writeToFile(String text, String filename, {bool append: false}) {
   if (text == null) return;
   Directory dir = new Directory(_outputDirectory);
   if (!dir.existsSync()) {
     dir.createSync();
   }
-  // We assume there's a single extra level of directory structure for packages.
   if (path.split(filename).length > 1) {
-    var subdir = new Directory(path.join(_outputDirectory, path.dirname(filename)));
-    if (!subdir.existsSync()) {
-      subdir.createSync();
+    var splitList = path.split(filename);
+    for (int i = 0; i < splitList.length; i++) {
+      var level = splitList[i];
+    }
+    for (var level in path.split(filename)) {
+      var subdir = new Directory(path.join(_outputDirectory,
+                                           path.dirname(filename)));
+      if (!subdir.existsSync()) {
+        subdir.createSync();
+      }
     }
   }
   File file = new File(path.join(_outputDirectory, filename));
   file.writeAsStringSync(text, mode: append ? FileMode.APPEND : FileMode.WRITE);
 }
 
 /// Transforms the map by calling toMap on each value in it.
 Map recurseMap(Map inputMap) {
   var outputMap = {};
   inputMap.forEach((key, value) {
@@ skipping 189 matching lines @@
   /// Top-level functions in the library.
   MethodGroup functions;
 
   /// Classes defined within the library
   ClassGroup classes;
 
   String packageName = '';
   bool hasBeenCheckedForPackage = false;
   String packageIntro;
 
+  Map<String, Exported> _exportedMembers;
+
   Library(LibraryMirror libraryMirror) : super(libraryMirror) {
     var exported = _calcExportedItems(libraryMirror);
-    this.classes = _createClasses(
-        exported['classes']..addAll(libraryMirror.classes));
+    _createClasses(exported['classes']..addAll(libraryMirror.classes));
     this.functions = _createMethods(
         exported['methods']..addAll(libraryMirror.functions));
     this.variables = _createVariables(
         exported['variables']..addAll(libraryMirror.variables));
+
+    var exportedVariables = {};
+    variables.forEach((key, value) {
+      if (value is ExportedVariable) {
+        exportedVariables[key] = value;
+      }
+    });
+    _exportedMembers = new Map.from(this.classes.exported)
+        ..addAll(this.functions.exported)
+        ..addAll(exportedVariables);
   }
 
   String get packagePrefix => packageName == null || packageName.isEmpty ?
       '' : '$packageName/';
 
   Map get previewMap {
     var basic = super.previewMap;
     basic['packageName'] = packageName;
     if (packageIntro != null) {
       basic['packageIntro'] = packageIntro;
     }
     return basic;
   }
 
   String get owner => '';
 
   String get name => docName(mirror);
 
   /// Returns a [ClassGroup] containing error, typedef and regular classes.

[Alan Knight, 2013/12/03 22:48:07]

If it's void now, comment should be updated.

-  ClassGroup _createClasses(Map<String, ClassMirror> mirrorMap) {
-    var group = new ClassGroup();
+  void _createClasses(Map<String, ClassMirror> mirrorMap) {
+    this.classes = new ClassGroup();
     mirrorMap.forEach((String mirrorName, ClassMirror mirror) {
-        group.addClass(mirror);
+      this.classes.addClass(mirror, this);
     });
-    return group;
   }
 
   /// For the given library determine what items (if any) are exported.
   ///
   /// Returns a Map with three keys: "classes", "methods", and "variables" the
   /// values of which point to a map of exported name identifiers with values
   /// corresponding to the actual DeclarationMirror.
   Map<String, Map<String, DeclarationMirror>> _calcExportedItems(
       LibraryMirror library) {
     var exports = {};
@@ skipping 177 matching lines @@
       if (interface.isError()) return true;
     }
     if (superclass == null) return false;
     return superclass.isError();
   }
 
   /// Check that the class exists in the owner library.
   ///
   /// If it does not exist in the owner library, it is a mixin applciation and
   /// should be removed.
-  void makeValid() {
+  void updateLinksAndRemoveIntermediaryClasses() {
     var library = entityMap[owner];
-    if (library != null && !library.classes.containsKey(name)) {
-      this.isPrivate = true;
-      // Since we are now making the mixin a private class, make all elements
-      // with the mixin as an owner private too.
-      entityMap.values.where((e) => e.owner == qualifiedName)
-        .forEach((element) => element.isPrivate = true);
-      // Move the subclass up to the next public superclass
-      subclasses.forEach((subclass) => addSubclass(subclass));
+    if (library != null) {
+      if (!library.classes.containsKey(name) && mirror.isNameSynthetic) {
+        // In the mixin case, remove the intermediary classes.
+        this.isPrivate = true;
+        // Since we are now making the mixin a private class, make all elements
+        // with the mixin as an owner private too.
+        entityMap.values.where((e) => e.owner == qualifiedName).forEach(
+            (element) => element.isPrivate = true);
+        // Move the subclass up to the next public superclass
+        subclasses.forEach((subclass) => addSubclass(subclass));
+      } else {
+        // It is an exported item. Loop through each of the exported types,
+        // and tell them to update their links, given these other exported
+        // names within the library.
+        for (Exported member in library._exportedMembers.values) {
+          member.updateExports(library._exportedMembers.keys);
+        }
+      }
     }
   }
 
   /// Makes sure that all methods with inherited equivalents have comments.
   void ensureComments() {
     if (_commentsEnsured) return;
     _commentsEnsured = true;
     inheritedMethods.forEach((qualifiedName, inheritedMethod) {
       var method = methods[qualifiedName];
       if (method != null) method.ensureCommentFor(inheritedMethod);
     });
   }
 
-  /// If a class extends a private superclass, find the closest public superclass
-  /// of the private superclass.
+  /// If a class extends a private superclass, find the closest public
+  /// superclass of the private superclass.
   String validSuperclass() {
     if (superclass == null) return 'dart.core.Object';
     if (_isVisible(superclass)) return superclass.qualifiedName;
     return superclass.validSuperclass();
   }
 
   /// Generates a map describing the [Class] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'isAbstract' : isAbstract,
     'superclass': validSuperclass(),
     'implements': interfaces.where(_isVisible)
         .map((e) => e.qualifiedName).toList(),
     'subclass': (subclasses.toList()..sort())
         .map((x) => x.qualifiedName).toList(),
     'variables': recurseMap(variables),
     'inheritedVariables': recurseMap(inheritedVariables),
     'methods': methods.toMap(),
     'inheritedMethods': inheritedMethods.toMap(),
     'annotations': annotations.map((a) => a.toMap()).toList(),
     'generics': recurseMap(generics)
   };
 
   int compareTo(aClass) => name.compareTo(aClass.name);
 }
 
+abstract class Exported {
+  void updateExports(Map<String, Indexable> libraryExports);
+}
+

[Alan Knight, 2013/12/03 22:48:07]

I know this is the rough version. Comments and types for these would be good for
the polished version.

+Map _filterMap(exported, map, test) {
+  map.forEach((key, value) {
+    if (test(value)) exported[key] = value;
+  });
+  return exported;
+}
+
+class ExportedClass extends Class implements Exported {
+  Class _originalClass;
+  Library _exportingLibrary;
+
+  ExportedClass(ClassMirror originalClass, Library this._exportingLibrary) :
+      super._(originalClass) {
+    _originalClass = new Class(originalClass);
+  }
+
+  // The qualified name (for URL purposes) and the file name are the same,
+  // of the form packageName/ClassName or packageName/ClassName.methodName.
+  // This defines both the URL and the directory structure.
+  String get fileName => path.join(_exportingLibrary.packageName,
+      _exportingLibrary.mirror.qualifiedName + '.' + _originalClass.name);
+
+  void updateExports(Map<String, Indexable> libraryExports) {
+    // TODO(efortuna): If this class points to another exported class or type
+    // of some sort, then that reference needs to be updated here.
+    /* these need to be updated:
+    'comment': comment,
+    'superclass': validSuperclass(),
+    'implements': interfaces.where(_isVisible)
+        .map((e) => e.qualifiedName).toList(),
+    'subclass': (subclasses.toList()..sort())
+        .map((x) => x.qualifiedName).toList(),
+    'variables': recurseMap(variables),
+    'inheritedVariables': recurseMap(inheritedVariables),
+    'methods': methods.toMap(),
+    'inheritedMethods': inheritedMethods.toMap(),
+    'annotations': annotations.map((a) => a.toMap()).toList(),
+    'generics': recurseMap(generics)
+    */
+  }
+}
+
 /// A container to categorize classes into the following groups: abstract
 /// classes, regular classes, typedefs, and errors.
 class ClassGroup {
   Map<String, Class> classes = {};
   Map<String, Typedef> typedefs = {};
   Map<String, Class> errors = {};
 
-  void addClass(ClassMirror classMirror) {
+  Map<String, Exported> get exported {
+    var exported = _filterMap({}, classes, (value) => value is ExportedClass);
+    // TODO(efortuna): The line below needs updating.
+    exported = _filterMap(exported, typedefs,
+        (value) => value is ExportedClass);
+    exported = _filterMap(exported, errors,
+        (value) => value is ExportedClass);
+    return exported;
+  }
+
+  void addClass(ClassMirror classMirror, Library containingLibrary) {
     if (classMirror.isTypedef) {
       // This is actually a Dart2jsTypedefMirror, and it does define value,
       // but we don't have visibility to that type.
       var mirror = classMirror;
       if (_includePrivate || !mirror.isPrivate) {
         entityMap[docName(mirror)] = new Typedef(mirror);
         typedefs[mirror.simpleName] = entityMap[docName(mirror)];
       }
     } else {
       var clazz = new Class(classMirror);
 
+      classMirror.library.qualifiedName;
+      if (classMirror.library.qualifiedName !=
+          containingLibrary.mirror.qualifiedName) {
+        var exportedClass = new ExportedClass(classMirror, containingLibrary);
+        entityMap[clazz.fileName] = exportedClass;
+        clazz = exportedClass;
+      }
+
       if (clazz.isError()) {
         errors[classMirror.simpleName] = clazz;
       } else if (classMirror.isClass) {
         classes[classMirror.simpleName] = clazz;
       } else {
         throw new ArgumentError(
             '${classMirror.simpleName} - no class type match. ');
       }
     }
   }
@@ skipping 82 matching lines @@
   get comment {
     if (_comment != null) return _comment;
     var owningClass = owningEntity;
     if (owningClass is Class) {
       owningClass.ensureComments();
     }
     return super.comment;
   }
 }
 
+class ExportedVariable extends Variable implements Exported {
+  Library _exportingLibrary;
+
+  ExportedVariable(String variableName, VariableMirror originalVariable,
+      Library this._exportingLibrary) : super(variableName, originalVariable);
+
+  String get fileName => '${_exportingLibrary.packageName}/' +
+      super.fileName.substring(packagePrefix.length);
+
+  void updateExports(Map<String, Indexable> libraryExports) {
+    // TODO(efortuna): if this class points to another exported class or type
+    // of some sort, then that reference needs to be updated here.
+    /* these need to be updated:
+    'comment': comment,
+    'type': new List.filled(1, type.toMap()),
+    'annotations': annotations.map((a) => a.toMap()).toList()
+    */
+  }
+}
+
 /// A class containing properties of a Dart method.
 class Method extends Indexable {
 
   /// Parameters for this method.
   Map<String, Parameter> parameters;
 
   bool isStatic;
   bool isAbstract;
   bool isConst;
   bool isConstructor;
@@ skipping 50 matching lines @@
   get comment {
     if (_comment != null) return _comment;
     var owningClass = owningEntity;
     if (owningClass is Class) {
       owningClass.ensureComments();
     }
     return super.comment;
   }
 }
 
+class ExportedMethod extends Method implements Exported {
+  Library _exportingLibrary;
+
+  ExportedMethod(MethodMirror originalMethod, Library this._exportingLibrary) :
+      super(originalMethod);
+
+  String get fileName => '${_exportingLibrary.packageName}/' +
+      super.fileName.substring(packagePrefix.length);
+
+  void updateExports(Map<String, Indexable> libraryExports) {
+    // TODO(efortuna): if this class points to another exported class or type
+    // of some sort, then that reference needs to be updated here.
+    /* these need to be updated:
+    'qualifiedName': qualifiedName,
+    'comment': comment,
+    'commentFrom': commentInheritedFrom,
+    'return': new List.filled(1, returnType.toMap()),
+    'parameters': recurseMap(parameters),
+    'annotations': annotations.map((a) => a.toMap()).toList()
+    */
+  }
+}
+
+
+
 /// A container to categorize methods into the following groups: setters,
 /// getters, constructors, operators, regular methods.
 class MethodGroup {
   Map<String, Method> setters = {};
   Map<String, Method> getters = {};
   Map<String, Method> constructors = {};
   Map<String, Method> operators = {};
   Map<String, Method> regularMethods = {};
 
+  Map<String, Exported> get exported {
+    var exported = {};
+    for (Map<String, Method> group in [setters, getters, constructors,
+      operators, regularMethods]) {
+      exported = _filterMap(exported, group,
+          (value) => value is ExportedMethod);
+    }
+    return exported;
+  }
+
   void addMethod(MethodMirror mirror) {
     var method = new Method(mirror);
     entityMap[docName(mirror)] = method;
     if (mirror.isSetter) {
       setters[mirror.simpleName] = method;
     } else if (mirror.isGetter) {
       getters[mirror.simpleName] = method;
     } else if (mirror.isConstructor) {
       constructors[mirror.simpleName] = method;
     } else if (mirror.isOperator) {
@@ skipping 157 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;
 }