Lots of little changes for dartdoc/apidoc.

Lots of little changes for dartdoc/apidoc.

* Alphabetized imports.
* Added TODOs.
* Removed some prefixes.
* Cleaned up a LOT of async code to make it work better.
* Much, much, much friendlier status messages for dartdoc/apidoc. More to do...
* Prevented many, many bad warnings from showing up... by fixing them.
* Smarter finding of packages directories.
* Started using pathos all over the place.
* Added indexed_db to html_diff.

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

[Andrei Mouravski, 2013-03-08 02:14:12]

And this was all in the process of finding some other bugs.

Yay! Nicer looking code!

[Jacob, 2013-03-11 19:05:09]

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
File sdk/lib/_internal/dartdoc/lib/dartdoc.dart (right):

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:299: * Will print whether dartdoc is
running, whether dartdoc has finished
Remove the word "Will"

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:309: return 'Documentation in
progress. -- Documented $_totalsString so far.';
punctuation is a little odd

"Documentation in progress -- document $_totalsString so far."
would be more typical

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:321: String get _totalsString =>
Nit: I'd prefer a name like
_totalsSummary 
or 
_statisticsSummary

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:411: print('Analyzing libraries...');
Do these print statements help the user experience or make the tool output
cluttered? Consider using a logging library so that users can turn them on or
off.

https://codereview.chromium.org/12448006/diff/3001/utils/apidoc/apidoc.gyp
File utils/apidoc/apidoc.gyp (right):

https://codereview.chromium.org/12448006/diff/3001/utils/apidoc/apidoc.gyp#ne...
utils/apidoc/apidoc.gyp:56: '--exclude-lib=browser',
why are you excluding "browser"

[Andrei Mouravski, 2013-03-11 19:36:46]

PTAL.

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
File sdk/lib/_internal/dartdoc/lib/dartdoc.dart (right):

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:299: * Will print whether dartdoc is
running, whether dartdoc has finished
On 2013/03/11 19:05:09, Jacob wrote:
> Remove the word "Will"

Done.

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:309: return 'Documentation in
progress. -- Documented $_totalsString so far.';
On 2013/03/11 19:05:09, Jacob wrote:
> punctuation is a little odd
> 
> "Documentation in progress -- document $_totalsString so far."
> would be more typical

Done.

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:321: String get _totalsString =>
On 2013/03/11 19:05:09, Jacob wrote:
> Nit: I'd prefer a name like
> _totalsSummary 
> or 
> _statisticsSummary

Done.

https://codereview.chromium.org/12448006/diff/3001/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:411: print('Analyzing libraries...');
On 2013/03/11 19:05:09, Jacob wrote:
> Do these print statements help the user experience or make the tool output
> cluttered? Consider using a logging library so that users can turn them on or
> off.

I completely agree. Adding something like "machine readable" output is also
valuable, especially for the summary (so that the tests don't have to grep for
"Documented (\d) libraries..."

Is TODO okay for now? I filed:
https://code.google.com/p/dart/issues/detail?id=9061

https://codereview.chromium.org/12448006/diff/3001/utils/apidoc/apidoc.gyp
File utils/apidoc/apidoc.gyp (right):

https://codereview.chromium.org/12448006/diff/3001/utils/apidoc/apidoc.gyp#ne...
utils/apidoc/apidoc.gyp:56: '--exclude-lib=browser',
On 2013/03/11 19:05:09, Jacob wrote:
> why are you excluding "browser"

Because the browser package only includes a js file and right now apidoc tries
to go through all of the pkg/ directories and generate documentation.

This like here is just to prevent a warning from happening later.

[Jacob, 2013-03-11 20:00:46]

lgtm

[Andrei Mouravski, 2013-03-11 20:28:01]

Committed patchset #3 manually as r19817 (presubmit successful).