Fix ApiDoc to work with new dart:html code. Tweak dart:html generator to generate clearer @domName …

lib/dom/scripts/systemhtml.py

 #!/usr/bin/python
 # 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.
 
 """This module provides shared functionality for the system to generate
 Dart:html APIs from the IDL database."""
 
 from systemfrog import *
 from systeminterface import *
@@ skipping 83 matching lines @@
     'Node.previousSibling': 'previousNode',
     'Node.textContent': 'text',
     'SVGElement.className': '$dom_svgClassName',
     'SVGAnimatedString.className': '$dom_svgClassName',
     'SVGStylable.className': '$dom_svgClassName',
 }
 
 #TODO(jacobr): inject annotations into the interfaces based on this table and
 # on _html_library_renames.
 _injected_doc_fragments = {
-    'Element.query': '  /** @domName querySelector, Document.getElementById */',
+    'Element.query': '  /** @domName Element.querySelector, Document.getElementById */',
 }
 # Members and classes from the dom that should be removed completelly from
 # dart:html.  These could be expressed in the IDL instead but expressing this
 # as a simple table instead is more concise.
 # Syntax is: ClassName.(get\.|set\.)?MemberName
 # Using get: and set: is optional and should only be used when a getter needs
 # to be suppressed but not the setter, etc. 
 # TODO(jacobr): cleanup and augment this list.
 _html_library_remove = set([
     'Window.get:document', # Removed as we have a custom implementation.
@@ skipping 515 matching lines @@
     if constructor_info:
       factory_provider = '_' + typename + 'FactoryProvider';
 
     if typename in interface_factories:
       factory_provider = interface_factories[typename]
 
     if factory_provider:
       extends_str += ' default ' + factory_provider
 
     # TODO(vsm): Add appropriate package / namespace syntax.
-    (self._members_emitter,
+    (self._type_comment_emitter,
+     self._members_emitter,
      self._top_level_emitter) = self._emitter.Emit(
          self._template + '$!TOP_LEVEL',
          ID=typename,
          EXTENDS=extends_str)
 
+    self._type_comment_emitter.Emit("/// @domName $DOMNAME",
+        DOMNAME=self._interface.doc_js_name)
+
     if constructor_info:
       self._members_emitter.Emit(
           '\n'
           '  $CTOR($PARAMS);\n',
           CTOR=typename,
           PARAMS=constructor_info.ParametersInterfaceDeclaration());
 
     element_type = MaybeTypedArrayElementType(self._interface)
     if element_type:
       self._members_emitter.Emit(
@@ skipping 25 matching lines @@
     if not html_getter_name or self._shared.IsPrivate(html_getter_name):
       getter = None
     if not html_setter_name or self._shared.IsPrivate(html_setter_name):
       setter = None
     if not getter and not setter:
       return
 
     # We don't yet handle inconsistent renames of the getter and setter yet.
     if html_getter_name and html_setter_name:
       assert html_getter_name == html_setter_name
-    if html_getter_name != dom_name:
-      self._members_emitter.Emit('\n  /** @domName $DOMNAME */',
-          DOMNAME = dom_name)
+
+    self._members_emitter.Emit('\n  /** @domName $DOMINTERFACE.$DOMNAME */',
+        DOMINTERFACE=getter.doc_js_interface_name,
+        DOMNAME=dom_name)
     if (getter and setter and
         DartType(getter.type.id) == DartType(setter.type.id)):
       self._members_emitter.Emit('\n  $TYPE $NAME;\n',
                                  NAME=html_getter_name,
                                  TYPE=DartType(getter.type.id));
       return
     if getter and not setter:
       self._members_emitter.Emit('\n  final $TYPE $NAME;\n',
                                  NAME=html_getter_name,
                                  TYPE=DartType(getter.type.id));
       return
     raise Exception('Unexpected getter/setter combination %s %s' %
                     (getter, setter))
 
   def AddOperation(self, info):
     """
     Arguments:
       operations - contains the overloads, one or more operations with the same
         name.
     """
     html_name = self._shared.RenameInHtmlLibrary(
         self._interface, info.name)
     if html_name and not self._shared.IsPrivate(html_name):
-      if html_name != info.name:
-        self._members_emitter.Emit('\n  /** @domName $DOMNAME */',
-            DOMNAME = info.name)
+      self._members_emitter.Emit('\n  /** @domName $DOMINTERFACE.$DOMNAME */',
+          DOMINTERFACE=info.overloads[0].doc_js_interface_name,
+          DOMNAME=info.name)
 
       self._members_emitter.Emit('\n'
                                  '  $TYPE $NAME($PARAMS);\n',
                                  TYPE=info.type_name,         
                                  NAME=html_name,
                                  PARAMS=info.ParametersInterfaceDeclaration())
 
   def FinishInterface(self):
     pass
 
@@ skipping 13 matching lines @@
             self._shared.GetParentsEventsClasses(self._interface)))
 
     for event_name in event_attrs:
       if event_name in _html_event_names:
         events_members.Emit('\n  EventListenerList get $NAME();\n',
           NAME=_html_event_names[event_name])
       else:
         raise Exception('No known html even name for event: ' + event_name)
 
   def _EmitEventGetter(self, events_interface):
-    self._members_emitter.Emit('\n  $TYPE get on();\n',
-                               TYPE=events_interface)
+    self._members_emitter.Emit(
+        '\n  /**'
+        '\n   * @domName EventTarget.addEventListener, '
+        'EventTarget.removeEventListener, EventTarget.dispatchEvent'
+        '\n   */'
+        '\n  $TYPE get on();\n',
+        TYPE=events_interface)
 
 # ------------------------------------------------------------------------------
 
 # TODO(jmesserly): inheritance is probably not the right way to factor this long
 # term, but it makes merging better for now.
 class HtmlFrogClassGenerator(FrogInterfaceGenerator):
   """Generates a Frog class for the dart:html library from a DOM IDL
   interface.
   """
 
@@ skipping 881 matching lines @@
     # dispatch has removed f(X), leaving only f(Y), but there is no guarantee
     # that Y = Z-X, so we need to check for Y.
     true_code = emitter.Emit(
         '$(INDENT)if ($COND) {\n'
         '$!TRUE'
         '$(INDENT)}\n',
         COND=test, INDENT=indent)
     self.GenerateDispatch(
         true_code, info, indent + '  ', position + 1, positive)
     return True