DOM elements now have MDN comments if provided.

pkg/docgen/lib/docgen.dart

Index: pkg/docgen/lib/docgen.dart
diff --git a/pkg/docgen/lib/docgen.dart b/pkg/docgen/lib/docgen.dart
index b67a321e5d309796d9614b00f60b8aa1d7c957dd..93d0d3f15b9c80de12bf2347604600d60b659a20 100644
--- a/pkg/docgen/lib/docgen.dart
+++ b/pkg/docgen/lib/docgen.dart
@@ -65,6 +65,9 @@ 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;
+
 /**
  * Docgen constructor initializes the link resolver for markdown parsing.
  * Also initializes the command line arguments.
@@ -96,7 +99,7 @@ Future<bool> docgen(List<String> files, {String packageRoot,
     }
   }
   logger.info('Package Root: ${packageRoot}');
-
+  

[Emily Fortuna, 2013/08/15 17:05:42]

remove whitespace please. 

[janicejl, 2013/08/15 17:45:19]

Done.

   linkResolver = (name) =>
       fixReference(name, _currentLibrary, _currentClass, _currentMember);
 
@@ -313,7 +316,7 @@ bool _isVisible(Indexable item) {
 /**
  * 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 = [];
@@ -357,6 +360,64 @@ String _commentToHtml(DeclarationMirror mirror) {
 }
 
 /**
+ * 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 != null && item.comment != '') return;
+  var domAnnotation = item.annotations.where(
+      (e) => e.qualifiedName == 'metadata.DomName');
+  if (domAnnotation.length != 1) return;

[Emily Fortuna, 2013/08/15 17:05:42]

are there places where we have more than one domAnnotation? That seems like an
error on the library's part that should be addressed if so.

[janicejl, 2013/08/15 17:45:19]

I do not think so. But it is possible for there to be no domAnnotation (not a
dom element). 

[Emily Fortuna, 2013/08/15 18:13:05]

Right, so firstWhere would be appropriate here, too, right?

[janicejl, 2013/08/15 18:38:11]

Done.

+  var domname = domAnnotation.single.parameters.single;

[Emily Fortuna, 2013/08/15 17:05:42]

domName

[janicejl, 2013/08/15 17:45:19]

Done.

+  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 mdnMemberList = mdnType['members'].where((e) => e['name'] == member);

[Emily Fortuna, 2013/08/15 17:05:42]

what about just calling firstWhere instead?

[janicejl, 2013/08/15 17:45:19]

Done.

+  var mdnMember = mdnMemberList.length == 1 ? mdnMemberList.single : null;
+  
+  if (mdnMember == null) return '';
+  if (mdnMember['help'] == null || mdnMember['help'] == '') return '';
+  if (mdnMember['url'] == null) return '';
+  
+  var comment = '<div class="mdn">' + mdnMember['help'].trim() + 
+      '<p class="mdn-note"><a href="' + mdnMember['url'].trim() + 

[Emily Fortuna, 2013/08/15 17:05:42]

can this string and the one below be shared since everything is the same except
the strings you're adding?

[janicejl, 2013/08/15 17:45:19]

Done.

+      '">from Mdn</a></p></div>';
+  
+  return comment;
+}
+
+/**
+ * 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 '';
+  var comment = '<div class="mdn">' + mdnType['summary'].trim() + 
+      '<p class="mdn-note"><a href="' + mdnType['srcUrl'].trim() + 
+      '">from Mdn</a></p></div>';
+  
+  return comment;
+}
+
+/**
  * Converts all [foo] references in comments to <a>libraryName.foo</a>.
  */
 markdown.Node fixReference(String name, LibraryMirror currentLibrary,
@@ -621,12 +682,14 @@ class Class extends Indexable {
   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';
   
@@ -808,7 +871,7 @@ class Typedef extends Indexable {
   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,
@@ -839,11 +902,13 @@ class Variable extends Indexable {
   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() => {
@@ -881,19 +946,21 @@ class Method extends Indexable {
   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;
+    if (comment.isNotEmpty && comment != "") return;

[Emily Fortuna, 2013/08/15 17:05:42]

does isNotEmpty really not cover the case where coment == ""? 

[janicejl, 2013/08/15 17:45:19]

Done.

     entityMap[inheritedMethod.owner].ensureComments();
     comment = inheritedMethod.comment;
     commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ?
@@ -1006,7 +1073,7 @@ class Parameter {
   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);