First half of the new HTML json docs.

First half of the new HTML json docs.

This half produces the JSON file by going through each of the HTML libraries
and pulling out the @DomName annotations as keys for the map.
This means that even though member names may change, the map still works.

Currently creates a blank json file because I have not hooked up the other half
that puts the docs into the libraries to begin with.

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

[Andrei Mouravski, 2013-01-23 18:56:57]

Pete: please take a look and make sure I'm doing everything right.

Jacob: I modified some of your code, so please make sure it's still okay.

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

https://codereview.chromium.org/12035057/diff/1/sdk/lib/html/html_common/meta...
File sdk/lib/html/html_common/metadata.dart (right):

https://codereview.chromium.org/12035057/diff/1/sdk/lib/html/html_common/meta...
sdk/lib/html/html_common/metadata.dart:61: class DocsEditable {}
Should the Experimental constructor have the same change?

https://codereview.chromium.org/12035057/diff/1/tools/dom/docs/bin/docs.dart
File tools/dom/docs/bin/docs.dart (right):

https://codereview.chromium.org/12035057/diff/1/tools/dom/docs/bin/docs.dart#...
tools/dom/docs/bin/docs.dart:20: print('Converted HTML docs ${anyErrors ? "with
$anyErrors" : "without"} errors.');
line length

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/bin/docs.dart
File tools/dom/docs/bin/docs.dart (right):

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/bin/docs.da...
tools/dom/docs/bin/docs.dart:15: final Path JSON_PATH =
scriptDir.append('../docs.json').canonicalize();
This seems odd- these are masquerading as consts, but really are not. Should not
be in caps.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.dart
File tools/dom/docs/lib/docs.dart (right):

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:10: import
'../../../../sdk/lib/_internal/dartdoc/lib/src/json_serializer.dart';
Sorta nice to import this as 'json'.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:17: final List<String> HTML_LIBRARY_NAMES =
['dart:html',
indentation is weird- either use 2 spaces or line up at paren.

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

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:51: <String>['--preserve-comments']);
Array can probably just be: ['--preserve-comments']

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:55: anyErrors = anyErrors ||
_exportJsonToFile(jsonPath, convertedJson);
where is anyErrors set before here? How are compilation errors reported?

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:60: bool _exportJsonToFile(Path jsonPath, Map
convertedJson) {
Nit- order of params.
exportJsonToFile should probably have JSON first, then file path second (order
as mentioned in method name).

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:127: return mirrors.where((DeclarationMirror c) =>
kudos for getting this all into one line. but was that necessary?

[Johnni Winther, 2013-01-24 09:10:08]

lgtm

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/bin/docs.dart
File tools/dom/docs/bin/docs.dart (right):

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/bin/docs.da...
tools/dom/docs/bin/docs.dart:23: print('Converted HTML docs ${anyErrors ? "with
$anyErrors" : "without"} errors.');
Long line.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.dart
File tools/dom/docs/lib/docs.dart (right):

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:55: anyErrors = anyErrors ||
_exportJsonToFile(jsonPath, convertedJson);
On 2013/01/24 02:28:24, blois wrote:
> where is anyErrors set before here? How are compilation errors reported?

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

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:102: if (computeComment(classMirror) != null) {
Store the comment in a variable instead of calling computeComment(classMirror)
twice.

[Jacob, 2013-01-24 18:55:24]

lgtm

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

PTAL.

https://codereview.chromium.org/12035057/diff/1/sdk/lib/html/html_common/meta...
File sdk/lib/html/html_common/metadata.dart (right):

https://codereview.chromium.org/12035057/diff/1/sdk/lib/html/html_common/meta...
sdk/lib/html/html_common/metadata.dart:61: class DocsEditable {}
On 2013/01/24 02:28:24, blois wrote:
> Should the Experimental constructor have the same change?

Probably, but that's outside the scope of this CL. Will start a new CL for that.

https://codereview.chromium.org/12035057/diff/1/tools/dom/docs/bin/docs.dart
File tools/dom/docs/bin/docs.dart (right):

https://codereview.chromium.org/12035057/diff/1/tools/dom/docs/bin/docs.dart#...
tools/dom/docs/bin/docs.dart:20: print('Converted HTML docs ${anyErrors ? "with
$anyErrors" : "without"} errors.');
On 2013/01/24 02:28:24, blois wrote:
> line length

Done.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/bin/docs.dart
File tools/dom/docs/bin/docs.dart (right):

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/bin/docs.da...
tools/dom/docs/bin/docs.dart:15: final Path JSON_PATH =
scriptDir.append('../docs.json').canonicalize();
On 2013/01/24 02:28:24, blois wrote:
> This seems odd- these are masquerading as consts, but really are not. Should
not
> be in caps.

Done.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/bin/docs.da...
tools/dom/docs/bin/docs.dart:23: print('Converted HTML docs ${anyErrors ? "with
$anyErrors" : "without"} errors.');
On 2013/01/24 09:10:09, Johnni Winther wrote:
> Long line.

Done.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.dart
File tools/dom/docs/lib/docs.dart (right):

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:10: import
'../../../../sdk/lib/_internal/dartdoc/lib/src/json_serializer.dart';
On 2013/01/24 02:28:24, blois wrote:
> Sorta nice to import this as 'json'.

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

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:17: final List<String> HTML_LIBRARY_NAMES =
['dart:html',
On 2013/01/24 02:28:24, blois wrote:
> indentation is weird- either use 2 spaces or line up at paren.
> 
> Also, var is not const. Should not be caps.

Done.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:51: <String>['--preserve-comments']);
On 2013/01/24 02:28:24, blois wrote:
> Array can probably just be: ['--preserve-comments']

Done.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:55: anyErrors = anyErrors ||
_exportJsonToFile(jsonPath, convertedJson);
TODO added.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:55: anyErrors = anyErrors ||
_exportJsonToFile(jsonPath, convertedJson);
TODO added.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:60: bool _exportJsonToFile(Path jsonPath, Map
convertedJson) {
On 2013/01/24 02:28:24, blois wrote:
> Nit- order of params.
> exportJsonToFile should probably have JSON first, then file path second (order
> as mentioned in method name).

Done.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:102: if (computeComment(classMirror) != null) {
On 2013/01/24 09:10:09, Johnni Winther wrote:
> Store the comment in a variable instead of calling computeComment(classMirror)
> twice.

Done.

https://codereview.chromium.org/12035057/diff/3001/tools/dom/docs/lib/docs.da...
tools/dom/docs/lib/docs.dart:127: return mirrors.where((DeclarationMirror c) =>
On 2013/01/24 02:28:24, blois wrote:
> kudos for getting this all into one line. but was that necessary?

Done.

[blois, 2013-01-24 21:56:18]

lgtm