sdk/lib/_internal/dartdoc/lib/universe_serializer.dart - sdk.git - Git at Google

 // 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 library serializes the Dart2Js AST into a compact and easy to use
  * [Element] tree useful for code exploration tools such as DartDoc.
  */
 library universe_serializer;

 import '../../compiler/implementation/mirrors/mirrors.dart';
 import '../../compiler/implementation/mirrors/mirrors_util.dart';
 import '../../compiler/implementation/mirrors/dart2js_mirror.dart' as dart2js;
 import '../../libraries.dart';
 import 'dartdoc.dart';

 String _stripUri(String uri) {
   String prefix = "/dart/";
   int start = uri.indexOf(prefix);
   if (start != -1) {
     return uri.substring(start + prefix.length);
   } else {
     return uri;
   }
 }

 String _escapeId(String id) {
   return id.replaceAll(new RegExp('[/]'), '#slash');
 }

 /**
  * Base class for all elements in the AST.
  */
 class Element {
   /** Human readable type name for the node. */
   final String kind;
   /** Human readable name for the element. */
   final String name;
   /** Id for the node that is unique within its parent's children. */
   final String id;
   /** Raw text of the comment associated with the Element if any. */
   final String comment;
   /** Raw html comment for the Element from MDN. */
   String mdnCommentHtml;
   /**
    * The URL to the page on MDN that content was pulled from for the current
    * type being documented. Will be `null` if the type doesn't use any MDN
    * content.
    */
   String mdnUrl;
   /** Children of the node. */
   List<Element> children;
   /** Whether the element is private. */
   final bool isPrivate;

   /**
    * Uri containing the definition of the element.
    */
   String uri;
   /**
    * Line in the original source file that starts the definition of the element.
    */
   String line;

   // TODO(jacobr): refactor the code so that lookupMdnComment does not need to
   // be passed to every Element constructor.
   Element(Mirror mirror, this.kind, this.name, String id, this.comment,
       MdnComment lookupMdnComment(Mirror))
       : line = mirror.location.line.toString(),
         id = _escapeId(id),
         isPrivate = _optionalBool(mirror.isPrivate),
         uri = _stripUri(mirror.location.sourceUri.toString()) {
     if (lookupMdnComment != null) {
       var mdnComment = lookupMdnComment(mirror);
       if (mdnComment != null) {
         mdnCommentHtml = mdnComment.mdnComment;
         mdnUrl = mdnComment.mdnUrl;
       }
     }
   }

   void addChild(Element child) {
     if (children == null) {
       children = <Element>[];
     }
     children.add(child);
   }

   /**
    * Remove all URIs that exactly match the parent node's URI.
    * This reduces output file size by about 20%.
    */
   void stripDuplicateUris(String parentUri, parentLine) {
     if (children != null) {
       for (var child in children) {
         child.stripDuplicateUris(uri, line);
       }
     }
     if (parentUri == uri) {
       uri = null;
     }
     if (line == parentLine) {
       line = null;
     }
   }
 }

 /**
  * Converts false to null.  Useful as the serialization scheme we use
  * omits null values.
  */
 bool _optionalBool(bool value) => value == true ? true : null;

 Reference _optionalReference(Mirror mirror) {
   return (mirror != null && mirror.simpleName != "Dynamic_" &&
       mirror.simpleName != "dynamic") ?
         new Reference(mirror) : null;
 }

 /**
  * Helper class to track what members of a library should be included.
  */
 class LibrarySubset {
   final LibraryMirror library;
   Set<String> includedChildren;

   LibrarySubset(this.library) : includedChildren = new Set<String>();
 }

 /**
  * [Element] describing a Dart library.
  */
 class LibraryElement extends Element {
   /**
    * Partial versions of LibraryElements containing classes that are extended
    * or implemented by classes in this library.
    */
   List<LibraryElement> dependencies;

   /**
    * Construct a LibraryElement from a [mirror].
    *
    * If [includedChildren] is specified, only elements matching names in
    * [includedChildren] are included and no dependencies are included.
    * [lookupMdnComment] is an optional function that returns the MDN
    * documentation for elements. [dependencies] is an optional map
    * tracking all classes dependend on by this [ClassElement].
    */
   LibraryElement(LibraryMirror mirror,
       {MdnComment lookupMdnComment(Mirror), Set<String> includedChildren})
       : super(mirror, 'library', _libraryName(mirror), mirror.displayName,
           computeComment(mirror), lookupMdnComment) {
     var requiredDependencies;
     // We don't need to track our required dependencies when generating a
     // filtered version of this library which will be used as a dependency for
     // another library.
     if (includedChildren == null)
       requiredDependencies = new Map<String, LibrarySubset>();
     mirror.functions.forEach((childName, childMirror) {
       if (includedChildren == null || includedChildren.contains(childName))
         addChild(new MethodElement(childName, childMirror, lookupMdnComment));
     });

     mirror.getters.forEach((childName, childMirror) {
       if (includedChildren == null || includedChildren.contains(childName))
         addChild(new GetterElement(childName, childMirror, lookupMdnComment));
     });

     mirror.variables.forEach((childName, childMirror) {
       if (includedChildren == null || includedChildren.contains(childName))
         addChild(new VariableElement(childName, childMirror, lookupMdnComment));
     });

     mirror.classes.forEach((className, classMirror) {
       if (includedChildren == null || includedChildren.contains(className)) {
         if (classMirror is TypedefMirror) {
           addChild(new TypedefElement(className, classMirror));
         } else {
           addChild(new ClassElement(classMirror,
               dependencies: requiredDependencies,
               lookupMdnComment: lookupMdnComment));
         }
       }
     });

     if (requiredDependencies != null && !requiredDependencies.isEmpty) {
       dependencies = requiredDependencies.values.map((librarySubset) =>
           new LibraryElement(
               librarySubset.library,
               lookupMdnComment: lookupMdnComment,
               includedChildren: librarySubset.includedChildren)).toList();
     }
   }

   static String _libraryName(LibraryMirror mirror) {
     if (mirror.uri.scheme == 'file') {
       // TODO(jacobr): this is a hack. Remove once these libraries are removed
       // from the sdk.
       var uri = mirror.uri;
       var path = uri.path;
       var pattern = new RegExp(r'[\\/]dart[\\/]pkg[\\/]([^\\/]+)[\\/]lib[\\/](.+)$');
       var match = pattern.firstMatch(path);
       var package;
       if (match != null) {
         package = match.group(1);
         path = match.group(2);
       }
       // TODO(jacobr): add a second pattern for a more typical pub environment.
       if (package != null) {
         return 'package:$package/$path';
       } else {
         // TODO(jacobr): this is a lousy fallback.
         print("Unable to determine package for $path.");
         return mirror.uri.toString();
       }
     } else {
       return mirror.uri.toString();
     }
   }

   void stripDuplicateUris(String parentUri, parentLine) {
     super.stripDuplicateUris(parentUri, parentLine);

     if (dependencies != null) {
       for (var child in dependencies) {
         child.stripDuplicateUris(null, null);
       }
     }
   }
 }

 /**
  * Returns whether the class implements or extends [Error] or [Exception].
  */
 bool _isThrowable(ClassMirror mirror) {
   if (mirror.library.uri.toString() == 'dart:core' &&
       mirror.simpleName == 'Error' || mirror.simpleName == 'Exception')
     return true;
   if (mirror.superclass != null && _isThrowable(mirror.superclass))
     return true;
   return mirror.superinterfaces.any(_isThrowable);
 }

 /**
  * [Element] describing a Dart class.
  */
 class ClassElement extends Element {
   /** Base class.*/
   final Reference superclass;
   /** Whether the class is abstract. */
   final bool isAbstract;
   /** Interfaces the class implements. */
   List<Reference> interfaces;
   /** Whether the class implements or extends [Error] or [Exception]. */
   bool isThrowable;

   /**
    * Constructs a [ClassElement] from a [ClassMirror].
    *
    * [dependencies] is an optional map updated as a side effect of running
    * this constructor that tracks what classes from other libraries are
    * dependencies of classes in this library.  A class is considered a
    * dependency if it implements or extends another class.
    * [lookupMdnComment] is an optional function that returns the MDN
    * documentation for elements. [dependencies] is an optional map
    * tracking all classes dependend on by this [ClassElement].
    */
   ClassElement(ClassMirror mirror,
       {Map<String, LibrarySubset> dependencies,
        MdnComment lookupMdnComment(Mirror)})
       : super(mirror, 'class', mirror.simpleName, mirror.simpleName, computeComment(mirror),
           lookupMdnComment),
         superclass = _optionalReference(mirror.superclass),
         isAbstract = _optionalBool(mirror.isAbstract),
         isThrowable = _optionalBool(_isThrowable(mirror)){

     addCrossLibraryDependencies(clazz) {
       if (clazz == null) return;

       if (mirror.library != clazz.library) {
         var libraryStub = dependencies.putIfAbsent(clazz.library.simpleName,
             () => new LibrarySubset(clazz.library));
         libraryStub.includedChildren.add(clazz.simpleName);
       }

       for (var interface in clazz.superinterfaces) {
         addCrossLibraryDependencies(interface);
       }
       addCrossLibraryDependencies(clazz.superclass);
     }

     if (dependencies != null) {
       addCrossLibraryDependencies(mirror);
     }

     for (var interface in mirror.superinterfaces) {
       if (this.interfaces == null) {
         this.interfaces = <Reference>[];
       }
       this.interfaces.add(_optionalReference(interface));
     }

     mirror.methods.forEach((childName, childMirror) {
       if (!childMirror.isConstructor && !childMirror.isGetter) {
         addChild(new MethodElement(childName, childMirror, lookupMdnComment));
       }
     });

     mirror.getters.forEach((childName, childMirror) {
       addChild(new GetterElement(childName, childMirror, lookupMdnComment));
     });

     mirror.variables.forEach((childName, childMirror) {
         addChild(new VariableElement(childName, childMirror,
             lookupMdnComment));
     });

     mirror.constructors.forEach((constructorName, methodMirror) {
       addChild(new MethodElement(constructorName, methodMirror,
           lookupMdnComment, 'constructor'));
     });

     for (var typeVariable in mirror.originalDeclaration.typeVariables) {
       addChild(new TypeParameterElement(typeVariable));
     }
   }
 }

 /**
  * [Element] describing a getter.
  */
 class GetterElement extends Element {
   /** Type of the getter. */
   final Reference ref;
   final bool isStatic;

   GetterElement(String name, MethodMirror mirror,
       MdnComment lookupMdnComment(Mirror))
       : super(mirror, 'property', mirror.simpleName, name, computeComment(mirror),
           lookupMdnComment),
         ref = _optionalReference(mirror.returnType),
         isStatic = _optionalBool(mirror.isStatic);
 }

 /**
  * [Element] describing a method which may be a regular method, a setter, or an
  * operator.
  */
 class MethodElement extends Element {
   final Reference returnType;
   final bool isSetter;
   final bool isOperator;
   final bool isStatic;

   MethodElement(String name, MethodMirror mirror,
       MdnComment lookupMdnComment(Mirror), [String kind = 'method'])
       : super(mirror, kind, name, '$name${mirror.parameters.length}()',
               computeComment(mirror), lookupMdnComment),
         returnType = _optionalReference(mirror.returnType),
         isSetter = _optionalBool(mirror.isSetter),
         isOperator = _optionalBool(mirror.isOperator),
         isStatic = _optionalBool(mirror.isStatic) {

     for (var param in mirror.parameters) {
       addChild(new ParameterElement(param));
     }
   }
 }

 /**
  * Element describing a parameter.
  */
 class ParameterElement extends Element {
   /** Type of the parameter. */
   final Reference ref;

   /**
    * Returns the default value for this parameter.
    */
   final String defaultValue;

   /**
    * Is this parameter optional?
    */
   final bool isOptional;

   /**
    * Is this parameter named?
    */
   final bool isNamed;

   /**
    * Returns the initialized field, if this parameter is an initializing formal.
    */
   final Reference initializedField;

   ParameterElement(ParameterMirror mirror)
       : super(mirror, 'param', mirror.simpleName, mirror.simpleName, null,
           null),
         ref = _optionalReference(mirror.type),
         isOptional = _optionalBool(mirror.isOptional),
         defaultValue = mirror.defaultValue,
         isNamed = _optionalBool(mirror.isNamed),
         initializedField = _optionalReference(mirror.initializedField) {

     if (mirror.type is FunctionTypeMirror) {
       addChild(new FunctionTypeElement(mirror.type));
     }
   }
 }

 class FunctionTypeElement extends Element {
   final Reference returnType;

   FunctionTypeElement(FunctionTypeMirror mirror)
       : super(mirror, 'functiontype', mirror.simpleName, mirror.simpleName, null, null),
         returnType = _optionalReference(mirror.returnType) {
     for (var param in mirror.parameters) {
       addChild(new ParameterElement(param));
     }
     // TODO(jacobr): can a FunctionTypeElement really have type variables?
     for (var typeVariable in mirror.originalDeclaration.typeVariables) {
       addChild(new TypeParameterElement(typeVariable));
     }
   }
 }

 /**
  * Element describing a generic type parameter.
  */
 class TypeParameterElement extends Element {
   /**
    * Upper bound for the parameter.
    *
    * In the following code sample, [:Bar:] is an upper bound:
    * [: class Bar<T extends Foo> { } :]
    */
   final Reference upperBound;

   TypeParameterElement(TypeMirror mirror)
       : super(mirror, 'typeparam', mirror.simpleName, mirror.simpleName, null,
           null),
         upperBound = mirror.upperBound != null && !mirror.upperBound.isObject ?
             new Reference(mirror.upperBound) : null;
 }

 /**
  * Element describing a variable.
  */
 class VariableElement extends Element {
   /** Type of the variable. */
   final Reference ref;
   /** Whether the variable is static. */
   final bool isStatic;
   /** Whether the variable is final. */
   final bool isFinal;

   VariableElement(String name, VariableMirror mirror,
       MdnComment lookupMdnComment(Mirror))
       : super(mirror, 'variable', mirror.simpleName, name,
           computeComment(mirror), lookupMdnComment),
         ref = _optionalReference(mirror.type),
         isStatic = _optionalBool(mirror.isStatic),
         isFinal = _optionalBool(mirror.isFinal);
 }

 /**
  * Element describing a typedef.
  */

 class TypedefElement extends Element {
   /** Return type of the typedef. */
   final Reference returnType;

   TypedefElement(String name, TypedefMirror mirror)
       : super(mirror, 'typedef', mirror.simpleName, name,
                computeComment(mirror), null),
         returnType = _optionalReference(mirror.value.returnType) {
     for (var param in mirror.value.parameters) {
       addChild(new ParameterElement(param));
     }
     for (var typeVariable in mirror.originalDeclaration.typeVariables) {
       addChild(new TypeParameterElement(typeVariable));
     }
   }
 }

 /**
  * Reference to an Element with type argument if the reference is parameterized.
  */
 class Reference {
   final String name;
   final String refId;
   List<Reference> arguments;

   Reference(Mirror mirror)
       : name = mirror.displayName,
         refId = getId(mirror) {
     if (mirror is ClassMirror) {
       if (mirror is !TypedefMirror && !mirror.typeArguments.isEmpty) {
         arguments = <Reference>[];
         for (var typeArg in mirror.typeArguments) {
           arguments.add(_optionalReference(typeArg));
         }
       }
     }
   }

   // TODO(jacobr): compute the referenceId correctly for the general case so
   // that this method can work with all element types not just LibraryElements.
   Reference.fromElement(LibraryElement e) : name = e.name, refId = e.id;

   static String getId(Mirror mirror) {
     String id = _escapeId(mirror.simpleName);
     if (mirror.owner != null) {
       id = '${getId(mirror.owner)}/$id';
     }
     return id;
   }
 }
	// 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 library serializes the Dart2Js AST into a compact and easy to use
	* [Element] tree useful for code exploration tools such as DartDoc.
	*/
	library universe_serializer;

	import '../../compiler/implementation/mirrors/mirrors.dart';
	import '../../compiler/implementation/mirrors/mirrors_util.dart';
	import '../../compiler/implementation/mirrors/dart2js_mirror.dart' as dart2js;
	import '../../libraries.dart';
	import 'dartdoc.dart';

	String _stripUri(String uri) {
	String prefix = "/dart/";
	int start = uri.indexOf(prefix);
	if (start != -1) {
	return uri.substring(start + prefix.length);
	} else {
	return uri;
	}
	}

	String _escapeId(String id) {
	return id.replaceAll(new RegExp('[/]'), '#slash');
	}

	/**
	* Base class for all elements in the AST.
	*/
	class Element {
	/** Human readable type name for the node. */
	final String kind;
	/** Human readable name for the element. */
	final String name;
	/** Id for the node that is unique within its parent's children. */
	final String id;
	/** Raw text of the comment associated with the Element if any. */
	final String comment;
	/** Raw html comment for the Element from MDN. */
	String mdnCommentHtml;
	/**
	* The URL to the page on MDN that content was pulled from for the current
	* type being documented. Will be `null` if the type doesn't use any MDN
	* content.
	*/
	String mdnUrl;
	/** Children of the node. */
	List<Element> children;
	/** Whether the element is private. */
	final bool isPrivate;

	/**
	* Uri containing the definition of the element.
	*/
	String uri;
	/**
	* Line in the original source file that starts the definition of the element.
	*/
	String line;

	// TODO(jacobr): refactor the code so that lookupMdnComment does not need to
	// be passed to every Element constructor.
	Element(Mirror mirror, this.kind, this.name, String id, this.comment,
	MdnComment lookupMdnComment(Mirror))
	: line = mirror.location.line.toString(),
	id = _escapeId(id),
	isPrivate = _optionalBool(mirror.isPrivate),
	uri = _stripUri(mirror.location.sourceUri.toString()) {
	if (lookupMdnComment != null) {
	var mdnComment = lookupMdnComment(mirror);
	if (mdnComment != null) {
	mdnCommentHtml = mdnComment.mdnComment;
	mdnUrl = mdnComment.mdnUrl;
	}
	}
	}

	void addChild(Element child) {
	if (children == null) {
	children = <Element>[];
	}
	children.add(child);
	}

	/**
	* Remove all URIs that exactly match the parent node's URI.
	* This reduces output file size by about 20%.
	*/
	void stripDuplicateUris(String parentUri, parentLine) {
	if (children != null) {
	for (var child in children) {
	child.stripDuplicateUris(uri, line);
	}
	}
	if (parentUri == uri) {
	uri = null;
	}
	if (line == parentLine) {
	line = null;
	}
	}
	}

	/**
	* Converts false to null. Useful as the serialization scheme we use
	* omits null values.
	*/
	bool _optionalBool(bool value) => value == true ? true : null;

	Reference _optionalReference(Mirror mirror) {
	return (mirror != null && mirror.simpleName != "Dynamic_" &&
	mirror.simpleName != "dynamic") ?
	new Reference(mirror) : null;
	}

	/**
	* Helper class to track what members of a library should be included.
	*/
	class LibrarySubset {
	final LibraryMirror library;
	Set<String> includedChildren;

	LibrarySubset(this.library) : includedChildren = new Set<String>();
	}

	/**
	* [Element] describing a Dart library.
	*/
	class LibraryElement extends Element {
	/**
	* Partial versions of LibraryElements containing classes that are extended
	* or implemented by classes in this library.
	*/
	List<LibraryElement> dependencies;

	/**
	* Construct a LibraryElement from a [mirror].
	*
	* If [includedChildren] is specified, only elements matching names in
	* [includedChildren] are included and no dependencies are included.
	* [lookupMdnComment] is an optional function that returns the MDN
	* documentation for elements. [dependencies] is an optional map
	* tracking all classes dependend on by this [ClassElement].
	*/
	LibraryElement(LibraryMirror mirror,
	{MdnComment lookupMdnComment(Mirror), Set<String> includedChildren})
	: super(mirror, 'library', _libraryName(mirror), mirror.displayName,
	computeComment(mirror), lookupMdnComment) {
	var requiredDependencies;
	// We don't need to track our required dependencies when generating a
	// filtered version of this library which will be used as a dependency for
	// another library.
	if (includedChildren == null)
	requiredDependencies = new Map<String, LibrarySubset>();
	mirror.functions.forEach((childName, childMirror) {
	if (includedChildren == null \|\| includedChildren.contains(childName))
	addChild(new MethodElement(childName, childMirror, lookupMdnComment));
	});

	mirror.getters.forEach((childName, childMirror) {
	if (includedChildren == null \|\| includedChildren.contains(childName))
	addChild(new GetterElement(childName, childMirror, lookupMdnComment));
	});

	mirror.variables.forEach((childName, childMirror) {
	if (includedChildren == null \|\| includedChildren.contains(childName))
	addChild(new VariableElement(childName, childMirror, lookupMdnComment));
	});

	mirror.classes.forEach((className, classMirror) {
	if (includedChildren == null \|\| includedChildren.contains(className)) {
	if (classMirror is TypedefMirror) {
	addChild(new TypedefElement(className, classMirror));
	} else {
	addChild(new ClassElement(classMirror,
	dependencies: requiredDependencies,
	lookupMdnComment: lookupMdnComment));
	}
	}
	});

	if (requiredDependencies != null && !requiredDependencies.isEmpty) {
	dependencies = requiredDependencies.values.map((librarySubset) =>
	new LibraryElement(
	librarySubset.library,
	lookupMdnComment: lookupMdnComment,
	includedChildren: librarySubset.includedChildren)).toList();
	}
	}

	static String _libraryName(LibraryMirror mirror) {
	if (mirror.uri.scheme == 'file') {
	// TODO(jacobr): this is a hack. Remove once these libraries are removed
	// from the sdk.
	var uri = mirror.uri;
	var path = uri.path;
	var pattern = new RegExp(r'[\\/]dart[\\/]pkg[\\/]([^\\/]+)[\\/]lib[\\/](.+)$');
	var match = pattern.firstMatch(path);
	var package;
	if (match != null) {
	package = match.group(1);
	path = match.group(2);
	}
	// TODO(jacobr): add a second pattern for a more typical pub environment.
	if (package != null) {
	return 'package:$package/$path';
	} else {
	// TODO(jacobr): this is a lousy fallback.
	print("Unable to determine package for $path.");
	return mirror.uri.toString();
	}
	} else {
	return mirror.uri.toString();
	}
	}

	void stripDuplicateUris(String parentUri, parentLine) {
	super.stripDuplicateUris(parentUri, parentLine);

	if (dependencies != null) {
	for (var child in dependencies) {
	child.stripDuplicateUris(null, null);
	}
	}
	}
	}

	/**
	* Returns whether the class implements or extends [Error] or [Exception].
	*/
	bool _isThrowable(ClassMirror mirror) {
	if (mirror.library.uri.toString() == 'dart:core' &&
	mirror.simpleName == 'Error' \|\| mirror.simpleName == 'Exception')
	return true;
	if (mirror.superclass != null && _isThrowable(mirror.superclass))
	return true;
	return mirror.superinterfaces.any(_isThrowable);
	}

	/**
	* [Element] describing a Dart class.
	*/
	class ClassElement extends Element {
	/** Base class.*/
	final Reference superclass;
	/** Whether the class is abstract. */
	final bool isAbstract;
	/** Interfaces the class implements. */
	List<Reference> interfaces;
	/** Whether the class implements or extends [Error] or [Exception]. */
	bool isThrowable;

	/**
	* Constructs a [ClassElement] from a [ClassMirror].
	*
	* [dependencies] is an optional map updated as a side effect of running
	* this constructor that tracks what classes from other libraries are
	* dependencies of classes in this library. A class is considered a
	* dependency if it implements or extends another class.
	* [lookupMdnComment] is an optional function that returns the MDN
	* documentation for elements. [dependencies] is an optional map
	* tracking all classes dependend on by this [ClassElement].
	*/
	ClassElement(ClassMirror mirror,
	{Map<String, LibrarySubset> dependencies,
	MdnComment lookupMdnComment(Mirror)})
	: super(mirror, 'class', mirror.simpleName, mirror.simpleName, computeComment(mirror),
	lookupMdnComment),
	superclass = _optionalReference(mirror.superclass),
	isAbstract = _optionalBool(mirror.isAbstract),
	isThrowable = _optionalBool(_isThrowable(mirror)){

	addCrossLibraryDependencies(clazz) {
	if (clazz == null) return;

	if (mirror.library != clazz.library) {
	var libraryStub = dependencies.putIfAbsent(clazz.library.simpleName,
	() => new LibrarySubset(clazz.library));
	libraryStub.includedChildren.add(clazz.simpleName);
	}

	for (var interface in clazz.superinterfaces) {
	addCrossLibraryDependencies(interface);
	}
	addCrossLibraryDependencies(clazz.superclass);
	}

	if (dependencies != null) {
	addCrossLibraryDependencies(mirror);
	}

	for (var interface in mirror.superinterfaces) {
	if (this.interfaces == null) {
	this.interfaces = <Reference>[];
	}
	this.interfaces.add(_optionalReference(interface));
	}

	mirror.methods.forEach((childName, childMirror) {
	if (!childMirror.isConstructor && !childMirror.isGetter) {
	addChild(new MethodElement(childName, childMirror, lookupMdnComment));
	}
	});

	mirror.getters.forEach((childName, childMirror) {
	addChild(new GetterElement(childName, childMirror, lookupMdnComment));
	});

	mirror.variables.forEach((childName, childMirror) {
	addChild(new VariableElement(childName, childMirror,
	lookupMdnComment));
	});

	mirror.constructors.forEach((constructorName, methodMirror) {
	addChild(new MethodElement(constructorName, methodMirror,
	lookupMdnComment, 'constructor'));
	});

	for (var typeVariable in mirror.originalDeclaration.typeVariables) {
	addChild(new TypeParameterElement(typeVariable));
	}
	}
	}

	/**
	* [Element] describing a getter.
	*/
	class GetterElement extends Element {
	/** Type of the getter. */
	final Reference ref;
	final bool isStatic;

	GetterElement(String name, MethodMirror mirror,
	MdnComment lookupMdnComment(Mirror))
	: super(mirror, 'property', mirror.simpleName, name, computeComment(mirror),
	lookupMdnComment),
	ref = _optionalReference(mirror.returnType),
	isStatic = _optionalBool(mirror.isStatic);
	}

	/**
	* [Element] describing a method which may be a regular method, a setter, or an
	* operator.
	*/
	class MethodElement extends Element {
	final Reference returnType;
	final bool isSetter;
	final bool isOperator;
	final bool isStatic;

	MethodElement(String name, MethodMirror mirror,
	MdnComment lookupMdnComment(Mirror), [String kind = 'method'])
	: super(mirror, kind, name, '$name${mirror.parameters.length}()',
	computeComment(mirror), lookupMdnComment),
	returnType = _optionalReference(mirror.returnType),
	isSetter = _optionalBool(mirror.isSetter),
	isOperator = _optionalBool(mirror.isOperator),
	isStatic = _optionalBool(mirror.isStatic) {

	for (var param in mirror.parameters) {
	addChild(new ParameterElement(param));
	}
	}
	}

	/**
	* Element describing a parameter.
	*/
	class ParameterElement extends Element {
	/** Type of the parameter. */
	final Reference ref;

	/**
	* Returns the default value for this parameter.
	*/
	final String defaultValue;

	/**
	* Is this parameter optional?
	*/
	final bool isOptional;

	/**
	* Is this parameter named?
	*/
	final bool isNamed;

	/**
	* Returns the initialized field, if this parameter is an initializing formal.
	*/
	final Reference initializedField;

	ParameterElement(ParameterMirror mirror)
	: super(mirror, 'param', mirror.simpleName, mirror.simpleName, null,
	null),
	ref = _optionalReference(mirror.type),
	isOptional = _optionalBool(mirror.isOptional),
	defaultValue = mirror.defaultValue,
	isNamed = _optionalBool(mirror.isNamed),
	initializedField = _optionalReference(mirror.initializedField) {

	if (mirror.type is FunctionTypeMirror) {
	addChild(new FunctionTypeElement(mirror.type));
	}
	}
	}

	class FunctionTypeElement extends Element {
	final Reference returnType;

	FunctionTypeElement(FunctionTypeMirror mirror)
	: super(mirror, 'functiontype', mirror.simpleName, mirror.simpleName, null, null),
	returnType = _optionalReference(mirror.returnType) {
	for (var param in mirror.parameters) {
	addChild(new ParameterElement(param));
	}
	// TODO(jacobr): can a FunctionTypeElement really have type variables?
	for (var typeVariable in mirror.originalDeclaration.typeVariables) {
	addChild(new TypeParameterElement(typeVariable));
	}
	}
	}

	/**
	* Element describing a generic type parameter.
	*/
	class TypeParameterElement extends Element {
	/**
	* Upper bound for the parameter.
	*
	* In the following code sample, [:Bar:] is an upper bound:
	* [: class Bar<T extends Foo> { } :]
	*/
	final Reference upperBound;

	TypeParameterElement(TypeMirror mirror)
	: super(mirror, 'typeparam', mirror.simpleName, mirror.simpleName, null,
	null),
	upperBound = mirror.upperBound != null && !mirror.upperBound.isObject ?
	new Reference(mirror.upperBound) : null;
	}

	/**
	* Element describing a variable.
	*/
	class VariableElement extends Element {
	/** Type of the variable. */
	final Reference ref;
	/** Whether the variable is static. */
	final bool isStatic;
	/** Whether the variable is final. */
	final bool isFinal;

	VariableElement(String name, VariableMirror mirror,
	MdnComment lookupMdnComment(Mirror))
	: super(mirror, 'variable', mirror.simpleName, name,
	computeComment(mirror), lookupMdnComment),
	ref = _optionalReference(mirror.type),
	isStatic = _optionalBool(mirror.isStatic),
	isFinal = _optionalBool(mirror.isFinal);
	}

	/**
	* Element describing a typedef.
	*/

	class TypedefElement extends Element {
	/** Return type of the typedef. */
	final Reference returnType;

	TypedefElement(String name, TypedefMirror mirror)
	: super(mirror, 'typedef', mirror.simpleName, name,
	computeComment(mirror), null),
	returnType = _optionalReference(mirror.value.returnType) {
	for (var param in mirror.value.parameters) {
	addChild(new ParameterElement(param));
	}
	for (var typeVariable in mirror.originalDeclaration.typeVariables) {
	addChild(new TypeParameterElement(typeVariable));
	}
	}
	}

	/**
	* Reference to an Element with type argument if the reference is parameterized.
	*/
	class Reference {
	final String name;
	final String refId;
	List<Reference> arguments;

	Reference(Mirror mirror)
	: name = mirror.displayName,
	refId = getId(mirror) {
	if (mirror is ClassMirror) {
	if (mirror is !TypedefMirror && !mirror.typeArguments.isEmpty) {
	arguments = <Reference>[];
	for (var typeArg in mirror.typeArguments) {
	arguments.add(_optionalReference(typeArg));
	}
	}
	}
	}

	// TODO(jacobr): compute the referenceId correctly for the general case so
	// that this method can work with all element types not just LibraryElements.
	Reference.fromElement(LibraryElement e) : name = e.name, refId = e.id;

	static String getId(Mirror mirror) {
	String id = _escapeId(mirror.simpleName);
	if (mirror.owner != null) {
	id = '${getId(mirror.owner)}/$id';
	}
	return id;
	}
	}