Align source mirrors with runtime mirrors.

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]
 ///
 /// This creates files called `docs/<library_name>.yaml` in your current
 /// working directory.
 library docgen;
 
 import 'dart:convert';
 import 'dart:io';
 import 'dart:async';
 
+
 import 'package:logging/logging.dart';
 import 'package:markdown/markdown.dart' as markdown;
 import 'package:path/path.dart' as path;
 import 'package:yaml/yaml.dart';
 
 import 'dart2yaml.dart';
 import 'src/io.dart';
 import '../../../sdk/lib/_internal/compiler/compiler.dart' as api;
 import '../../../sdk/lib/_internal/compiler/implementation/filenames.dart';
-import '../../../sdk/lib/_internal/compiler/implementation/mirrors/dart2js_mirror.dart'
+import '../../../sdk/lib/_internal/compiler/implementation/mirrors/dart2js_mirrors.dart'
     as dart2js;
-import '../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart';
+import '../../../sdk/lib/_internal/compiler/implementation/mirrors/analyze.dart'
+    as dart2js;
+import '../../../sdk/lib/_internal/compiler/implementation/mirrors/source_mirrors.dart';
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dart'
     as dart2js_util;
 import '../../../sdk/lib/_internal/compiler/implementation/source_file_provider.dart';
 import '../../../sdk/lib/_internal/libraries.dart';
 
 var logger = new Logger('Docgen');
 
 const String USAGE = 'Usage: dart docgen.dart [OPTIONS] fooDir/barFile';
 
 
 List<String> skippedAnnotations = const [
     'metadata.DocsEditable', '_js_helper.JSName', '_js_helper.Creates',
     '_js_helper.Returns', 'observe-src-metadata.Reflectable'];
 
 /// Set of libraries declared in the SDK, so libraries that can be accessed
 /// when running dart by default.
 Iterable<LibraryMirror> _sdkLibraries;
 
 /// The dart:core library, which contains all types that are always available
 /// without import.
 LibraryMirror _coreLibrary;
 
 /// Current library being documented to be used for comment links.
 LibraryMirror _currentLibrary;
 
 /// Current class being documented to be used for comment links.
 ClassMirror _currentClass;
 
 /// Current member being documented to be used for comment links.
-MemberMirror _currentMember;
+DeclarationMirror _currentMember;
 
 /// Support for [:foo:]-style code comments to the markdown parser.
 List<markdown.InlineSyntax> markdownSyntaxes =
   [new markdown.CodeSyntax(r'\[:\s?((?:.|\n)*?)\s?:\]')];
 
 /// Resolves reference links in doc comments.
 markdown.Resolver linkResolver;
 
 /// Index of all indexable items. This also ensures that no class is
 /// created more than once.
@@ skipping 301 matching lines @@
     var previousIndex =
         JSON.decode(new File('docs/index.json').readAsStringSync());
     index.addAll(previousIndex);
   }
   _writeToFile(JSON.encode(index), 'index.json');
 }
 
 Library generateLibrary(dart2js.Dart2JsLibraryMirror library) {
   _currentLibrary = library;
   var result = new Library(docName(library), _commentToHtml(library),
-      _classes(library.classes),
-      _methods(library.functions),
-      _variables(library.variables),
+      _classes(dart2js_util.typesOf(library.declarations)),
+      _methods(dart2js_util.methodsOf(library.declarations)),
+      _variables(dart2js_util.variablesOf(library.declarations)),
       _isHidden(library));
   _findPackage(result, library);
   logger.fine('Generated library for ${result.name}');
   return result;
 }
 
 void _writeIndexableToFile(Indexable result, bool outputToYaml) {
   var outputFile = result.fileName;
   var output;
   if (outputToYaml) {
     output = getYamlString(result.toMap());
     outputFile = outputFile + '.yaml';
   } else {
     output = JSON.encode(result.toMap());
     outputFile = outputFile + '.json';
   }
   _writeToFile(output, outputFile);
 }
 
 /// Returns true if a library name starts with an underscore, and false
 /// otherwise.
 ///
 /// An example that starts with _ is _js_helper.
 /// An example that contains ._ is dart._collection.dev
 // This is because LibraryMirror.isPrivate returns `false` all the time.
 bool _isLibraryPrivate(LibraryMirror mirror) {
-  var sdkLibrary = LIBRARIES[mirror.simpleName];
+  var sdkLibrary = LIBRARIES[dart2js_util.nameOf(mirror)];
   if (sdkLibrary != null) {
     return !sdkLibrary.documented;
-  } else if (mirror.simpleName.startsWith('_') ||
-      mirror.simpleName.contains('._')) {
+  } else if (dart2js_util.nameOf(mirror).startsWith('_') ||
+      dart2js_util.nameOf(mirror).contains('._')) {
     return true;
   }
   return false;
 }
 
 /// A declaration is private if itself is private, or the owner is private.
 // Issue(12202) - A declaration is public even if it's owner is private.
 bool _isHidden(DeclarationMirror mirror) {
   if (mirror is LibraryMirror) {
     return _isLibraryPrivate(mirror);
   } else if (mirror.owner is LibraryMirror) {
     return (mirror.isPrivate || _isLibraryPrivate(mirror.owner));
   } else {
     return (mirror.isPrivate || _isHidden(mirror.owner));
   }
 }
 
 bool _isVisible(Indexable item) {
   return _includePrivate || !item.isPrivate;
 }
 
 /// Returns a list of meta annotations assocated with a mirror.
 List<Annotation> _annotations(DeclarationMirror mirror) {
   var annotationMirrors = mirror.metadata.where((e) =>
       e is dart2js.Dart2JsConstructedConstantMirror);
   var annotations = [];
   annotationMirrors.forEach((annotation) {
-    var parameterList = annotation.type.variables.values
+    var parameterList = dart2js_util.variablesOf(annotation.type.declarations)
       .where((e) => e.isFinal)
       .map((e) => annotation.getField(e.simpleName).reflectee)
       .where((e) => e != null)
       .toList();
     if (!skippedAnnotations.contains(docName(annotation.type))) {
       annotations.add(new Annotation(docName(annotation.type),
           parameterList));
     }
   });
   return annotations;
@@ skipping 76 matching lines @@
 }
 
 String _htmlMdn(String content, String url) {
   return '<div class="mdn">' + content.trim() + '<p class="mdn-note">'
       '<a href="' + url.trim() + '">from Mdn</a></p></div>';
 }
 
 /// Look for the specified name starting with the current member, and
 /// progressively working outward to the current library scope.
 String findElementInScope(String name, LibraryMirror currentLibrary,
-    ClassMirror currentClass, MemberMirror currentMember) {
+                          ClassMirror currentClass,
+                          DeclarationMirror currentMember) {
   determineLookupFunc(name) => name.contains('.') ?
       dart2js_util.lookupQualifiedInScope :
       (mirror, name) => mirror.lookupInScope(name);
   var lookupFunc = determineLookupFunc(name);
 
   var memberScope = currentMember == null ?
       null : lookupFunc(currentMember, name);
   if (memberScope != null) return docName(memberScope);
 
   var classScope = currentClass;
@@ skipping 68 matching lines @@
 /// This is a more complex reference. Try to break up if its of the form A<B>
 /// where A is an alphanumeric string and B is an A, a list of B ("B, B, B"),
 /// or of the form A<B>. Note: unlike other the other markdown-style links, all
 /// text inside the square brackets is treated as part of the link (aka the * is
 /// interpreted literally as a *, not as a indicator for bold <em>.
 ///
 /// Example: [foo&lt;_bar_>] will produce
 /// <a>resolvedFoo</a>&lt;<a>resolved_bar_</a>> rather than an italicized
 /// version of resolvedBar.
 markdown.Node _fixComplexReference(String name, LibraryMirror currentLibrary,
-    ClassMirror currentClass, MemberMirror currentMember) {
+                                   ClassMirror currentClass,
+                                   DeclarationMirror currentMember) {
   // Parse into multiple elements we can try to resolve.
   var tokens = _tokenizeComplexReference(name);
 
   // Produce an html representation of our elements. Group unresolved and plain
   // text are grouped into "link" elements so they display as code.
   final textElements = [' ', ',', '>', _LESS_THAN];
   var accumulatedHtml = '';
 
   for (var token in tokens) {
     bool added = false;
     if (!textElements.contains(token)) {
       String elementName = findElementInScope(token, currentLibrary,
           currentClass, currentMember);
       if (elementName != null) {
         accumulatedHtml += markdown.renderToHtml([new markdown.Element.text(
             'a', elementName)]);
         added = true;
       }
     }
     if (!added) {
       accumulatedHtml += token;
     }
   }
   return new markdown.Text(accumulatedHtml);
 }
 
 /// Converts all [foo] references in comments to <a>libraryName.foo</a>.
 markdown.Node fixReference(String name, LibraryMirror currentLibrary,
-    ClassMirror currentClass, MemberMirror currentMember) {
+                           ClassMirror currentClass,
+                           DeclarationMirror 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);
 }
 
 /// Returns a map of [Variable] objects constructed from [mirrorMap].
-Map<String, Variable> _variables(Map<String, VariableMirror> mirrorMap) {
+Map<String, Variable> _variables(Iterable<VariableMirror> mirrors) {
   var data = {};
   // TODO(janicejl): When map to map feature is created, replace the below with
   // a filter. Issue(#9590).

[floitsch, 2014/01/28 19:21:53]

Either rewrite TODO, or just do the switch.

-  mirrorMap.forEach((String mirrorName, VariableMirror mirror) {
+  mirrors.forEach((VariableMirror mirror) {
     _currentMember = mirror;
     if (_includePrivate || !_isHidden(mirror)) {
+      var mirrorName = dart2js_util.nameOf(mirror);
       entityMap[docName(mirror)] = new Variable(mirrorName, mirror.isFinal,
          mirror.isStatic, mirror.isConst, _type(mirror.type),
          _commentToHtml(mirror), _annotations(mirror), docName(mirror),
          _isHidden(mirror), docName(mirror.owner));
       data[mirrorName] = entityMap[docName(mirror)];
     }
   });
   return data;
 }
 
 /// Returns a map of [Method] objects constructed from [mirrorMap].
-MethodGroup _methods(Map<String, MethodMirror> mirrorMap) {
+MethodGroup _methods(Iterable<MethodMirror> mirrors) {
   var group = new MethodGroup();
-  mirrorMap.forEach((String mirrorName, MethodMirror mirror) {
+  mirrors.forEach((MethodMirror mirror) {
     if (_includePrivate || !mirror.isPrivate) {
       group.addMethod(mirror);
     }
   });
   return group;
 }
 
 /// Returns the [Class] for the given [mirror] has already been created, and if
 /// it does not exist, creates it.
-Class _class(ClassMirror mirror) {
+Class _class(ClassSourceMirror mirror) {
   var clazz = entityMap[docName(mirror)];
   if (clazz == null) {
+    var mirrorName = dart2js_util.nameOf(mirror);
     var superclass = mirror.superclass != null ?
         _class(mirror.superclass) : null;
     var interfaces =
         mirror.superinterfaces.map((interface) => _class(interface));
-    clazz = new Class(mirror.simpleName, superclass, _commentToHtml(mirror),
-        interfaces.toList(), _variables(mirror.variables),
-        _methods(mirror.methods), _annotations(mirror), _generics(mirror),
+    clazz = new Class(mirrorName, superclass, _commentToHtml(mirror),
+        interfaces.toList(),
+        _variables(dart2js_util.variablesOf(mirror.declarations)),
+        _methods(dart2js_util.methodsOf(mirror.declarations)),
+        _annotations(mirror), _generics(mirror),
         docName(mirror), _isHidden(mirror), docName(mirror.owner),
         mirror.isAbstract);
     if (superclass != null) clazz.addInherited(superclass);
     interfaces.forEach((interface) => clazz.addInherited(interface));
     entityMap[docName(mirror)] = clazz;
   }
   return clazz;
 }
 
 /// Returns a map of [Class] objects constructed from [mirrorMap].
-ClassGroup _classes(Map<String, ClassMirror> mirrorMap) {
+ClassGroup _classes(Iterable<TypeMirror> mirrors) {
   var group = new ClassGroup();
-  mirrorMap.forEach((String mirrorName, ClassMirror mirror) {
-      group.addClass(mirror);
-  });
+  mirrors.forEach(group.addClass);
   return group;
 }
 
 /// Returns a map of [Parameter] objects constructed from [mirrorList].
 Map<String, Parameter> _parameters(List<ParameterMirror> mirrorList) {
   var data = {};
   mirrorList.forEach((ParameterMirror mirror) {
+    var mirrorName = dart2js_util.nameOf(mirror);
     _currentMember = mirror;
-    data[mirror.simpleName] = new Parameter(mirror.simpleName,
+    data[mirrorName] = new Parameter(mirrorName,
         mirror.isOptional, mirror.isNamed, mirror.hasDefaultValue,
-        _type(mirror.type), mirror.defaultValue,
+        _type(mirror.type), '${mirror.defaultValue}',
         _annotations(mirror));
   });
   return data;
 }
 
 /// Returns a map of [Generic] objects constructed from the class mirror.

[floitsch, 2014/01/28 19:21:53]

from the type mirror.

-Map<String, Generic> _generics(ClassMirror mirror) {
+Map<String, Generic> _generics(TypeMirror mirror) {
   return new Map.fromIterable(mirror.typeVariables,
       key: (e) => e.toString(),
       value: (e) => new Generic(e.toString(), e.upperBound.qualifiedName));
 }
 
 /// Returns a single [Type] object constructed from the Method.returnType
 /// Type mirror.
 Type _type(TypeMirror mirror) {
   return new Type(docName(mirror), _typeGenerics(mirror));
 }
 
 /// Returns a list of [Type] objects constructed from TypeMirrors.
 List<Type> _typeGenerics(TypeMirror mirror) {
-  if (mirror is ClassMirror && !mirror.isTypedef) {
+  if (mirror is ClassMirror) {
     var innerList = [];
     mirror.typeArguments.forEach((e) {
       innerList.add(new Type(docName(e), _typeGenerics(e)));
     });
     return innerList;
   }
   return [];
 }
 
 /// Writes text to a file in the 'docs' directory.
@@ skipping 261 matching lines @@
   };
 }
 
 /// 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 mirror) {
+  void addClass(TypeMirror mirror) {
     _currentClass = mirror;
-    if (mirror.isTypedef) {
+    var mirrorName = dart2js_util.nameOf(mirror);
+    if (mirror is TypedefMirror) {
       // This is actually a Dart2jsTypedefMirror, and it does define value,
       // but we don't have visibility to that type.
-      var mirror = _currentClass;
+      //var mirror = _currentClass;
       if (_includePrivate || !mirror.isPrivate) {
-        entityMap[docName(mirror)] = new Typedef(mirror.simpleName,
-            docName(mirror.value.returnType), _commentToHtml(mirror),
-            _generics(mirror), _parameters(mirror.value.parameters),
+        entityMap[docName(mirror)] = new Typedef(mirrorName,
+            docName(mirror.referent.returnType), _commentToHtml(mirror),
+            _generics(mirror), _parameters(mirror.referent.parameters),
             _annotations(mirror), docName(mirror),  _isHidden(mirror),
             docName(mirror.owner));
-        typedefs[mirror.simpleName] = entityMap[docName(mirror)];
+        typedefs[mirrorName] = entityMap[docName(mirror)];
       }
-    } else {
+    } else if (mirror is ClassMirror) {
       var clazz = _class(mirror);
 
       // Adding inherited parent variables and methods.
       clazz.parent().forEach((parent) {
         if (_isVisible(clazz)) {
           parent.addSubclass(clazz);
         }
       });
 
       clazz.ensureComments();
 
       if (clazz.isError()) {
-        errors[mirror.simpleName] = clazz;
-      } else if (mirror.isClass) {
-        classes[mirror.simpleName] = clazz;
+        errors[mirrorName] = clazz;
       } else {
-        throw new ArgumentError('${mirror.simpleName} - no class type match. ');
+        classes[mirrorName] = clazz;
       }
+    } else {
+      throw new ArgumentError('${mirrorName} - no class type match. ');
     }
   }
 
   /// Checks if the given name is a key for any of the Class Maps.
   bool containsKey(String name) {
     return classes.containsKey(name) || errors.containsKey(name);
   }
 
   Map toMap() => {
     'class': classes.values.where(_isVisible)
@@ skipping 125 matching lines @@
 /// 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 = {};
 
   void addMethod(MethodMirror mirror) {
-    var method = new Method(mirror.simpleName, mirror.isStatic,
+    var methodName = dart2js_util.nameOf(mirror);
+    var method = new Method(methodName, mirror.isStatic,
         mirror.isAbstract, mirror.isConstConstructor, _type(mirror.returnType),
         _commentToHtml(mirror), _parameters(mirror.parameters),
         _annotations(mirror), docName(mirror), _isHidden(mirror),
         docName(mirror.owner), mirror.isConstructor, mirror.isGetter,
         mirror.isSetter, mirror.isOperator);
     entityMap[docName(mirror)] = method;
     _currentMember = mirror;
     if (mirror.isSetter) {
-      setters[mirror.simpleName] = method;
+      setters[methodName] = method;
     } else if (mirror.isGetter) {
-      getters[mirror.simpleName] = method;
+      getters[methodName] = method;
     } else if (mirror.isConstructor) {
-      constructors[mirror.simpleName] = method;
+      constructors[methodName] = method;
     } else if (mirror.isOperator) {
-      operators[mirror.simpleName] = method;
+      operators[methodName] = method;
     } else if (mirror.isRegularMethod) {
-      regularMethods[mirror.simpleName] = method;
+      regularMethods[methodName] = method;
     } else {
-      throw new ArgumentError('${mirror.simpleName} - no method type match');
+      throw new ArgumentError('${methodName} - no method type match');
     }
   }
 
   void addInherited(Class parent) {
     setters.addAll(parent.inheritedMethods.setters);
     setters.addAll(_filterStatics(parent.methods.setters));
     getters.addAll(parent.inheritedMethods.getters);
     getters.addAll(_filterStatics(parent.methods.getters));
     operators.addAll(parent.inheritedMethods.operators);
     operators.addAll(_filterStatics(parent.methods.operators));
@@ skipping 119 matching lines @@
     'name': qualifiedName,
     'parameters': parameters
   };
 }
 
 /// Given a mirror, returns its qualified name, but following the conventions
 /// we're using in Dartdoc, which is that library names with dots in them
 /// have them replaced with hyphens.
 String docName(DeclarationMirror m) {
   if (m is LibraryMirror) {
-    return (m as LibraryMirror).qualifiedName.replaceAll('.','-');
+    return dart2js_util.qualifiedNameOf(m).replaceAll('.','-');
   }
   var owner = m.owner;
-  if (owner == null) return m.qualifiedName;
+  if (owner == null) return dart2js_util.qualifiedNameOf(m);
   // For the unnamed constructor we just return the class name.
   if (m.simpleName == '') return docName(owner);
-  return docName(owner) + '.' + m.simpleName;
+  return docName(owner) + '.' + dart2js_util.nameOf(m);
 }
 
 /// 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;
 }