HTML human writable docs working end to end!... mostly...

HTML human writable docs working end to end!... mostly...

Included is the first bit of hand-written HTML docs in MenuElement (since it
was first on the list of files.)

Note that this CL is a super set of https://codereview.chromium.org/11280133/

Things are still very, very fragile, but it works!

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

[blois, 2012-11-26 20:07:43]

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/scripts/dartd...
File sdk/lib/html/scripts/dartdomgenerator.py (right):

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/scripts/dartd...
sdk/lib/html/scripts/dartdomgenerator.py:175: print 'Extracting documentation
from HTML.'
_logger.info rather than print.

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/scripts/dartd...
sdk/lib/html/scripts/dartdomgenerator.py:175: print 'Extracting documentation
from HTML.'
Use of HTML is misleading (applies to class names as well)- this extracts
documentation from DOM types (dart:html, dart:svg, dart:web_audio, etc).

Tool should probably work on dart2js/dart then recurse into html, svg, audio,
etc.

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/scripts/dartd...
sdk/lib/html/scripts/dartdomgenerator.py:179: html_output_dir =
os.path.join(output_dir, 'dart2js/dart/html/')
SVG as well?

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/bin/ht...
File tools/html-json-doc/bin/htmlJsonDoc.dart (right):

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/bin/ht...
tools/html-json-doc/bin/htmlJsonDoc.dart:4: 
style guide has file names being lowercase_with_underscores.
http://www.dartlang.org/articles/style-guide/#names

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
File tools/html-json-doc/lib/HtmlToJson.dart (right):

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:158: //lineObject[nextLine] = comment;
I assume this is where duplicated lines are being hit?

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:286: String prettyPrintJson(Object json,
[depth = 0]) {
Probably (unfortunately) not now, but this should really be pushed into the JSON
serializer.

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:294: Strings.join(json.map((e) =>
prettyPrintJson(e, depth + 1)), ',\n');
StringBuffer-ize?

[sra1, 2012-11-26 20:36:57]

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
File tools/html-json-doc/lib/HtmlToJson.dart (right):

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:290: new List<String>(depth + 1).map((e)
=> ''), '  ');
Call it 'indentation'.
printSpaces looks like a verb so I expect it to be a function.

The +1 bothers me.
Strings.join(new List(depth).map((e) => '  '), '');

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Js...
File tools/html-json-doc/lib/JsonToHtml.dart (right):

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Js...
tools/html-json-doc/lib/JsonToHtml.dart:13: *           "$lineInHtml":
If you can change the format to

{
  "$filename":
    [
      {
        "line": "$lineInHtml",
        "comment":
          [
            "lines of comment",
            "here"
          ]
       },
       ...
    ],
  ...
}

Then it will be easier to upgrade by providing a new key based on the
library/class/member.

[blois, 2012-11-26 21:50:44]

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/dart2js/html_...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:72: }// Copyright (c) 2012, the Dart
project authors.  Please see the AUTHORS file
Should also add back the newline at the end of the file.

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
File tools/html-json-doc/lib/HtmlToJson.dart (right):

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:25: library htmlToJson;
library names should be html_to_json.

[Andrei Mouravski, 2012-11-26 23:24:11]

Sorry for a bajillion patches and all the renames. PTAL.

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/dart2js/html_...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:72: }// Copyright (c) 2012, the Dart
project authors.  Please see the AUTHORS file
On 2012/11/26 21:50:44, blois wrote:
> Should also add back the newline at the end of the file.

Done.

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/scripts/dartd...
File sdk/lib/html/scripts/dartdomgenerator.py (right):

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/scripts/dartd...
sdk/lib/html/scripts/dartdomgenerator.py:175: print 'Extracting documentation
from HTML.'
On 2012/11/26 20:07:43, blois wrote:
> _logger.info rather than print.

Done.

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/scripts/dartd...
sdk/lib/html/scripts/dartdomgenerator.py:175: print 'Extracting documentation
from HTML.'
On 2012/11/26 20:07:43, blois wrote:
> Use of HTML is misleading (applies to class names as well)- this extracts
> documentation from DOM types (dart:html, dart:svg, dart:web_audio, etc).
> 
> Tool should probably work on dart2js/dart then recurse into html, svg, audio,
> etc.

Done.

https://codereview.chromium.org/11412144/diff/4001/sdk/lib/html/scripts/dartd...
sdk/lib/html/scripts/dartdomgenerator.py:179: html_output_dir =
os.path.join(output_dir, 'dart2js/dart/html/')
On 2012/11/26 20:07:43, blois wrote:
> SVG as well?

Done.

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/bin/ht...
File tools/html-json-doc/bin/htmlJsonDoc.dart (right):

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/bin/ht...
tools/html-json-doc/bin/htmlJsonDoc.dart:4: 
On 2012/11/26 20:07:43, blois wrote:
> style guide has file names being lowercase_with_underscores.
> http://www.dartlang.org/articles/style-guide/#names

Done.

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
File tools/html-json-doc/lib/HtmlToJson.dart (right):

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:25: library htmlToJson;
On 2012/11/26 21:50:44, blois wrote:
> library names should be html_to_json.

Done.

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:158: //lineObject[nextLine] = comment;
On 2012/11/26 20:07:43, blois wrote:
> I assume this is where duplicated lines are being hit?

Yes. I'll print a warning.

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:286: String prettyPrintJson(Object json,
[depth = 0]) {
On 2012/11/26 20:07:43, blois wrote:
> Probably (unfortunately) not now, but this should really be pushed into the
JSON
> serializer.

Agreed.

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:290: new List<String>(depth + 1).map((e)
=> ''), '  ');
On 2012/11/26 20:36:57, sra1 wrote:
> Call it 'indentation'.
> printSpaces looks like a verb so I expect it to be a function.
> 
> The +1 bothers me.
> Strings.join(new List(depth).map((e) => '  '), '');
> 
> 

Done.

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Ht...
tools/html-json-doc/lib/HtmlToJson.dart:294: Strings.join(json.map((e) =>
prettyPrintJson(e, depth + 1)), ',\n');
On 2012/11/26 20:07:43, blois wrote:
> StringBuffer-ize?

In the interest of getting everything in, I'm putting this off for now.

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Js...
File tools/html-json-doc/lib/JsonToHtml.dart (right):

https://codereview.chromium.org/11412144/diff/4001/tools/html-json-doc/lib/Js...
tools/html-json-doc/lib/JsonToHtml.dart:13: *           "$lineInHtml":
On 2012/11/26 20:36:57, sra1 wrote:
> If you can change the format to
> 
> {
>   "$filename":
>     [
>       {
>         "line": "$lineInHtml",
>         "comment":
>           [
>             "lines of comment",
>             "here"
>           ]
>        },
>        ...
>     ],
>   ...
> }
> 
> Then it will be easier to upgrade by providing a new key based on the
> library/class/member.

Noted. I'm not too concerned about upgrading at the moment.

[Andrei Mouravski, 2012-11-27 00:18:29]

Okay, it should be good now.

[blois, 2012-11-27 00:21:43]

https://codereview.chromium.org/11412144/diff/13001/sdk/lib/html/scripts/html...
File sdk/lib/html/scripts/htmlrenamer.py (right):

https://codereview.chromium.org/11412144/diff/13001/sdk/lib/html/scripts/html...
sdk/lib/html/scripts/htmlrenamer.py:257: "MenuElement.compact",
Why this change?

[Andrei Mouravski, 2012-11-27 00:30:14]

PTAL.

https://codereview.chromium.org/11412144/diff/13001/sdk/lib/html/scripts/html...
File sdk/lib/html/scripts/htmlrenamer.py (right):

https://codereview.chromium.org/11412144/diff/13001/sdk/lib/html/scripts/html...
sdk/lib/html/scripts/htmlrenamer.py:257: "MenuElement.compact",
On 2012/11/27 00:21:43, blois wrote:
> Why this change?

I wanted to use MenuElement as a test to make sure everything worked, and I
noticed that compact was deprecated, figured I'd take it out while I was writing
the documentation.

[blois, 2012-11-27 00:31:44]

lgtm

Suppose it's good for now, I'm still concerned about the fragility of the JSON
file.