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;
+
 /**
  * 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}');
-
+  

[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);
 
   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 != 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,
     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;
+    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 == '' ?
         inheritedMethod.qualifiedName : inheritedMethod.commentInheritedFrom;
   }
 
   /// Generates a map describing the [Method] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
@@ skipping 92 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
   };
 }