This accidentally snuck into the revert.

utils/apidoc/html_diff.dart

 // 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.
 
 /**
  * A script to assist in documenting the difference between the dart:html API
  * and the old DOM API.
  */
 #library('html_diff');
 
@@ skipping 67 matching lines @@
   static Compilation _compilation;
   static MirrorSystem _mirrors;
   static LibraryMirror dom;
 
   /**
    * Perform static initialization of [world]. This should be run before
    * calling [HtmlDiff.run].
    */
   static void initialize(Path libDir) {
     _compilation = new Compilation.library(
-        const <Path>[
-            const Path(DOM_LIBRARY_NAME),
-            const Path(HTML_LIBRARY_NAME)
-        ], libDir);
+        const <Path>[const Path(HTML_LIBRARY_NAME)], libDir);
     _mirrors = _compilation.mirrors;
 
     // Find 'dart:dom_deprecated' by its library tag 'dom'.
     dom = findMirror(_mirrors.libraries, DOM_LIBRARY_NAME);
   }
 
   HtmlDiff([bool printWarnings = false]) :
     _printWarnings = printWarnings,
     domToHtml = new Map<MemberMirror, Set<MemberMirror>>(),
     htmlToDom = new Map<String, Set<MemberMirror>>(),
     domTypesToHtml = new Map<String, Set<InterfaceMirror>>(),
     htmlTypesToDom = new Map<String, Set<InterfaceMirror>>(),
     comments = new CommentMap();
 
   void warn(String s) {
     if (_printWarnings) {
       print('Warning: $s');
     }
   }
 
   /**
    * Computes the `dart:dom_deprecated` to `dart:html` mapping, and
    * places it in [domToHtml], [htmlToDom], [domTypesToHtml], and
-   * [htmlTypesToDom]. Before this is run, Frog should be initialized
+   * [htmlTypesToDom]. Before this is run, dart2js should be initialized
    * (via [parseOptions] and [initializeWorld]) and
    * [HtmlDiff.initialize] should be called.
    */
   void run() {
     LibraryMirror htmlLib = findMirror(_mirrors.libraries, HTML_LIBRARY_NAME);
     if (htmlLib === null) {
       warn('Could not find $HTML_LIBRARY_NAME');
       return;
     }
     for (InterfaceMirror htmlType in htmlLib.types.getValues()) {
       final domTypes = htmlToDomTypes(htmlType);
       if (domTypes.isEmpty()) continue;
 
-      htmlTypesToDom.putIfAbsent(htmlType.qualifiedName,
+      htmlTypesToDom.putIfAbsent(htmlType.qualifiedName,// map of html->[its dom types]
           () => new Set()).addAll(domTypes);
-      domTypes.forEach((t) =>
+      domTypes.forEach((t) => // map of dom type -> [the html name].
           domTypesToHtml.putIfAbsent(t.qualifiedName,
             () => new Set()).add(htmlType));
 
       htmlType.declaredMembers.forEach(
-          (_, m) => _addMemberDiff(m, domTypes));
+          (_, m) => _addMemberDiff(m, domTypes)); // add those dom member types to each
+          // of the html member (name/type) we're looking at
     }
   }
 
   /**
    * Records the `dart:dom_deprecated` to `dart:html` mapping for
    * [implMember] (from `dart:html`). [domTypes] are the
    * `dart:dom_deprecated` [Type]s that correspond to [implMember]'s
    * defining [Type].
    */
   void _addMemberDiff(MemberMirror htmlMember, List<TypeMirror> domTypes) {
     var domMembers = htmlToDomMembers(htmlMember, domTypes);
     if (htmlMember == null && !domMembers.isEmpty()) {
       warn('$HTML_LIBRARY_NAME member '
            '${htmlMember.surroundingDeclaration.simpleName}.'
            '${htmlMember.simpleName} has no corresponding '
            '$HTML_LIBRARY_NAME member.');
     }
 
     if (htmlMember == null) return;
     if (!domMembers.isEmpty()) {
       htmlToDom[htmlMember.qualifiedName] = domMembers;
+      //htmlToDom[htmlmembername] -> list of corresponding dom members
     }
-    domMembers.forEach((m) =>
+    domMembers.forEach((m) => // add the html member name to the domToHtml
         domToHtml.putIfAbsent(m, () => new Set()).add(htmlMember));
   }
 
   /**
    * Returns the `dart:dom_deprecated` [Type]s that correspond to
    * [htmlType] from `dart:html`. This can be the empty list if no
    * correspondence is found.
    */
   List<InterfaceMirror> htmlToDomTypes(InterfaceMirror htmlType) {
     if (htmlType.simpleName == null) return [];
     final tags = _getTags(comments.find(htmlType.location));
-    if (tags.containsKey('domName')) {
+    if (tags.containsKey('domName')) { // TODO(efortuna): instead just tag with
+      // domTypes and domMembers instead of domName
       var domNames = <String>[];
       for (var s in tags['domName'].split(',')) {
         domNames.add(s.trim());
       }
       if (domNames.length == 1 && domNames[0] == 'none') return [];
       var domTypes = <InterfaceMirror>[];
       for (var domName in domNames) {
         final domType = findMirror(dom.types, domName);
         if (domType == null) {
           warn('no $DOM_LIBRARY_NAME type named $domName');
@@ skipping 99 matching lines @@
   Map<String, String> _getTags(String comment) {
     if (comment == null) return const <String, String>{};
     final re = const RegExp("@([a-zA-Z]+) ([^;]+)(?:;|\$)");
     final tags = <String, String>{};
     for (var m in re.allMatches(comment.trim())) {
       tags[m[1]] = m[2];
     }
     return tags;
   }
 }