Add a script for determining which DOM methods correspond to which HTML methods.

Add a script for determining which DOM methods correspond to which HTML methods.

Ultimately, this will be used for generating documentation. Currently, though,
it just prints out information to the console.

This also includes some annotations to the HTML library, where the DOM
correspondence couldn't be auto-detected.

Committed: https://code.google.com/p/dart/source/detail?r=1767

[nweiz, 2011-11-18 22:20:25]

Looping in John and Bob to review minor changes in Frog and DartDoc,
respectively.

[Jennifer Messerly, 2011-11-18 22:41:16]

frog changes lgtm. it's going to be so cool having this help

http://codereview.chromium.org/8548019/diff/1/frog/member.dart
File frog/member.dart (right):

http://codereview.chromium.org/8548019/diff/1/frog/member.dart#newcode214
frog/member.dart:214: int hashCode() =>
'${declaringType.hashCode()}:$name'.hashCode();
Normally I'd do this with something like:
int hashCode() => (declaringType.hashCode() << 4) ^ name.hashCode();

[nweiz, 2011-11-18 22:48:56]

http://codereview.chromium.org/8548019/diff/1/frog/member.dart
File frog/member.dart (right):

http://codereview.chromium.org/8548019/diff/1/frog/member.dart#newcode214
frog/member.dart:214: int hashCode() =>
'${declaringType.hashCode()}:$name'.hashCode();
On 2011/11/18 22:41:16, John Messerly wrote:
> Normally I'd do this with something like:
> int hashCode() => (declaringType.hashCode() << 4) ^ name.hashCode();

I don't love the magic 4 there, but I don't love my solution either, and yours
is probably the cleaner of the two. Really what I want to do is [declaringType,
name].hashCode(), but lists aren't hashable :-/.

[Jacob, 2011-11-21 18:51:16]

This will be very useful!

http://codereview.chromium.org/8548019/diff/4002/client/html/release/html.dart
File client/html/release/html.dart (right):

http://codereview.chromium.org/8548019/diff/4002/client/html/release/html.dar...
client/html/release/html.dart:16830: /** @domName DOMWindow.createWebKitPoint */
why @domName instead of @DomName?

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
File client/html/scripts/html-diff.dart (right):

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:30: htmlMember.name;
put the htmlMember.name line in the string template to make the line easier to
read by using a single mechanism to perform string concat.

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:40: if (member.isPrivate) continue;
I think it is clearer to have multiple clauses anded together than to have a
bunch of separate classes that continue.
For example:

if (!member.isPrivate
   && (member is MethodMember || member is PropertyMember)
   && ...)  {
     print (No dart:html wrapper....

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:79: var domName = tags['domName'];
prefer final to var for local variables that really are final.  it makes it
easier for someone browsing the code to quickly tell that the variable is never
modified in after it is defined which makes it quicker to quickly grock code.

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:232: }
provide explicit return of null or throw an exception if nothing matched

[nweiz, 2011-11-21 19:34:21]

http://codereview.chromium.org/8548019/diff/4002/client/html/release/html.dart
File client/html/release/html.dart (right):

http://codereview.chromium.org/8548019/diff/4002/client/html/release/html.dar...
client/html/release/html.dart:16830: /** @domName DOMWindow.createWebKitPoint */
On 2011/11/21 18:51:17, Jacob wrote:
> why @domName instead of @DomName?

@domName is in line with existing doc tag conventions in other languages. I
think initial lowercase looks much better for single-word tags, if we ever do
those (e.g. "@see" vs "@See").

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
File client/html/scripts/html-diff.dart (right):

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:30: htmlMember.name;
On 2011/11/21 18:51:17, Jacob wrote:
> put the htmlMember.name line in the string template to make the line easier to
> read by using a single mechanism to perform string concat.

How do I wrap the line if everything's in a single string literal?

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:40: if (member.isPrivate) continue;
On 2011/11/21 18:51:17, Jacob wrote:
> I think it is clearer to have multiple clauses anded together than to have a
> bunch of separate classes that continue.
> For example:
> 
> if (!member.isPrivate
>    && (member is MethodMember || member is PropertyMember)
>    && ...)  {
>      print (No dart:html wrapper....

Done.

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:79: var domName = tags['domName'];
On 2011/11/21 18:51:17, Jacob wrote:
> prefer final to var for local variables that really are final.  it makes it
> easier for someone browsing the code to quickly tell that the variable is
never
> modified in after it is defined which makes it quicker to quickly grock code.

Done, although the fact that "final" is two more characters than "var" makes
doing this pervasively a little annoying.

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:232: }
On 2011/11/21 18:51:17, Jacob wrote:
> provide explicit return of null or throw an exception if nothing matched

Done.

[Jacob, 2011-11-21 19:47:23]

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
File client/html/scripts/html-diff.dart (right):

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:30: htmlMember.name;
On 2011/11/21 19:34:22, nweiz wrote:
> On 2011/11/21 18:51:17, Jacob wrote:
> > put the htmlMember.name line in the string template to make the line easier
to
> > read by using a single mechanism to perform string concat.
> 
> How do I wrap the line if everything's in a single string literal?

Either use a multi-line string literal or write
          final separator = htmlMember.name == '' ? '' : '.';
          htmlName ='new $htmlTypeName$separator${htmlMember.name}';

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:79: var domName = tags['domName'];
On 2011/11/21 19:34:22, nweiz wrote:
> On 2011/11/21 18:51:17, Jacob wrote:
> > prefer final to var for local variables that really are final.  it makes it
> > easier for someone browsing the code to quickly tell that the variable is
> never
> > modified in after it is defined which makes it quicker to quickly grock
code.
> 
> Done, although the fact that "final" is two more characters than "var" makes
> doing this pervasively a little annoying.
I agree the extra two characters are annoying but I think the clearer semantics
make it worth it. Time to make your code editor automatically write final after
you type "fin "
of course i'd be even happier if the language was tweaked so that the keyword
for  final took fewer characters.

http://codereview.chromium.org/8548019/diff/7002/client/html/scripts/html-dif...
File client/html/scripts/html-diff.dart (right):

http://codereview.chromium.org/8548019/diff/7002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:43: continue;
nit: only use the continue keyword when needed.  Switch to && and invert the
cases so that no continue is needed.

[nweiz, 2011-11-21 23:01:32]

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
File client/html/scripts/html-diff.dart (right):

http://codereview.chromium.org/8548019/diff/4002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:30: htmlMember.name;
On 2011/11/21 19:47:23, Jacob wrote:
> On 2011/11/21 19:34:22, nweiz wrote:
> > On 2011/11/21 18:51:17, Jacob wrote:
> > > put the htmlMember.name line in the string template to make the line
easier
> to
> > > read by using a single mechanism to perform string concat.
> > 
> > How do I wrap the line if everything's in a single string literal?
> 
> Either use a multi-line string literal or write
>           final separator = htmlMember.name == '' ? '' : '.';
>           htmlName ='new $htmlTypeName$separator${htmlMember.name}';

Done.

http://codereview.chromium.org/8548019/diff/7002/client/html/scripts/html-dif...
File client/html/scripts/html-diff.dart (right):

http://codereview.chromium.org/8548019/diff/7002/client/html/scripts/html-dif...
client/html/scripts/html-diff.dart:43: continue;
On 2011/11/21 19:47:23, Jacob wrote:
> nit: only use the continue keyword when needed.  Switch to && and invert the
> cases so that no continue is needed.

Done.

[Jacob, 2011-11-21 23:12:11]

All the code to autogen looks good.  Went through the annotations added to
client/html and fixed some cases that weren't quite right.

http://codereview.chromium.org/8548019/diff/13001/client/html/src/ElementWrap...
File client/html/src/ElementWrappingImplementation.dart (right):

http://codereview.chromium.org/8548019/diff/13001/client/html/src/ElementWrap...
client/html/src/ElementWrappingImplementation.dart:724: /** @domName
getClientRects */
Should be 
Element.getClientRects?

http://codereview.chromium.org/8548019/diff/13001/client/html/src/NodeWrappin...
File client/html/src/NodeWrappingImplementation.dart (right):

http://codereview.chromium.org/8548019/diff/13001/client/html/src/NodeWrappin...
client/html/src/NodeWrappingImplementation.dart:60: /** @domName
Node.hasChildNodes */
isEmpty should be
return !_nod.hasChildNodes();

http://codereview.chromium.org/8548019/diff/13001/client/html/src/NodeWrappin...
client/html/src/NodeWrappingImplementation.dart:201: /** @domName Node.contains
*/
should be Element.contains

http://codereview.chromium.org/8548019/diff/13001/client/html/src/WindowWrapp...
File client/html/src/WindowWrappingImplementation.dart (right):

http://codereview.chromium.org/8548019/diff/13001/client/html/src/WindowWrapp...
client/html/src/WindowWrappingImplementation.dart:87: /** @domName DOMWindow */
Use @domName Window instead
DOMWindow is a WebKit specific name.

http://codereview.chromium.org/8548019/diff/13001/client/html/src/XMLHttpRequ...
File client/html/src/XMLHttpRequestWrappingImplementation.dart (right):

http://codereview.chromium.org/8548019/diff/13001/client/html/src/XMLHttpRequ...
client/html/src/XMLHttpRequestWrappingImplementation.dart:21: /** @domName
DOMWindow.createXMLHttpRequest */
here and elsewhere, replace DOMWindow with Window

[nweiz, 2011-11-22 01:11:09]

http://codereview.chromium.org/8548019/diff/13001/client/html/src/ElementWrap...
File client/html/src/ElementWrappingImplementation.dart (right):

http://codereview.chromium.org/8548019/diff/13001/client/html/src/ElementWrap...
client/html/src/ElementWrappingImplementation.dart:724: /** @domName
getClientRects */
On 2011/11/21 23:12:11, Jacob wrote:
> Should be 
> Element.getClientRects?

"Element" is the default class, so it can be omitted. I could add it in anyway
if you think it's clearer.

http://codereview.chromium.org/8548019/diff/13001/client/html/src/NodeWrappin...
File client/html/src/NodeWrappingImplementation.dart (right):

http://codereview.chromium.org/8548019/diff/13001/client/html/src/NodeWrappin...
client/html/src/NodeWrappingImplementation.dart:60: /** @domName
Node.hasChildNodes */
On 2011/11/21 23:12:11, Jacob wrote:
> isEmpty should be
> return !_nod.hasChildNodes();

Done.

http://codereview.chromium.org/8548019/diff/13001/client/html/src/NodeWrappin...
client/html/src/NodeWrappingImplementation.dart:201: /** @domName Node.contains
*/
On 2011/11/21 23:12:11, Jacob wrote:
> should be Element.contains

Element.contains doesn't exist in the DOM API.

http://codereview.chromium.org/8548019/diff/13001/client/html/src/WindowWrapp...
File client/html/src/WindowWrappingImplementation.dart (right):

http://codereview.chromium.org/8548019/diff/13001/client/html/src/WindowWrapp...
client/html/src/WindowWrappingImplementation.dart:87: /** @domName DOMWindow */
On 2011/11/21 23:12:11, Jacob wrote:
> Use @domName Window instead
> DOMWindow is a WebKit specific name.

This needs to point at the class name as defined in dom.dart.

http://codereview.chromium.org/8548019/diff/13001/client/html/src/XMLHttpRequ...
File client/html/src/XMLHttpRequestWrappingImplementation.dart (right):

http://codereview.chromium.org/8548019/diff/13001/client/html/src/XMLHttpRequ...
client/html/src/XMLHttpRequestWrappingImplementation.dart:21: /** @domName
DOMWindow.createXMLHttpRequest */
On 2011/11/21 23:12:11, Jacob wrote:
> here and elsewhere, replace DOMWindow with Window

See previous response.

[Jacob, 2011-11-22 22:48:45]

lgtm