Several new features and improvements for dartdoc.

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');
 
 #import('dart:coreimpl');
 #import('dart:io');
 
 #import('../../lib/dartdoc/dartdoc.dart');
 #import('../../lib/dartdoc/mirrors/mirrors.dart');
 #import('../../lib/dartdoc/mirrors/mirrors_util.dart');
 
+final HTML_LIBRARY_NAME = 'dart:html';
+final DOM_LIBRARY_NAME = 'dart:dom_deprecated';
+
 /**
  * A class for computing a many-to-many mapping between the types and
  * members in `dart:dom_deprecated` and `dart:html`. This mapping is
  * based on two indicators:
  *
  *   1. Auto-detected wrappers. Most `dart:html` types correspond
  *      straightforwardly to a single `dart:dom_deprecated` type, and
  *      have the same name.  In addition, most `dart:html` methods
  *      just call a single `dart:dom_deprecated` method. This class
  *      detects these simple correspondences automatically.
@@ skipping 48 matching lines @@
   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('dart:dom_deprecated'),
-            const Path('dart:html')
+            const Path(DOM_LIBRARY_NAME),
+            const Path(HTML_LIBRARY_NAME)
         ], libDir);
     _mirrors = _compilation.mirrors();
 
     // Find 'dart:dom_deprecated' by its library tag 'dom'.
-    dom = findMirror(_mirrors.libraries(), '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
    * (via [parseOptions] and [initializeWorld]) and
    * [HtmlDiff.initialize] should be called.
    */
   void run() {
-    LibraryMirror htmlLib = findMirror(_mirrors.libraries(), 'html');
+    LibraryMirror htmlLib = findMirror(_mirrors.libraries(), HTML_LIBRARY_NAME);
     if (htmlLib === null) {
-      warn('Could not find dart:html');
+      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(),
           () => new Set()).addAll(domTypes);
       domTypes.forEach((t) =>
           domTypesToHtml.putIfAbsent(t.qualifiedName(),
             () => new Set()).add(htmlType));
 
       htmlType.declaredMembers().forEach(
           (_, m) => _addMemberDiff(m, domTypes));
     }
   }
 
   /**
    * 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('dart:html member '
+      warn('$HTML_LIBRARY_NAME member '
            '${htmlMember.surroundingDeclaration().simpleName()}.'
-           '${htmlMember.simpleName()} has no corresponding dart:html member.');
+           '${htmlMember.simpleName()} has no corresponding '
+           '$HTML_LIBRARY_NAME member.');
     }
 
     if (htmlMember == null) return;
     if (!domMembers.isEmpty()) {
       htmlToDom[htmlMember.qualifiedName()] = domMembers;
     }
     domMembers.forEach((m) =>
         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')) {
       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 dart:dom_deprecated type named $domName');
+          warn('no $DOM_LIBRARY_NAME type named $domName');
         } else {
           domTypes.add(domType);
         }
       }
       return domTypes;
     }
     return <InterfaceMirror>[];
   }
 
   /**
@@ skipping 89 matching lines @@
   Map<String, String> _getTags(String comment) {
     if (comment == null) return const <String>{};
     final re = const RegExp("@([a-zA-Z]+) ([^;]+)(?:;|\$)");
     final tags = <String>{};
     for (var m in re.allMatches(comment.trim())) {
       tags[m[1]] = m[2];
     }
     return tags;
   }
 }