Add support for documentation comments to most of AstBuilder.

Add support for documentation comments to most of AstBuilder.

This CL addresses all use cases except for documentation comments on
type parameter formals.

R=scheglov@google.com

Committed: https://github.com/dart-lang/sdk/commit/a6ee0dfd3f04f1236a072191e9da17ede8467d4a

[Paul Berry, 2017-03-07 22:14:45]

paulberry@google.com changed reviewers:
+ ahe@google.com, scheglov@google.com

[scheglov, 2017-03-07 22:17:29]

LGTM

[Paul Berry, 2017-03-07 22:19:57]

Description was changed from

==========
Add support for documentation comments to most of AstBuilder.

This CL addresses all use cases except for documentation comments on
type parameter formals.
==========

to

==========
Add support for documentation comments to most of AstBuilder.

This CL addresses all use cases except for documentation comments on
type parameter formals.

R=scheglov@google.com

Committed:
https://github.com/dart-lang/sdk/commit/a6ee0dfd3f04f1236a072191e9da17ede8467d4a
==========

[Paul Berry, 2017-03-07 22:19:58]

Committed patchset #1 (id:1) manually as
a6ee0dfd3f04f1236a072191e9da17ede8467d4a (presubmit successful).

[ahe, 2017-03-09 13:56:01]

lgtm

I'm pleasantly surprised how well this integrates with what appears to be little
overhead or complexity.

https://codereview.chromium.org/2732363002/diff/1/pkg/analyzer/test/generated...
File pkg/analyzer/test/generated/parser_test.dart (right):

https://codereview.chromium.org/2732363002/diff/1/pkg/analyzer/test/generated...
pkg/analyzer/test/generated/parser_test.dart:359: var constructor =
parser.parseClassMember('C') as ConstructorDeclaration;
Why don't you just put the type on the variable?

[Paul Berry, 2017-03-09 16:42:04]

https://codereview.chromium.org/2732363002/diff/1/pkg/analyzer/test/generated...
File pkg/analyzer/test/generated/parser_test.dart (right):

https://codereview.chromium.org/2732363002/diff/1/pkg/analyzer/test/generated...
pkg/analyzer/test/generated/parser_test.dart:359: var constructor =
parser.parseClassMember('C') as ConstructorDeclaration;
On 2017/03/09 13:56:01, ahe wrote:
> Why don't you just put the type on the variable?

Two reasons:

1. it makes the downcast obvious.  A casual reader might see
"ConstructorDeclaration constructor = parser.parseClassMember('C');" and fail to
notice that the assignment might fail if parseClassMember returns the wrong
type.

2. it guarantees that if parseClassMember returns the wrong type, we will get a
test failure regardless of whether the test is running in checked mode.