Refactor scripts, so we have a single entrypoint, dartdoc.py, to generate docs.

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.
- */
+/// **docgen** is a tool for creating machine readable representations of Dart

[Emily Fortuna, 2013/11/01 22:34:46]

there was a mixture of /// and /** throughout this file. I made them all
consistent.

+/// 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'
     as dart2js;
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart';
 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]';
+const String USAGE = 'Usage: dart docgen.dart [OPTIONS] fooDir/barFile';
 
 
-List<String> validAnnotations = const ['metadata.Experimental',
-    'metadata.DomName', 'metadata.Deprecated', 'metadata.Unstable',
-    'meta.deprecated', 'metadata.SupportedBrowser'];
+List<String> skippedAnnotations = const [
+    'metadata.DocsEditable', 'metadata.DomName'];
 
 /// 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;
 
 /// 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.
 Map<String, Indexable> entityMap = new Map<String, Indexable>();
 
 /// This is set from the command line arguments flag --include-private
 bool _includePrivate = false;
 
 // TODO(janicejl): Make MDN content generic or pluggable. Maybe move
 // MDN-specific code to its own library that is imported into the default impl?
 /// Map of all the comments for dom elements from MDN.
 Map _mdn;
 
-/**
- * Docgen constructor initializes the link resolver for markdown parsing.
- * Also initializes the command line arguments.
- *
- * [packageRoot] is the packages directory of the directory being analyzed.
- * If [includeSdk] is `true`, then any SDK libraries explicitly imported will
- * also be documented.
- * If [parseSdk] is `true`, then all Dart SDK libraries will be documented.
- * This option is useful when only the SDK libraries are needed.
- *
- * Returns `true` if docgen sucessfuly completes.
- */
+/// Docgen constructor initializes the link resolver for markdown parsing.
+/// Also initializes the command line arguments.
+///
+/// [packageRoot] is the packages directory of the directory being analyzed.
+/// If [includeSdk] is `true`, then any SDK libraries explicitly imported will
+/// also be documented.
+/// If [parseSdk] is `true`, then all Dart SDK libraries will be documented.
+/// This option is useful when only the SDK libraries are needed.
+///
+/// Returned Future completes with true if document generation is successful.
 Future<bool> docgen(List<String> files, {String packageRoot,
     bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false,
     bool parseSdk: false, bool append: false, String introduction: ''}) {
   _includePrivate = includePrivate;
   if (!append) {
     var dir = new Directory('docs');
     if (dir.existsSync()) dir.deleteSync(recursive: true);
   }
 
   if (packageRoot == null && !parseSdk) {
     var type = FileSystemEntity.typeSync(files.first);
     if (type == FileSystemEntityType.DIRECTORY) {
       packageRoot = _findPackageRoot(files.first);
     } else if (type == FileSystemEntityType.FILE) {
       logger.warning('WARNING: No package root defined. If Docgen fails, try '
           'again by setting the --package-root option.');
     }
   }
   logger.info('Package Root: ${packageRoot}');
   linkResolver = (name) =>
       fixReference(name, _currentLibrary, _currentClass, _currentMember);
 
   return getMirrorSystem(files, packageRoot: packageRoot, parseSdk: parseSdk)
     .then((MirrorSystem mirrorSystem) {
       if (mirrorSystem.libraries.isEmpty) {
         throw new StateError('No library mirrors were created.');
       }
       var librariesWeAskedFor = _listLibraries(files);
-      var librariesWeGot = mirrorSystem.libraries.values.where((each)
-          => each.uri.scheme == 'file');
+      var librariesWeGot = mirrorSystem.libraries.values.where(
+          (each) => each.uri.scheme == 'file');
       var sdkLibraries = mirrorSystem.libraries.values.where(
           (each) => each.uri.scheme == 'dart');
       var librariesWeGotByPath = new Map.fromIterables(
           librariesWeGot.map((each) => each.uri.toFilePath()),
           librariesWeGot);
-      var librariesToDocument = librariesWeAskedFor.map((each) =>
-        librariesWeGotByPath
-            .putIfAbsent(each, () => throw "Missing library $each")).toList();
+      var librariesToDocument = librariesWeAskedFor.map(
+          (each) => librariesWeGotByPath.putIfAbsent(each,
+              () => throw "Missing library $each")).toList();
       librariesToDocument.addAll((includeSdk || parseSdk) ? sdkLibraries : []);
       _documentLibraries(librariesToDocument, includeSdk: includeSdk,
           outputToYaml: outputToYaml, append: append, parseSdk: parseSdk,
           introduction: introduction);
       return true;
     });
 }
 
 /// For a [library] and its corresponding [mirror] that we believe come
 /// from a package (because it has a file
@@ skipping 77 matching lines @@
   var files = listDir(directory, recursive: true);
   // Return '' means that there was no pubspec.yaml and therefor no packageRoot.
   String packageRoot = files.firstWhere((f) =>
       f.endsWith('${path.separator}pubspec.yaml'), orElse: () => '');
   if (packageRoot != '') {
     packageRoot = path.join(path.dirname(packageRoot), 'packages');
   }
   return packageRoot;
 }
 
-/**
- * Read a pubspec and return the library name.
- */
+/// Read a pubspec and return the library name.
 String _packageName(String pubspecName) {
   File pubspec = new File(pubspecName);
   if (!pubspec.existsSync()) return '';
   var contents = pubspec.readAsStringSync();
   var spec = loadYaml(contents);
   return spec["name"];
 }
 
 List<String> _listSdk() {
   var sdk = new List<String>();
   LIBRARIES.forEach((String name, LibraryInfo info) {
     if (info.documented) {
       sdk.add('dart:$name');
       logger.info('Add to SDK: ${sdk.last}');
     }
   });
   return sdk;
 }
 
-/**
- * Analyzes set of libraries by getting a mirror system and triggers the
- * documentation of the libraries.
- */
+/// Analyzes set of libraries by getting a mirror system and triggers the
+/// documentation of the libraries.
 Future<MirrorSystem> getMirrorSystem(List<String> args, {String packageRoot,
     bool parseSdk: false}) {
   var libraries = !parseSdk ? _listLibraries(args) : _listSdk();
   if (libraries.isEmpty) throw new StateError('No Libraries.');
   // Finds the root of SDK library based off the location of docgen.
 
   var root = findRootDirectory();
   var sdkRoot = path.normalize(path.absolute(path.join(root, 'sdk')));
   logger.info('SDK Root: ${sdkRoot}');
   return _analyzeLibraries(libraries, sdkRoot, packageRoot: packageRoot);
 }
 
 String findRootDirectory() {
   var scriptDir = path.absolute(path.dirname(Platform.script.toFilePath()));
   var root = scriptDir;
   while(path.basename(root) != 'dart') {
     root = path.dirname(root);
   }
   return root;
 }
 
-/**
- * Analyzes set of libraries and provides a mirror system which can be used
- * for static inspection of the source code.
- */
+/// Analyzes set of libraries and provides a mirror system which can be used
+/// for static inspection of the source code.
 Future<MirrorSystem> _analyzeLibraries(List<String> libraries,
       String libraryRoot, {String packageRoot}) {
   SourceFileProvider provider = new CompilerSourceFileProvider();
   api.DiagnosticHandler diagnosticHandler =
       (new FormattingDiagnosticHandler(provider)
         ..showHints = false
         ..showWarnings = false)
           .diagnosticHandler;
   Uri libraryUri = new Uri(scheme: 'file', path: appendSlash(libraryRoot));
   Uri packageUri = null;
@@ skipping 10 matching lines @@
       ..catchError((error) {
         logger.severe('Error: Failed to create mirror system. ');
         // TODO(janicejl): Use the stack trace package when bug is resolved.
         // Currently, a string is thrown when it fails to create a mirror
         // system, and it is not possible to use the stack trace. BUG(#11622)
         // To avoid printing the stack trace.
         exit(1);
       });
 }
 
-/**
- * Creates documentation for filtered libraries.
- */
+/// Creates documentation for filtered libraries.
 void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false,
     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;
     }
   });
@@ skipping 77 matching lines @@
   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
- */
+/// 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];
   if (sdkLibrary != null) {
     return !sdkLibrary.documented;
   } else if (mirror.simpleName.startsWith('_') ||
       mirror.simpleName.contains('._')) {
     return true;
   }
   return false;
 }
 
-/**
- * A declaration is private if itself is private, or the owner is private.
- */
+/// 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.
- */
+/// 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
       .where((e) => e.isFinal)
       .map((e) => annotation.getField(e.simpleName).reflectee)
       .where((e) => e != null)
       .toList();
-    if (validAnnotations.contains(docName(annotation.type))) {
+    if (!skippedAnnotations.contains(docName(annotation.type))) {
       annotations.add(new Annotation(docName(annotation.type),
           parameterList));
     }
   });
   return annotations;
 }
 
-/**
- * Returns any documentation comments associated with a mirror with
- * simple markdown converted to html.
- */
+/// Returns any documentation comments associated with a mirror with
+/// simple markdown converted to html.
 String _commentToHtml(DeclarationMirror mirror) {
   String commentText;
   mirror.metadata.forEach((metadata) {
     if (metadata is CommentInstanceMirror) {
       CommentInstanceMirror comment = metadata;
       if (comment.isDocComment) {
         if (commentText == null) {
           commentText = comment.trimmedText;
         } else {
           commentText = '$commentText ${comment.trimmedText}';
         }
       }
     }
   });
 
   commentText = commentText == null ? '' :
       markdown.markdownToHtml(commentText.trim(), linkResolver: linkResolver,
           inlineSyntaxes: markdownSyntaxes);
   return commentText;
 }
 
-/**
- * Generates MDN comments from database.json.
- */
+/// Generates MDN comments from database.json.
 void _mdnComment(Indexable item) {
   //Check if MDN is loaded.
   if (_mdn == null) {
     // Reading in MDN related json file.
     var root = findRootDirectory();
     var mdnPath = path.join(root, 'utils/apidoc/mdn/database.json');
     _mdn = JSON.decode(new File(mdnPath).readAsStringSync());
   }
   if (item.comment.isNotEmpty) return;
   var domAnnotation = item.annotations.firstWhere(
       (e) => e.qualifiedName == 'metadata.DomName', orElse: () => null);
   if (domAnnotation == null) return;
   var domName = domAnnotation.parameters.single;
   var parts = domName.split('.');
   if (parts.length == 2) item.comment = _mdnMemberComment(parts[0], parts[1]);
   if (parts.length == 1) item.comment = _mdnTypeComment(parts[0]);
 }
 
-/**
- * Generates the MDN Comment for variables and method DOM elements.
- */
+/// Generates the MDN Comment for variables and method DOM elements.
 String _mdnMemberComment(String type, String member) {
   var mdnType = _mdn[type];
   if (mdnType == null) return '';
   var mdnMember = mdnType['members'].firstWhere((e) => e['name'] == member,
       orElse: () => null);
   if (mdnMember == null) return '';
   if (mdnMember['help'] == null || mdnMember['help'] == '') return '';
   if (mdnMember['url'] == null) return '';
   return _htmlMdn(mdnMember['help'], mdnMember['url']);
 }
 
-/**
- * Generates the MDN Comment for class DOM elements.
- */
+/// Generates the MDN Comment for class DOM elements.
 String _mdnTypeComment(String type) {
   var mdnType = _mdn[type];
   if (mdnType == null) return '';
   if (mdnType['summary'] == null || mdnType['summary'] == "") return '';
   if (mdnType['srcUrl'] == null) return '';
   return _htmlMdn(mdnType['summary'], mdnType['srcUrl']);
 }
 
 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>';
 }
 
-/**
- * Converts all [foo] references in comments to <a>libraryName.foo</a>.
- */
+/// Converts all [foo] references in comments to <a>libraryName.foo</a>.
 markdown.Node fixReference(String name, LibraryMirror currentLibrary,
     ClassMirror currentClass, MemberMirror currentMember) {
   var reference;
   var memberScope = currentMember == null ?
       null : currentMember.lookupInScope(name);
   if (memberScope != null) {
     reference = docName(memberScope);
   } else {
     var classScope = currentClass == null ?
         null : currentClass.lookupInScope(name);
     if (classScope != null) {
       reference = docName(classScope);
     } else {
       var libraryScope = currentLibrary == null ?
           null : currentLibrary.lookupInScope(name);
       reference = libraryScope != null ? docName(libraryScope) : name;
     }
   }
   return new markdown.Element.text('a', reference);
 }
 
-/**
- * Returns a map of [Variable] objects constructed from [mirrorMap].
- */
+/// Returns a map of [Variable] objects constructed from [mirrorMap].
 Map<String, Variable> _variables(Map<String, VariableMirror> mirrorMap) {
   var data = {};
   // TODO(janicejl): When map to map feature is created, replace the below with
   // a filter. Issue(#9590).
   mirrorMap.forEach((String mirrorName, VariableMirror mirror) {
     _currentMember = mirror;
     if (_includePrivate || !_isHidden(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].
- */
+/// Returns a map of [Method] objects constructed from [mirrorMap].
 MethodGroup _methods(Map<String, MethodMirror> mirrorMap) {
   var group = new MethodGroup();
   mirrorMap.forEach((String mirrorName, 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.
- */
+/// Returns the [Class] for the given [mirror] has already been created, and if
+/// it does not exist, creates it.
 Class _class(ClassMirror mirror) {
   var clazz = entityMap[docName(mirror)];
   if (clazz == null) {
     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),
         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].
- */
+/// Returns a map of [Class] objects constructed from [mirrorMap].
 ClassGroup _classes(Map<String, ClassMirror> mirrorMap) {
   var group = new ClassGroup();
   mirrorMap.forEach((String mirrorName, ClassMirror mirror) {
       group.addClass(mirror);
   });
   return group;
 }
 
-/**
- * Returns a map of [Parameter] objects constructed from [mirrorList].
- */
+/// Returns a map of [Parameter] objects constructed from [mirrorList].
 Map<String, Parameter> _parameters(List<ParameterMirror> mirrorList) {
   var data = {};
   mirrorList.forEach((ParameterMirror mirror) {
     _currentMember = mirror;
     data[mirror.simpleName] = new Parameter(mirror.simpleName,
         mirror.isOptional, mirror.isNamed, mirror.hasDefaultValue,
         _type(mirror.type), mirror.defaultValue,
         _annotations(mirror));
   });
   return data;
 }
 
-/**
- * Returns a map of [Generic] objects constructed from the class mirror.
- */
+/// Returns a map of [Generic] objects constructed from the class mirror.
 Map<String, Generic> _generics(ClassMirror 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.
- */
+/// 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.
- */
+/// Returns a list of [Type] objects constructed from TypeMirrors.
 List<Type> _typeGenerics(TypeMirror mirror) {
   if (mirror is ClassMirror && !mirror.isTypedef) {
     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.
- */
+/// Writes text to a file in the 'docs' directory.
 void _writeToFile(String text, String filename, {bool append: false}) {
   Directory dir = new Directory('docs');
   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('docs', path.dirname(filename)));
     if (!subdir.existsSync()) {
       subdir.createSync();
     }
   }
 
   File file = new File('docs/$filename');
   if (!file.existsSync()) {
     file.createSync();
   }
   file.writeAsStringSync(text, mode: append ? FileMode.APPEND : FileMode.WRITE);
 }
 
-/**
- * Transforms the map by calling toMap on each value in it.
- */
+/// Transforms the map by calling toMap on each value in it.
 Map recurseMap(Map inputMap) {
   var outputMap = {};
   inputMap.forEach((key, value) {
     if (value is Map) {
       outputMap[key] = recurseMap(value);
     } else {
       outputMap[key] = value.toMap();
     }
   });
   return outputMap;
 }
 
-/**
- * A class representing all programming constructs, like library or class.
- */
+/// A class representing all programming constructs, like library or class.
 class Indexable {
   String name;
   String get qualifiedName => fileName;
   bool isPrivate;
 
   // 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 => packagePrefix + ownerPrefix + name;
 
@@ skipping 11 matching lines @@
 
   /// Qualified Name of the owner of this Indexable Item.
   /// For Library, owner will be "";
   String owner;
 
   Indexable(this.name, this.comment, this.isPrivate, this.owner);
 
   /// The type of this member to be used in index.txt.
   String get typeName => '';
 
-  /**
-   * Creates a [Map] with this [Indexable]'s name and a preview comment.
-   */
+  /// Creates a [Map] with this [Indexable]'s name and a preview comment.
   Map get previewMap {
     var finalMap = { 'name' : name, 'qualifiedName' : qualifiedName };
     if (comment != '') {
       var index = comment.indexOf('</p>');
       finalMap['preview'] = '${comment.substring(0, index)}</p>';
     }
     return finalMap;
   }
 
   /// Return an informative [Object.toString] for debugging.
   String toString() => "${super.toString()}(${name.toString()})";
 
   /// Return a map representation of this type.
   Map toMap() {}
 }
 
-/**
- * A class containing contents of a Dart library.
- */
+/// A class containing contents of a Dart library.
 class Library extends Indexable {
 
   /// Top-level variables in the library.
   Map<String, Variable> variables;
 
   /// Top-level functions in the library.
   MethodGroup functions;
 
   /// Classes defined within the library
   ClassGroup classes;
@@ skipping 27 matching lines @@
     'variables': recurseMap(variables),
     'functions': functions.toMap(),
     'classes': classes.toMap(),
     'packageName': packageName,
     'packageIntro' : packageIntro
   };
 
   String get typeName => 'library';
 }
 
-/**
- * A class containing contents of a Dart class.
- */
+/// A class containing contents of a Dart class.
 class Class extends Indexable {
 
   /// List of the names of interfaces that this class implements.
   List<Class> interfaces = [];
 
   /// Names of classes that extends or implements this class.
   Set<String> subclasses = new Set<String>();
 
   /// Top-level variables in the class.
   Map<String, Variable> variables;
@@ skipping 18 matching lines @@
 
   Class(String name, this.superclass, String comment, this.interfaces,
       this.variables, this.methods, this.annotations, this.generics,
       String qualifiedName, bool isPrivate, String owner, this.isAbstract)
       : super(name, comment, isPrivate, owner) {
     _mdnComment(this);
   }
 
   String get typeName => 'class';
 
-  /**
-   * Returns a list of all the parent classes.
-   */
+  /// Returns a list of all the parent classes.
   List<Class> parent() {
     var parent = superclass == null ? [] : [superclass];
     parent.addAll(interfaces);
     return parent;
   }
 
-  /**
-   * Add all inherited variables and methods from the provided superclass.
-   * If [_includePrivate] is true, it also adds the variables and methods from
-   * the superclass.
-   */
+  /// Add all inherited variables and methods from the provided superclass.
+  /// If [_includePrivate] is true, it also adds the variables and methods from
+  /// the superclass.
   void addInherited(Class superclass) {
     inheritedVariables.addAll(superclass.inheritedVariables);
     inheritedVariables.addAll(superclass.variables);
     inheritedMethods.addInherited(superclass);
   }
 
-  /**
-   * Add the subclass to the class.
-   *
-   * If [this] is private, it will add the subclass to the list of subclasses in
-   * the superclasses.
-   */
+  /// Add the subclass to the class.
+  ///
+  /// If [this] is private, it will add the subclass to the list of subclasses in
+  /// the superclasses.
   void addSubclass(Class subclass) {
     if (!_includePrivate && isPrivate) {
       if (superclass != null) superclass.addSubclass(subclass);
       interfaces.forEach((interface) {
         interface.addSubclass(subclass);
       });
     } else {
       subclasses.add(subclass.qualifiedName);
     }
   }
 
-  /**
-   * Check if this [Class] is an error or exception.
-   */
+  /// Check if this [Class] is an error or exception.
   bool isError() {
     if (qualifiedName == 'dart-core.Error' ||
         qualifiedName == 'dart-core.Exception')
       return true;
     for (var interface in interfaces) {
       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.
-   */
+  /// 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() {
     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(entityMap[subclass]));
     }
   }
 
-  /**
-   * Makes sure that all methods with inherited equivalents have comments.
-   */
+  /// Makes sure that all methods with inherited equivalents have comments.
   void ensureComments() {
     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(),
     '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.
- */
+/// 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) {
     _currentClass = mirror;
     if (mirror.isTypedef) {
       // This is actually a Dart2jsTypedefMirror, and it does define value,
       // but we don't have visibility to that type.
@@ skipping 21 matching lines @@
       if (clazz.isError()) {
         errors[mirror.simpleName] = clazz;
       } else if (mirror.isClass) {
         classes[mirror.simpleName] = clazz;
       } else {
         throw new ArgumentError('${mirror.simpleName} - no class type match. ');
       }
     }
   }
 
-  /**
-   * Checks if the given name is a key for any of the Class Maps.
-   */
+  /// 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)
       .map((e) => e.previewMap).toList(),
     'typedef': recurseMap(typedefs),
     'error': errors.values.where(_isVisible)
       .map((e) => e.previewMap).toList()
@@ skipping 22 matching lines @@
     'comment': comment,
     'return': returnType,
     'parameters': recurseMap(parameters),
     'annotations': annotations.map((a) => a.toMap()).toList(),
     'generics': recurseMap(generics)
   };
 
   String get typeName => 'typedef';
 }
 
-/**
- * A class containing properties of a Dart variable.
- */
+/// A class containing properties of a Dart variable.
 class Variable extends Indexable {
 
   bool isFinal;
   bool isStatic;
   bool isConst;
   Type type;
 
   /// List of the meta annotations on the variable.
   List<Annotation> annotations;
 
@@ skipping 11 matching lines @@
     'final': isFinal.toString(),
     'static': isStatic.toString(),
     'constant': isConst.toString(),
     'type': new List.filled(1, type.toMap()),
     'annotations': annotations.map((a) => a.toMap()).toList()
   };
 
   String get typeName => 'property';
 }
 
-/**
- * A class containing properties of a Dart method.
- */
+/// 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;
   bool isGetter;
   bool isSetter;
   bool isOperator;
   Type returnType;
 
   /// Qualified name to state where the comment is inherited from.
   String commentInheritedFrom = "";
 
   /// List of the meta annotations on the method.
   List<Annotation> annotations;
 
   Method(String name, this.isStatic, this.isAbstract, this.isConst,
       this.returnType, String comment, this.parameters, this.annotations,
       String qualifiedName, bool isPrivate, String owner, this.isConstructor,
       this.isGetter, this.isSetter, this.isOperator)
         : super(name, comment, isPrivate, owner) {
     _mdnComment(this);
   }
 
-  /**
-   * Makes sure that the method with an inherited equivalent have comments.
-   */
+  /// Makes sure that the method with an inherited equivalent have comments.
   void ensureCommentFor(Method inheritedMethod) {
     if (comment.isNotEmpty) return;
     (entityMap[inheritedMethod.owner] as Class).ensureComments();
     comment = inheritedMethod.comment;
     commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ?
         inheritedMethod.qualifiedName : inheritedMethod.commentInheritedFrom;
   }
 
   /// Generates a map describing the [Method] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'commentFrom': commentInheritedFrom,
     'static': isStatic.toString(),
     'abstract': isAbstract.toString(),
     'constant': isConst.toString(),
     'return': new List.filled(1, returnType.toMap()),
     'parameters': recurseMap(parameters),
     'annotations': annotations.map((a) => a.toMap()).toList()
   };
 
   String get typeName => isConstructor ? 'constructor' :
     isGetter ? 'getter' : isSetter ? 'setter' :
     isOperator ? 'operator' : 'method';
 }
 
-/**
- * A container to categorize methods into the following groups: setters,
- * getters, constructors, operators, regular methods.
- */
+/// 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,
         mirror.isAbstract, mirror.isConstConstructor, _type(mirror.returnType),
@@ skipping 48 matching lines @@
   }
 
   void forEach(void f(String key, Method value)) {
     setters.forEach(f);
     getters.forEach(f);
     operators.forEach(f);
     regularMethods.forEach(f);
   }
 }
 
-/**
- * A class containing properties of a Dart method/function parameter.
- */
+/// A class containing properties of a Dart method/function parameter.
 class Parameter {
 
   String name;
   bool isOptional;
   bool isNamed;
   bool hasDefaultValue;
   Type type;
   String defaultValue;
 
   /// List of the meta annotations on the parameter.
   List<Annotation> annotations;
 
   Parameter(this.name, this.isOptional, this.isNamed, this.hasDefaultValue,
       this.type, this.defaultValue, this.annotations);
 
   /// Generates a map describing the [Parameter] object.
   Map toMap() => {
     'name': name,
     'optional': isOptional.toString(),
     'named': isNamed.toString(),
     'default': hasDefaultValue.toString(),
     'type': new List.filled(1, type.toMap()),
     'value': defaultValue,
     'annotations': annotations.map((a) => a.toMap()).toList()
   };
 }
 
-/**
- * A class containing properties of a Generic.
- */
+/// A class containing properties of a Generic.
 class Generic {
   String name;
   String type;
 
   Generic(this.name, this.type);
 
   Map toMap() => {
     'name': name,
     'type': type
   };
 }
 
-/**
- * Holds the name of a return type, and its generic type parameters.
- *
- * Return types are of a form [outer]<[inner]>.
- * If there is no [inner] part, [inner] will be an empty list.
- *
- * For example:
- *        int size()
- *          "return" :
- *            - "outer" : "dart-core.int"
- *              "inner" :
- *
- *        List<String> toList()
- *          "return" :
- *            - "outer" : "dart-core.List"
- *              "inner" :
- *                - "outer" : "dart-core.String"
- *                  "inner" :
- *
- *        Map<String, List<int>>
- *          "return" :
- *            - "outer" : "dart-core.Map"
- *              "inner" :
- *                - "outer" : "dart-core.String"
- *                  "inner" :
- *                - "outer" : "dart-core.List"
- *                  "inner" :
- *                    - "outer" : "dart-core.int"
- *                      "inner" :
- */
+/// Holds the name of a return type, and its generic type parameters.
+///
+/// Return types are of a form [outer]<[inner]>.
+/// If there is no [inner] part, [inner] will be an empty list.
+///
+/// For example:
+///        int size()
+///          "return" :
+///            - "outer" : "dart-core.int"
+///              "inner" :
+///
+///        List<String> toList()
+///          "return" :
+///            - "outer" : "dart-core.List"
+///              "inner" :
+///                - "outer" : "dart-core.String"
+///                  "inner" :
+///
+///        Map<String, List<int>>
+///          "return" :
+///            - "outer" : "dart-core.Map"
+///              "inner" :
+///                - "outer" : "dart-core.String"
+///                  "inner" :
+///                - "outer" : "dart-core.List"
+///                  "inner" :
+///                    - "outer" : "dart-core.int"
+///                      "inner" :
 class Type {
   String outer;
   List<Type> inner;
 
   Type(this.outer, this.inner);
 
   Map toMap() => {
     'outer': outer,
     'inner': inner.map((e) => e.toMap()).toList()
   };
 }
 
-/**
- * Holds the name of the annotation, and its parameters.
- */
+/// Holds the name of the annotation, and its parameters.
 class Annotation {
   String qualifiedName;
   List<String> parameters;
 
   Annotation(this.qualifiedName, this.parameters);
 
   Map toMap() => {
     '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('.','-');
   }
   var owner = m.owner;
   if (owner == null) return m.qualifiedName;
   // For the unnamed constructor we just return the class name.
   if (m.simpleName == '') return docName(owner);
   return docName(owner) + '.' + m.simpleName;
 }