First half of the new HTML json docs.

tools/dom/docs/lib/docs.dart

Index: tools/dom/docs/lib/docs.dart
diff --git a/tools/dom/docs/lib/docs.dart b/tools/dom/docs/lib/docs.dart
new file mode 100644
index 0000000000000000000000000000000000000000..d509d59000a90c375de1a8e87400d9c40c03e773
--- /dev/null
+++ b/tools/dom/docs/lib/docs.dart
@@ -0,0 +1,153 @@
+/**
+ * A library for extracting the documentation from the various HTML libraries
+ * ([dart:html], [dart:svg], [dart:web_audio], [dart:indexed_db]) and saving
+ * those documentation comments to a JSON file.
+ */
+
+library docs;
+
+import '../../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart';
+import '../../../../sdk/lib/_internal/dartdoc/lib/src/json_serializer.dart';

[blois, 2013/01/24 02:28:24]

Sorta nice to import this as 'json'.

[Andrei Mouravski, 2013/01/24 19:28:51]

Why? There's no namespace collision, and this keeps methods shorter.

+import '../../../../sdk/lib/_internal/dartdoc/lib/dartdoc.dart';
+import '../../../../utils/apidoc/lib/metadata.dart';
+import 'dart:async';
+import 'dart:io';
+
+/// The various HTML libraries.
+final List<String> HTML_LIBRARY_NAMES = ['dart:html',

[blois, 2013/01/24 02:28:24]

indentation is weird- either use 2 spaces or line up at paren.

Also, var is not const. Should not be caps.

[Andrei Mouravski, 2013/01/24 19:28:51]

Done.

+                   'dart:svg',
+                   'dart:web_audio',
+                   'dart:indexed_db'];
+/**
+ * Converts the libraries in [HTML_LIBRARY_NAMES] to a json file at [jsonPath]
+ * given the library path at [libPath].
+ *
+ * The json output looks like:
+ *     {
+ *       $library_name: {
+ *         $interface_name: {
+ *           comment: "$comment"
+ *           members: {
+ *             $member: "$comment",
+ *             ...
+ *           }
+ *         },
+ *         ...
+ *       },
+ *       ...
+ *     }
+ *
+ * Returns `true` if any errors were encountered, `false` otherwise.
+ */
+bool convert(Path libPath, Path jsonPath) {
+  var anyErrors = false;
+
+  var paths = <Path>[];
+  for (var libraryName in HTML_LIBRARY_NAMES) {
+    paths.add(new Path(libraryName));
+  }
+
+  final compilation = new Compilation.library(paths, libPath, null,
+      <String>['--preserve-comments']);

[blois, 2013/01/24 02:28:24]

Array can probably just be: ['--preserve-comments']

[Andrei Mouravski, 2013/01/24 19:28:51]

Done.

+
+  var convertedJson = _generateJsonFromLibraries(compilation);
+
+  anyErrors = anyErrors || _exportJsonToFile(jsonPath, convertedJson);

[blois, 2013/01/24 02:28:24]

where is anyErrors set before here? How are compilation errors reported?

[Johnni Winther, 2013/01/24 09:10:09]

Currently, compilation error not reported. Shortly a mechanism for handling
diagnostics with be added to Compilation.

[Andrei Mouravski, 2013/01/24 19:28:51]

TODO added.

[Andrei Mouravski, 2013/01/24 19:28:51]

TODO added.

+
+  return anyErrors;
+}
+
+bool _exportJsonToFile(Path jsonPath, Map convertedJson) {

[blois, 2013/01/24 02:28:24]

Nit- order of params.
exportJsonToFile should probably have JSON first, then file path second (order
as mentioned in method name).

[Andrei Mouravski, 2013/01/24 19:28:51]

Done.

+  final jsonFile = new File.fromPath(jsonPath);
+  var writeJson = prettySerialize(convertedJson);
+
+  var outputStream = jsonFile.openOutputStream();
+  outputStream.writeString(writeJson);
+
+  return false;
+}
+
+Map _generateJsonFromLibraries(Compilation compilation) {
+  var convertedJson = {};
+
+  // Sort the libraries by name (not key).
+  var sortedLibraries = new List<LibraryMirror>.from(
+      compilation.mirrors.libraries.values.where(
+          (e) => HTML_LIBRARY_NAMES.indexOf(e.uri.toString()) >= 0))
+      ..sort((x, y) =>
+        x.uri.toString().toUpperCase().compareTo(
+        y.uri.toString().toUpperCase()));
+
+  for (LibraryMirror libMirror in sortedLibraries) {
+    print('Extracting documentation from ${libMirror.displayName}.');
+
+    var libraryJson = {};
+    var sortedClasses = _sortAndFilterMirrors(
+        libMirror.classes.values.toList());
+
+    for (ClassMirror classMirror in sortedClasses) {
+      var classJson = {};
+      var sortedMembers = _sortAndFilterMirrors(
+          classMirror.members.values.toList());
+
+      var membersJson = {};
+      for (var memberMirror in sortedMembers) {
+        var memberDomName = domNames(memberMirror)[0];
+        var memberComment = computeComment(memberMirror);
+        if (memberComment != null) {
+          membersJson.putIfAbsent(memberDomName, () => memberComment);
+        }
+      }
+
+      if (computeComment(classMirror) != null) {

[Johnni Winther, 2013/01/24 09:10:09]

Store the comment in a variable instead of calling computeComment(classMirror)
twice.

[Andrei Mouravski, 2013/01/24 19:28:51]

Done.

+        classJson.putIfAbsent('comment', () =>
+            computeComment(classMirror));
+      }
+      if (!membersJson.isEmpty) {
+        classJson.putIfAbsent('members', () =>
+            membersJson);
+      }
+
+      if (!classJson.isEmpty) {
+        libraryJson.putIfAbsent(domNames(classMirror)[0], () =>
+            classJson);
+      }
+    }
+
+    if (!libraryJson.isEmpty) {
+      convertedJson.putIfAbsent(libMirror.displayName, () =>
+          libraryJson);
+    }
+  }
+
+  return convertedJson;
+}
+
+List<DeclarationMirror> _sortAndFilterMirrors(List<DeclarationMirror> mirrors) {
+  return mirrors.where((DeclarationMirror c) =>

[blois, 2013/01/24 02:28:24]

kudos for getting this all into one line. but was that necessary?

[Andrei Mouravski, 2013/01/24 19:28:51]

Done.

+      !domNames(c).isEmpty &&
+      !c.displayName.startsWith('_') &&
+      (findMetadata(c.metadata, 'DocsEditable') != null))
+      .toList()
+  ..sort((x, y) =>
+    domNames(x)[0].toUpperCase().compareTo(
+    domNames(y)[0].toUpperCase()));
+}
+
+/// Given the class mirror, returns the names found or an empty list.
+List<String> domNames(DeclarationMirror mirror) {
+  var domNameMetadata = findMetadata(mirror.metadata, 'DomName');
+
+  if (domNameMetadata != null) {
+    var domNames = <String>[];
+    var tags = deprecatedFutureValue(domNameMetadata.getField('name'));
+    for (var s in tags.reflectee.split(',')) {
+      domNames.add(s.trim());
+    }
+
+    if (domNames.length == 1 && domNames[0] == 'none') return <String>[];
+    return domNames;
+  } else {
+    return <String>[];
+  }
+}