Get dartdoc in the SDK and working correctly.

Get dartdoc in the SDK and working correctly.

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

[Bob Nystrom, 2012-03-01 01:32:52]

Note that apidoc isn't here because I don't think we expect that to be part of
the SDK.

Dartdoc currently gives a couple of noisy warnings when it runs but it does work
correctly. When I get a chance, I'll investigate those and try to clean them up.

[dgrove, 2012-03-01 08:38:00]

Can you please make the move from utils/dartdoc to lib/dartdoc ?

https://chromiumcodereview.appspot.com/9555013/diff/1/tools/create_sdk.py
File tools/create_sdk.py (right):

https://chromiumcodereview.appspot.com/9555013/diff/1/tools/create_sdk.py#new...
tools/create_sdk.py:291: dartdoc_src_dir = join(HOME, 'utils', 'dartdoc')
I think we should move dartdoc from utils/dartdoc to lib/dartdoc as part of this
change.

https://chromiumcodereview.appspot.com/9555013/diff/1/tools/create_sdk.py#new...
tools/create_sdk.py:311: ("#import\('../../frog", "#import('../frog")
it would be nice if ReplaceInFile were ReplaceInFiles.

[Bob Nystrom, 2012-03-01 23:03:27]

Thanks!

I'd like to move dartdoc (and maybe apidoc) in the repo too, but I'm still not
sure what to do about the tests. I would love it if they were with their
respective libraries (i.e. dart/lib/dartdoc/tests) but I'm up for whatever.

https://chromiumcodereview.appspot.com/9555013/diff/1/tools/create_sdk.py
File tools/create_sdk.py (right):

https://chromiumcodereview.appspot.com/9555013/diff/1/tools/create_sdk.py#new...
tools/create_sdk.py:291: dartdoc_src_dir = join(HOME, 'utils', 'dartdoc')
On 2012/03/01 08:38:00, dgrove wrote:
> I think we should move dartdoc from utils/dartdoc to lib/dartdoc as part of
this
> change.

Should we move apidoc there too?

More important question, what about the tests? Where do those go?

[Bob Nystrom, 2012-03-02 21:36:51]

OK, moved dartdoc over to lib and wired up the tests the same way the other
stuff in lib/ is setup.

Adding Siggy to try to get an LGTM today before I go on vacation next week.

[dgrove, 2012-03-02 21:48:29]

lgtm

https://chromiumcodereview.appspot.com/9555013/diff/6002/lib/dartdoc/ast.dart
File lib/dartdoc/ast.dart (right):

https://chromiumcodereview.appspot.com/9555013/diff/6002/lib/dartdoc/ast.dart...
lib/dartdoc/ast.dart:1: // Copyright (c) 2011, the Dart project authors.  Please
see the AUTHORS file
please update copyrights throughout.

[Bob Nystrom, 2012-03-02 21:54:28]

Thanks!

https://chromiumcodereview.appspot.com/9555013/diff/6002/lib/dartdoc/ast.dart
File lib/dartdoc/ast.dart (right):

https://chromiumcodereview.appspot.com/9555013/diff/6002/lib/dartdoc/ast.dart...
lib/dartdoc/ast.dart:1: // Copyright (c) 2011, the Dart project authors.  Please
see the AUTHORS file
On 2012/03/02 21:48:29, dgrove wrote:
> please update copyrights throughout.

Done.

[Ivan Posva, 2012-03-02 22:58:55]

I don't think dartdoc is a general library that should live in lib/. Granted it
is a library, but I cannot see any use of it outside of the apidoc utility.

-Ivan

[Bob Nystrom, 2012-03-02 23:07:42]

On 2012/03/02 22:58:55, Ivan Posva wrote:
> I don't think dartdoc is a general library that should live in lib/. Granted
it
> is a library, but I cannot see any use of it outside of the apidoc utility.

Dartdoc is like Javadoc (and RDoc, godoc, ReStructured Text, etc.): it's a
general purpose application/library for generating documentation from any Dart
code. Apidoc is the only thing in the repo that uses it directly, but we have
Dart users outside of Google that use it.

- bob

[ahe, 2012-03-03 08:57:16]

On 2012/03/02 23:07:42, Bob Nystrom wrote:
> On 2012/03/02 22:58:55, Ivan Posva wrote:
> > I don't think dartdoc is a general library that should live in lib/. Granted
> it
> > is a library, but I cannot see any use of it outside of the apidoc utility.
> 
> Dartdoc is like Javadoc (and RDoc, godoc, ReStructured Text, etc.): it's a
> general purpose application/library for generating documentation from any Dart
> code. Apidoc is the only thing in the repo that uses it directly, but we have
> Dart users outside of Google that use it.
> 
> - bob

And just like javadoc, dartdoc should not be part of the platform APIs. It is a
tool, not an API. If it is an API, you have gotten ahead of yourself as the API
isn't based on mirrors.

[ahe, 2012-03-03 08:59:15]

https://chromiumcodereview.appspot.com/9555013/diff/10070/frog/presubmit.py
File frog/presubmit.py (right):

https://chromiumcodereview.appspot.com/9555013/diff/10070/frog/presubmit.py#n...
frog/presubmit.py:153: cmd = test_cmd + ['--component=vm', 'utils']
The tests are ordered by "first crawl, then walk, then run". This means that the
Leg unit tests needs to run first, dartdoc should be last.

In the future, please do not make any changes to the Frog/Leg build
infrastructure without consulting with me first.

[dgrove, 2012-03-03 10:58:02]

It is an API and a tool. Once we have a mirror implementation, then that could
clearly change. 

As of now, we don't have mirrors, and we do have a need for a library that can
generate docs from dart code.

If we don't keep this in lib, where do you suggest putting it, given that there
are users of the API?


On 2012/03/03 08:57:16, ahe wrote:
> On 2012/03/02 23:07:42, Bob Nystrom wrote:
> > On 2012/03/02 22:58:55, Ivan Posva wrote:
> > > I don't think dartdoc is a general library that should live in lib/.
Granted
> > it
> > > is a library, but I cannot see any use of it outside of the apidoc
utility.
> > 
> > Dartdoc is like Javadoc (and RDoc, godoc, ReStructured Text, etc.): it's a
> > general purpose application/library for generating documentation from any
Dart
> > code. Apidoc is the only thing in the repo that uses it directly, but we
have
> > Dart users outside of Google that use it.
> > 
> > - bob
> 
> And just like javadoc, dartdoc should not be part of the platform APIs. It is
a
> tool, not an API. If it is an API, you have gotten ahead of yourself as the
API
> isn't based on mirrors.

[ahe, 2012-03-03 11:00:51]

We need to provide dart docs for http://dartlang.org and perhaps the Dart
Editor.

Both of these should be able to do with a tool.

What else are you thinking about?

Cheers,
Peter

On 2012/03/03 10:58:02, dgrove wrote:
> It is an API and a tool. Once we have a mirror implementation, then that could
> clearly change. 
> 
> As of now, we don't have mirrors, and we do have a need for a library that can
> generate docs from dart code.
> 
> If we don't keep this in lib, where do you suggest putting it, given that
there
> are users of the API?
> 
> 
> On 2012/03/03 08:57:16, ahe wrote:
> > On 2012/03/02 23:07:42, Bob Nystrom wrote:
> > > On 2012/03/02 22:58:55, Ivan Posva wrote:
> > > > I don't think dartdoc is a general library that should live in lib/.
> Granted
> > > it
> > > > is a library, but I cannot see any use of it outside of the apidoc
> utility.
> > > 
> > > Dartdoc is like Javadoc (and RDoc, godoc, ReStructured Text, etc.): it's a
> > > general purpose application/library for generating documentation from any
> Dart
> > > code. Apidoc is the only thing in the repo that uses it directly, but we
> have
> > > Dart users outside of Google that use it.
> > > 
> > > - bob
> > 
> > And just like javadoc, dartdoc should not be part of the platform APIs. It
is
> a
> > tool, not an API. If it is an API, you have gotten ahead of yourself as the
> API
> > isn't based on mirrors.