Resolve comments lazily and re-evaluate inherited comments for subclasses

Resolve comments lazily and re-evaluate inherited comments for subclasses

R=efortuna@google.com

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

[Alan Knight, 2013-11-15 23:17:56]

Resolve comments lazily so that we have all the information we need at the time.
Specifically, if we have references inside a package, we may not know the
package while we're constructing a Method. So save a commentFunction closure
that we evaluate only when we need the comment.

Gets rid of the global _current* and linkResolver in favour of closing over the
current mirror and using that to provide the context for the linkResolver.

We also need to re-evaluate comments in subclasses so that references point to
the subclass versions of things. This requires us to save the mirror when we
create an Indexable and use it when we re-evaluate.

The page for DefaultEquality is a good example for this. It has inherited
comments with references and we also need the inherited from Equality references
to be package qualified.

[Emily Fortuna, 2013-11-18 21:00:41]

Before you commit this, just for grins, can you generate docs before and after
this change and diff the two just to make sure nothing was lost? I ran into a
couple of strange corner cases when I was doing link resolving.

lgtm. just nits.

https://codereview.chromium.org/63193006/diff/1/pkg/docgen/lib/docgen.dart
File pkg/docgen/lib/docgen.dart (left):

https://codereview.chromium.org/63193006/diff/1/pkg/docgen/lib/docgen.dart#ol...
pkg/docgen/lib/docgen.dart:55: LibraryMirror _currentLibrary;
yay! :-)

https://codereview.chromium.org/63193006/diff/1/pkg/docgen/lib/docgen.dart
File pkg/docgen/lib/docgen.dart (right):

https://codereview.chromium.org/63193006/diff/1/pkg/docgen/lib/docgen.dart#ne...
pkg/docgen/lib/docgen.dart:949: bool _commentsEnsured = false;
comment explaining this variable?

https://codereview.chromium.org/63193006/diff/1/pkg/docgen/lib/docgen.dart#ne...
pkg/docgen/lib/docgen.dart:955: : super(name, commentFunction, isPrivate, owner,
mirror) {
you can take out the { } and just have a semicolon if the body is empty here.

[Alan Knight, 2013-11-18 22:04:46]

Tricky to diff json files if they're not identical, but from inspection it
appears that the only change is that we're not prepending the package on things
that don't need it, e.g. analyzer/dart-core.Object. The viewer would check for
the unqualified version anyway.

https://codereview.chromium.org/63193006/diff/1/pkg/docgen/lib/docgen.dart
File pkg/docgen/lib/docgen.dart (right):

https://codereview.chromium.org/63193006/diff/1/pkg/docgen/lib/docgen.dart#ne...
pkg/docgen/lib/docgen.dart:949: bool _commentsEnsured = false;
On 2013/11/18 21:00:41, Emily Fortuna wrote:
> comment explaining this variable?

Done.

https://codereview.chromium.org/63193006/diff/1/pkg/docgen/lib/docgen.dart#ne...
pkg/docgen/lib/docgen.dart:955: : super(name, commentFunction, isPrivate, owner,
mirror) {
On 2013/11/18 21:00:41, Emily Fortuna wrote:
> you can take out the { } and just have a semicolon if the body is empty here.

Done.

[Alan Knight, 2013-11-18 22:05:52]

Committed patchset #2 manually as r30379 (presubmit successful).