DOM elements now have MDN comments if provided.

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.
  *
@@ skipping 47 matching lines @@
 /// 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;
 
+/// Map of all the comments for dom elements from MDN. 
+Map _mdn;

[kevmoo-old, 2013/08/15 18:59:57]

Drive by review:

Could one argue for a TODO: make this generic and perhaps pluggable?

I could imagine other types of pluggable annotations (details of an
auto-generated web service library).

At a minimum, move MDN-specific code to its own library that's imported into the
default impl?

+
 /**
  * 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.
  *
@@ skipping 11 matching lines @@
   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.');
       }
       _documentLibraries(mirrorSystem.libraries.values,includeSdk: includeSdk,
           outputToYaml: outputToYaml, append: append, parseSdk: parseSdk);
@@ skipping 196 matching lines @@
   }
 }
 
 bool _isVisible(Indexable item) {
   return _includePrivate || !item.isPrivate;
 }
 
 /**
  * Returns a list of meta annotations assocated with a mirror.
  */
-List<String> _annotations(DeclarationMirror 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(annotation.type.qualifiedName)) {
@@ skipping 23 matching lines @@
     }
   });
 
   commentText = commentText == null ? '' :
       markdown.markdownToHtml(commentText.trim(), linkResolver: linkResolver,
           inlineSyntaxes: markdownSyntaxes);
   return commentText;
 }
 
 /**
+ * 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 mdnDir = path.join(path.dirname(path.dirname(path.dirname(path.dirname(
+        path.absolute(new Options().script))))), 'utils', 'apidoc', 'mdn');
+    _mdn = parse(new File(path.join(mdnDir, 'database.json'))
+        .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. 
+ */
+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. 
+ */
+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>.
  */
 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 = memberScope.qualifiedName;
   } else {
@@ skipping 244 matching lines @@
   /// Inherited methods in the class.
   MethodGroup inheritedMethods = new MethodGroup();
 
   /// Generic infomation about the class.
   Map<String, Generic> generics;
 
   Class superclass;
   bool isAbstract;
 
   /// List of the meta annotations on the class.
-  List<String> annotations;
+  List<Annotation> annotations;
 
   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, qualifiedName, isPrivate, owner);
+      : super(name, comment, qualifiedName, isPrivate, owner) {
+    _mdnComment(this);
+  }
 
   String get typeName => 'class';
   
   /**
    * Returns a list of all the parent classes.
    */
   List<Class> parent() {
     var parent = superclass == null ? [] : [superclass];
     parent.addAll(interfaces);
     return parent;
@@ skipping 161 matching lines @@
 
 class Typedef extends Indexable {
   String returnType;
 
   Map<String, Parameter> parameters;
 
   /// Generic information about the typedef.
   Map<String, Generic> generics;
 
   /// List of the meta annotations on the typedef.
-  List<String> annotations;
+  List<Annotation> annotations;
 
   Typedef(String name, this.returnType, String comment, this.generics,
       this.parameters, this.annotations,
       String qualifiedName, bool isPrivate, String owner) 
         : super(name, comment, qualifiedName, isPrivate, owner);
 
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
@@ skipping 10 matching lines @@
  * 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<String> annotations;
+  List<Annotation> annotations;
 
   Variable(String name, this.isFinal, this.isStatic, this.isConst, this.type,
       String comment, this.annotations, String qualifiedName, bool isPrivate,
-      String owner) : super(name, comment, qualifiedName, isPrivate, owner);
+      String owner) : super(name, comment, qualifiedName, isPrivate, owner) {
+    _mdnComment(this);
+  }
 
   /// Generates a map describing the [Variable] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'final': isFinal.toString(),
     'static': isStatic.toString(),
     'constant': isConst.toString(),
     'type': new List.filled(1, type.toMap()),
@@ skipping 17 matching lines @@
   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<String> annotations;
+  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, qualifiedName, isPrivate, owner);
+        : super(name, comment, qualifiedName, isPrivate, owner) {
+    _mdnComment(this);
+  }
 
   /**
    * Makes sure that the method with an inherited equivalent have comments.
    */
   void ensureCommentFor(Method inheritedMethod) {
     if (comment.isNotEmpty) return;
     entityMap[inheritedMethod.owner].ensureComments();
     comment = inheritedMethod.comment;
     commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ?
         inheritedMethod.qualifiedName : inheritedMethod.commentInheritedFrom;
@@ skipping 98 matching lines @@
 class Parameter {
 
   String name;
   bool isOptional;
   bool isNamed;
   bool hasDefaultValue;
   Type type;
   String defaultValue;
 
   /// List of the meta annotations on the parameter.
-  List<String> annotations;
+  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(),
@@ skipping 67 matching lines @@
   String qualifiedName;
   List<String> parameters;
 
   Annotation(this.qualifiedName, this.parameters);
 
   Map toMap() => {
     'name': qualifiedName,
     'parameters': parameters
   };
 }