Several new features and improvements for dartdoc.

Several new features and improvements for dartdoc.

* Dartdoc now works on multiple libraries and entrypoints.
* A dartdoc/dartdoc.bat script is generated into dart-sdk/bin
* The API libraries recognized by dart2js using the 'dart:' prefix 
  have been updated to use the 'dart:*' name in their library tags.
  This makes the libraries show up with the correct prefix in the API docs.
* The processed libraries can be selected or limited, API
  libraries are not processed by default, and links to api.dartlang.org
  can be generated for API libraries. 
  
  Because of the changed library tags on API libraries, the generated 
  links don't current match the addresses on api.dartlang.org. 
  For instance, the docs for Object is currently located in 
  api.dartlang.org/core/Object.html, but with the new library
  tag 'dart:core', the address will be api.dartlang.org/dart_core/Object.html.
  The links will thus not work until api.dartlang.org have been updated with 
  this patch.
* Code and pre blocks use overflow-x:auto to support wide lines.

BUG=2656, 2686, 3533, 4029, 4145, 3555
Committed: https://code.google.com/p/dart/source/detail?r=9843

[floitsch, 2012-07-23 10:43:55]

LGTM, but I only skimmed over the create_sdk.py, build_helper.dart and gyp
changes. Maybe someone else could have a look at those.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart
File lib/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:353: /** Set this to generate link to the online API.
*/
links

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:356: /** Set this to select the libraries to include in
the documentation */
documentation.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:357: List<String> includeLibraries = null;
Wouldn't it be easier, if you initialized this with the empty list?

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:359: /** Set this to select the libraries to exclude
from the documentation */
documentation.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:360: List<String> excludeLibraries = null;
ditto (empty list).

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:400: bool includeLibrary(LibraryMirror library) {
not a boolean name.
shouldIncludeLibrary?

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:416: String suffix =
libraryName.substring('dart:'.length);
This code is duplicated here and below. Maybe create a method?

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:425: bool linkLibrary(LibraryMirror library) {
that's not a boolean name.
shouldLinkToPublicApi ?

http://codereview.chromium.org/10809035/diff/1/utils/apidoc/apidoc.dart
File utils/apidoc/apidoc.dart (right):

http://codereview.chromium.org/10809035/diff/1/utils/apidoc/apidoc.dart#newco...
utils/apidoc/apidoc.dart:106: var apidocLibraries = new List<Path>();
= <Path>[];

[Bob Nystrom, 2012-07-23 17:04:30]

This is awesome!

http://codereview.chromium.org/10809035/diff/1/lib/compiler/implementation/li...
File lib/compiler/implementation/library_map.dart (right):

http://codereview.chromium.org/10809035/diff/1/lib/compiler/implementation/li...
lib/compiler/implementation/library_map.dart:18: final bool internal;
Boolean properties should usually start with "is", "has" or (rarely) "can". How
about "isInternal"?

http://codereview.chromium.org/10809035/diff/1/lib/compiler/implementation/li...
lib/compiler/implementation/library_map.dart:27: final Map<String,LibraryInfo>
DART2JS_LIBRARY_MAP
Space after ",".

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart
File lib/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:76: List<Path> entrypoints = new List<Path>();
final entrypoints = <Path>[];

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:111: dartdoc.includeAPI = true;
Should be "includeApi".

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:357: List<String> includeLibraries = null;
On 2012/07/23 10:43:56, floitsch wrote:
> Wouldn't it be easier, if you initialized this with the empty list?

+1.

Also, I would name it "includedLibraries", or, better, just "libraries". Field
names should be noun phrases.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:360: List<String> excludeLibraries = null;
"excludedLibraries"

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:400: bool includeLibrary(LibraryMirror library) {
On 2012/07/23 10:43:56, floitsch wrote:
> not a boolean name.
> shouldIncludeLibrary?

+1. Also, needs a doc comment.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:401: if (linkLibrary(library)) {
It's up to you, but if you like, the style guide does allow for single line ifs
for cases like this:

if (linkLibrary(library)) return false;

http://codereview.chromium.org/10809035/diff/1/tools/create_sdk.py
File tools/create_sdk.py (right):

http://codereview.chromium.org/10809035/diff/1/tools/create_sdk.py#newcode148
tools/create_sdk.py:148: dartdoc = os.path.join(sdk_root, 'bin', 'dartdoc.bat')
Take a look at CopyShellScript() and see if you can use that here.

[Johnni Winther, 2012-07-24 08:49:16]

http://codereview.chromium.org/10809035/diff/1/lib/compiler/implementation/li...
File lib/compiler/implementation/library_map.dart (right):

http://codereview.chromium.org/10809035/diff/1/lib/compiler/implementation/li...
lib/compiler/implementation/library_map.dart:18: final bool internal;
On 2012/07/23 17:04:31, Bob Nystrom wrote:
> Boolean properties should usually start with "is", "has" or (rarely) "can".
How
> about "isInternal"?

Done.

http://codereview.chromium.org/10809035/diff/1/lib/compiler/implementation/li...
lib/compiler/implementation/library_map.dart:27: final Map<String,LibraryInfo>
DART2JS_LIBRARY_MAP
On 2012/07/23 17:04:31, Bob Nystrom wrote:
> Space after ",".

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart
File lib/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:76: List<Path> entrypoints = new List<Path>();
On 2012/07/23 17:04:31, Bob Nystrom wrote:
> final entrypoints = <Path>[];

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:111: dartdoc.includeAPI = true;
On 2012/07/23 17:04:31, Bob Nystrom wrote:
> Should be "includeApi".

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:353: /** Set this to generate link to the online API.
*/
On 2012/07/23 10:43:56, floitsch wrote:
> links

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:356: /** Set this to select the libraries to include in
the documentation */
On 2012/07/23 10:43:56, floitsch wrote:
> documentation.

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:357: List<String> includeLibraries = null;
On 2012/07/23 10:43:56, floitsch wrote:
> Wouldn't it be easier, if you initialized this with the empty list?

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:357: List<String> includeLibraries = null;
On 2012/07/23 10:43:56, floitsch wrote:
> Wouldn't it be easier, if you initialized this with the empty list?

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:359: /** Set this to select the libraries to exclude
from the documentation */
On 2012/07/23 10:43:56, floitsch wrote:
> documentation.

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:360: List<String> excludeLibraries = null;
On 2012/07/23 10:43:56, floitsch wrote:
> ditto (empty list).

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:360: List<String> excludeLibraries = null;
On 2012/07/23 10:43:56, floitsch wrote:
> ditto (empty list).

Done.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:416: String suffix =
libraryName.substring('dart:'.length);
On 2012/07/23 10:43:56, floitsch wrote:
> This code is duplicated here and below. Maybe create a method?

They are slightly different.

http://codereview.chromium.org/10809035/diff/1/lib/dartdoc/dartdoc.dart#newco...
lib/dartdoc/dartdoc.dart:425: bool linkLibrary(LibraryMirror library) {
On 2012/07/23 10:43:56, floitsch wrote:
> that's not a boolean name.
> shouldLinkToPublicApi ?

Done.

http://codereview.chromium.org/10809035/diff/1/tools/create_sdk.py
File tools/create_sdk.py (right):

http://codereview.chromium.org/10809035/diff/1/tools/create_sdk.py#newcode148
tools/create_sdk.py:148: dartdoc = os.path.join(sdk_root, 'bin', 'dartdoc.bat')
On 2012/07/23 17:04:31, Bob Nystrom wrote:
> Take a look at CopyShellScript() and see if you can use that here.

I tried but it didn't work. It seems to do something more that just the '.bat'
part.

http://codereview.chromium.org/10809035/diff/1/utils/apidoc/apidoc.dart
File utils/apidoc/apidoc.dart (right):

http://codereview.chromium.org/10809035/diff/1/utils/apidoc/apidoc.dart#newco...
utils/apidoc/apidoc.dart:106: var apidocLibraries = new List<Path>();
On 2012/07/23 10:43:56, floitsch wrote:
> = <Path>[];

Done.

[Bob Nystrom, 2012-07-24 17:14:44]

LGTM!