Add a script to generate HTML and DOM docs with cross-links to one another.

client/html/scripts/html_doc.dart

Index: client/html/scripts/html_doc.dart
diff --git a/client/html/scripts/html_doc.dart b/client/html/scripts/html_doc.dart
new file mode 100644
index 0000000000000000000000000000000000000000..4db268d6f3109f5cb07bacc6ae3d554af1981ef1
--- /dev/null
+++ b/client/html/scripts/html_doc.dart
@@ -0,0 +1,95 @@
+// Copyright (c) 2011, 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 document the HTML library. This needs to be run from the

[Bob Nystrom, 2011/12/06 23:11:23]

To document what about the HTML library? For a script about documentation, it's
sadly devoid of it. :(

+ * utils/dartdoc directory.

[Bob Nystrom, 2011/12/06 23:11:23]

I'd move this into dartdoc. I know it's specific to HTML, but dartdoc already
has a little special sauce for HTML, and HTML is built into Dart.

Even more awesome would be to add a little shell script (htmldoc) that invokes
it. 

[nweiz, 2011/12/07 19:26:56]

Moving this into dartdoc runs into the same problem that we had with
unittest_node. This would transitively depend on ../markdown/ast.dart, as well
as on ../../client/html/scripts/html_diff.dart; but the latter would also depend
on ../../../utils/markdown/ast.dart. Frog doesn't recognize that the two
ast.darts are the same, which causes errors.

I've added the htmldoc wrapper script, though.

+ */
+#library('html_doc');
+
+#import('html_diff.dart');
+#import('../../../frog/lang.dart');
+#import('../../../frog/file_system_node.dart');
+#import('../../../frog/file_system.dart');
+#import('../../../utils/dartdoc/dartdoc.dart', prefix: 'doc');
+
+HtmlDiff _diff;
+
+void main() {
+  HtmlDiff.initWorld('../../frog', new NodeFileSystem());
+  doc.initializeDartDoc();
+  _diff = new HtmlDiff();
+  _diff.run();
+
+  process.argv[2] = 'dart:html';

[Bob Nystrom, 2011/12/06 23:11:23]

This is pretty gross. Right now dartdoc isn't set up to be run as a lib, but it
should be. Can you do that? The markdown lib might be a useful reference.

[nweiz, 2011/12/07 19:26:56]

Done.

+  doc.registerMethodCallback(addMemberDoc);
+  doc.registerFieldCallback(addMemberDoc);
+  doc.registerTypeCallback(addTypeDoc);
+  doc.main();
+}
+
+String _andList(List<String> items) {

[Jacob, 2011/12/06 22:38:14]

nit: name _andList is a bit confusing.  Maybe something like
listToAndSeparatedString
?

[Bob Nystrom, 2011/12/06 23:11:23]

Dartdoc also has code that does this. Since you're already importing dartdoc,
refactor that out into a separate method in dartdoc and just call it here?

[nweiz, 2011/12/07 19:26:56]

Done.

+  if (items.length == 1) return items[0];
+  if (items.length == 2) return "${items[0]} and ${items[1]}";
+  return Strings.join(items.getRange(0, items.length - 1), ', ') +
+    ', and ' + items[items.length - 1];
+}
+
+String _linkMember(Member member) {
+  final typeName = member.declaringType.name;
+  var memberName = "$typeName.${member.name}";
+  if (member.isConstructor || member.isFactory) {
+    final separator = member.constructorName == '' ? '' : '.';
+    memberName = 'new $typeName$separator${member.constructorName}';
+  } else if (member.name.startsWith('get:')) {
+    memberName = "$typeName.${member.name.substring(4)}";
+  }
+
+  return "[$memberName](../${doc.memberUrl(member)})";

[Bob Nystrom, 2011/12/06 23:11:23]

Yay markdown!

+}
+
+String _linkType(Type type) => "[${type.name}](../${doc.typeUrl(type)})";
+
+Set<Member> _mergeProps(Set<Member> members) {
+  // Only print setters if the getter doesn't exist.

[Bob Nystrom, 2011/12/06 23:11:23]

Make this a doc comment. I'd name this something descriptive: _unifyProperties?

[nweiz, 2011/12/07 19:26:56]

Done.

+  return members.filter((m) {
+    if (!m.name.startsWith('set:')) return true;
+    var getName = m.name.replaceFirst('set:', 'get:');
+    return !members.some((maybeGet) => maybeGet.name == getName);
+  });
+}
+
+String addMemberDoc(Member member) {
+  if (_diff.domToHtml.containsKey(member)) {
+    var htmlMemberSet = _mergeProps(_diff.domToHtml[member]);

[Jacob, 2011/12/06 22:38:14]

nit: var ==> final

[nweiz, 2011/12/07 19:26:56]

Done.

+    var phrase = htmlMemberSet.every((m) => _diff.sameName(member, m)) ?

[Bob Nystrom, 2011/12/06 23:11:23]

Some temporary variables would help here:

final blah = htmlMemberSet.every((m) => _diff.sameName(member, m))
final phrase = blah ? 'available as' : 'renamed to';

It isn't obvious what the result of .every() represents.

[nweiz, 2011/12/07 19:26:56]

I think it reads pretty well... "if every member has the same name as [member],
...". But I guess I wrote it, so it's probably clearer to me than to a reader.
I'll change it.

+      "available as" : "renamed to";
+    var htmlMembers = _andList(map(htmlMemberSet, _linkMember));
+    return "_This is $phrase $htmlMembers in the " +
+      "[dart:html](../html.html) library._";
+  } else if (_diff.htmlToDom.containsKey(member)) {
+    var domMemberSet = _mergeProps(_diff.htmlToDom[member]);
+    var phrase = domMemberSet.every((m) => _diff.sameName(m, member)) ?
+      "is the same as" : "renames";
+    var domMembers = _andList(map(domMemberSet, _linkMember));
+    return "_This $phrase ${domMembers} in the [dart:dom](../dom.html) " +

[Jacob, 2011/12/06 22:38:14]

nit: personally i'd recommend violating the 80 char line limit instead of using
" + "

[Bob Nystrom, 2011/12/06 23:11:23]

Don't need {} on domMembers.

[nweiz, 2011/12/07 19:26:56]

That makes it harder to read in text editors that don't wrap lines (like mine).
It's also contrary to Google style, at least for JS.

[nweiz, 2011/12/07 19:26:56]

Done.

+      "library._";
+  } else {
+    return "";
+  }
+}
+
+String addTypeDoc(Type type) {
+  if (_diff.domTypesToHtml.containsKey(type)) {
+    var htmlTypes = _andList(map(_diff.domTypesToHtml[type], _linkType));
+    return "_This corresponds to $htmlTypes in the [dart:html](../html.html) " +
+      "library._";
+  } else if (_diff.htmlTypesToDom.containsKey(type)) {
+    var domTypes = _andList(map(_diff.htmlTypesToDom[type], _linkType));
+    return "_This corresponds to $domTypes in the [dart:dom](../dom.html) " +
+      "library._";
+  } else {
+    return "";
+  }
+}