Generate separate json files for each library.

Generate separate json files for each library and include the  version #.


BUG=

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

[Jacob, 2013-02-08 19:50:38]

Sigmund, can you review the .gyp and tools/list_version.py changes?

amouravski, can you review the dartdoc changes?

-Jacob

[Siggi Cherem (dart-lang), 2013-02-08 21:14:13]

lgtm on the gyp changes

[Jacob, 2013-02-08 21:37:14]

ahe, is it alright if I add this tiny util .py script to the tools directory?

[Andrei Mouravski, 2013-02-08 23:36:31]

What's going to happen if someone tries to run dartdoc on their own libraries?

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

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:152: * For our purposes we treat the
dart core libraries as a package.
Either "... the `dart:core` library..." or "... the core Dart libraries..."

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:161: /** Descriptive string
describing the version# of the package. */
What makes the string "descriptive"? Is that like, "myAwesomeVersion" or is it
like, "1.2.3+52-alpha"?

Maybe add a link if that's the semantic version or whatever.

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:163: /** Source control revision # of
the package. */
What do you mean by revision #? Is this like build r18230 of the SDK? Or is it
the git hash?

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:166: String location;
Is this the lib dir or the src dir. How does this location work?

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
File sdk/lib/_internal/dartdoc/lib/universe_serializer.dart (right):

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/universe_serializer.dart:231: /** Upper bound for
the parameter. */
What does upper bound mean?

https://codereview.chromium.org/12217077/diff/1007/tools/list_version.py
File tools/list_version.py (right):

https://codereview.chromium.org/12217077/diff/1007/tools/list_version.py#newc...
tools/list_version.py:7: # A script which will be invoked from gyp to list the
current version.
Current version of what?

https://codereview.chromium.org/12217077/diff/1007/utils/apidoc/apidoc.dart
File utils/apidoc/apidoc.dart (right):

https://codereview.chromium.org/12217077/diff/1007/utils/apidoc/apidoc.dart#n...
utils/apidoc/apidoc.dart:172: Apidoc(this.mdn, Path outputDir, int mode,
Put the newline back in.

[Jacob, 2013-02-09 02:37:28]

PTAL

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

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:152: * For our purposes we treat the
dart core libraries as a package.
On 2013/02/08 23:36:31, Andrei Mouravski wrote:
> Either "... the `dart:core` library..." or "... the core Dart libraries..."

Done.

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:161: /** Descriptive string
describing the version# of the package. */
On 2013/02/08 23:36:31, Andrei Mouravski wrote:
> What makes the string "descriptive"? Is that like, "myAwesomeVersion" or is it
> like, "1.2.3+52-alpha"?
> 
> Maybe add a link if that's the semantic version or whatever.

   * The current format for dart-sdk versions is
   * $MAJOR.$MINOR.$BUILD.$PATCH$revisionString$userNameString
   * For example: 0.1.2.0_r18233_johndoe

Done.

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:163: /** Source control revision # of
the package. */
On 2013/02/08 23:36:31, Andrei Mouravski wrote:
> What do you mean by revision #? Is this like build r18230 of the SDK? Or is it
> the git hash?
currently 18233 for SVN.  Will use hashes for git.

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:163: /** Source control revision # of
the package. */
On 2013/02/08 23:36:31, Andrei Mouravski wrote:
> What do you mean by revision #? Is this like build r18230 of the SDK? Or is it
> the git hash?
   * Source control revision number for the package. For SVN this is a number
   * while for GIT it is a hash.

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/dartdoc.dart:166: String location;
On 2013/02/08 23:36:31, Andrei Mouravski wrote:
> Is this the lib dir or the src dir. How does this location work?
This is for the serialized version (json) for the libraries in the package.

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
File sdk/lib/_internal/dartdoc/lib/universe_serializer.dart (right):

https://codereview.chromium.org/12217077/diff/1007/sdk/lib/_internal/dartdoc/...
sdk/lib/_internal/dartdoc/lib/universe_serializer.dart:231: /** Upper bound for
the parameter. */
On 2013/02/08 23:36:31, Andrei Mouravski wrote:
> What does upper bound mean?
Dart support upper bound syntax for generics.
For example:
class Bar<T extends Foo>

Added an example to the documentation.

https://codereview.chromium.org/12217077/diff/1007/tools/list_version.py
File tools/list_version.py (right):

https://codereview.chromium.org/12217077/diff/1007/tools/list_version.py#newc...
tools/list_version.py:7: # A script which will be invoked from gyp to list the
current version.
On 2013/02/08 23:36:31, Andrei Mouravski wrote:
> Current version of what?
of the sdk

https://codereview.chromium.org/12217077/diff/1007/utils/apidoc/apidoc.dart
File utils/apidoc/apidoc.dart (right):

https://codereview.chromium.org/12217077/diff/1007/utils/apidoc/apidoc.dart#n...
utils/apidoc/apidoc.dart:172: Apidoc(this.mdn, Path outputDir, int mode,
On 2013/02/08 23:36:31, Andrei Mouravski wrote:
> Put the newline back in.

Done.

[Andrei Mouravski, 2013-02-09 02:57:27]

lgtm

[ahe, 2013-02-09 11:54:20]

GYP and tools/ changes LGTM, if this is what you want.

I suggest you rename list_version.py to print_version.py.

https://codereview.chromium.org/12217077/diff/10003/tools/list_version.py
File tools/list_version.py (right):

https://codereview.chromium.org/12217077/diff/10003/tools/list_version.py#new...
tools/list_version.py:7: # A script which will be invoked from gyp to list the
current version of the
Perhaps my English is flawed but isn't it "print" rather than "list"?

https://codereview.chromium.org/12217077/diff/10003/utils/apidoc/apidoc.gyp
File utils/apidoc/apidoc.gyp (right):

https://codereview.chromium.org/12217077/diff/10003/utils/apidoc/apidoc.gyp#n...
utils/apidoc/apidoc.gyp:49: '--version=<!@(["python",
"../../tools/list_version.py"])',
The value is captured when you run GYP, not when you build. Is that what you
expect?

https://codereview.chromium.org/12217077/diff/10003/utils/apidoc/apidoc.gyp#n...
utils/apidoc/apidoc.gyp:50: '--pkg=<(PRODUCT_DIR)/packages/',
I think I spotted a problem here. We are not listing the contents of the
../../pkg. You should probably include that in line 35 above.

[Jacob, 2013-02-11 01:44:11]

https://codereview.chromium.org/12217077/diff/10003/tools/list_version.py
File tools/list_version.py (right):

https://codereview.chromium.org/12217077/diff/10003/tools/list_version.py#new...
tools/list_version.py:7: # A script which will be invoked from gyp to list the
current version of the
On 2013/02/09 11:54:20, ahe wrote:
> Perhaps my English is flawed but isn't it "print" rather than "list"?
I've renamed it to print.

https://codereview.chromium.org/12217077/diff/10003/utils/apidoc/apidoc.gyp
File utils/apidoc/apidoc.gyp (right):

https://codereview.chromium.org/12217077/diff/10003/utils/apidoc/apidoc.gyp#n...
utils/apidoc/apidoc.gyp:49: '--version=<!@(["python",
"../../tools/list_version.py"])',
On 2013/02/09 11:54:20, ahe wrote:
> The value is captured when you run GYP, not when you build. Is that what you
> expect?

I think it should be fine for print_version.py to run at GYP generation time. I
can't think of a reasonable case where you'd want to publish docs but have
synced to a newer version without executing "gclient runhooks" 
I don't really know gyp that well. I'm assuming that when you run "gclient
runhooks", the python script will run even if none of the listed dependencies or
inputs have changed.

https://codereview.chromium.org/12217077/diff/10003/utils/apidoc/apidoc.gyp#n...
utils/apidoc/apidoc.gyp:50: '--pkg=<(PRODUCT_DIR)/packages/',
On 2013/02/09 11:54:20, ahe wrote:
> I think I spotted a problem here. We are not listing the contents of the
> ../../pkg. You should probably include that in line 35 above.
Interesting but unrelated to this cl. I'll follow up separately with the pub
team to see if we are specifying the wrong pkg directory.

[ahe, 2013-02-11 07:27:56]

https://codereview.chromium.org/12217077/diff/10003/utils/apidoc/apidoc.gyp
File utils/apidoc/apidoc.gyp (right):

https://codereview.chromium.org/12217077/diff/10003/utils/apidoc/apidoc.gyp#n...
utils/apidoc/apidoc.gyp:49: '--version=<!@(["python",
"../../tools/list_version.py"])',
On 2013/02/11 01:44:11, Jacob wrote:
> On 2013/02/09 11:54:20, ahe wrote:
> > The value is captured when you run GYP, not when you build. Is that what you
> > expect?
> 
> I think it should be fine for print_version.py to run at GYP generation time.
I
> can't think of a reasonable case where you'd want to publish docs but have
> synced to a newer version without executing "gclient runhooks" 
> I don't really know gyp that well. I'm assuming that when you run "gclient
> runhooks", the python script will run even if none of the listed dependencies
or
> inputs have changed. 

Correct. This is why we shouldn't list list_version.py as a dependency. It isn't
used at build time.