Cache element docs (and add to completions) (#23694).

Cache element docs (and add to completions) [#23694].

This does away with the expensive call to `computeDocumentationComment` in favor of cached comments.  Notably this makes adding doc content to code completion proposals performant (and so is done here).  It should also make `dartdoc` *much* faster for doc generation since there are no more trips to disk to fetch comments  for elements (still needed for source though).

For more on the desire for docs in completions see here: https://github.com/dart-lang/sdk/issues/23694

R=brianwilkerson@google.com, scheglov@google.com

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

[pquitslund, 2015-12-17 22:05:23]

pquitslund@google.com changed reviewers:
+ brianwilkerson@google.com, scheglov@google.com

[scheglov, 2015-12-17 22:10:14]

LGTM

https://codereview.chromium.org/1534043002/diff/1/pkg/analyzer/lib/src/dart/e...
File pkg/analyzer/lib/src/dart/element/element.dart (right):

https://codereview.chromium.org/1534043002/diff/1/pkg/analyzer/lib/src/dart/e...
pkg/analyzer/lib/src/dart/element/element.dart:1717: SourceRange get docRange {
Did we decide to remove this?

https://codereview.chromium.org/1534043002/diff/1/pkg/analyzer/lib/src/dart/e...
pkg/analyzer/lib/src/dart/element/element.dart:3810: // TODO: implement
documentationComment
Did you want to fix this in this CL?

[pquitslund, 2015-12-17 22:12:56]

Thank you!

https://codereview.chromium.org/1534043002/diff/1/pkg/analyzer/lib/src/dart/e...
File pkg/analyzer/lib/src/dart/element/element.dart (right):

https://codereview.chromium.org/1534043002/diff/1/pkg/analyzer/lib/src/dart/e...
pkg/analyzer/lib/src/dart/element/element.dart:1717: SourceRange get docRange {
On 2015/12/17 22:10:14, scheglov wrote:
> Did we decide to remove this?

We did and then reconsidered.  It would break API and no one is quite ready for
that pain again quite yet. ;)

https://codereview.chromium.org/1534043002/diff/1/pkg/analyzer/lib/src/dart/e...
pkg/analyzer/lib/src/dart/element/element.dart:3810: // TODO: implement
documentationComment
On 2015/12/17 22:10:14, scheglov wrote:
> Did you want to fix this in this CL?

Whoops!  Yes.  Thanks!

[Brian Wilkerson, 2015-12-17 22:51:17]

LGTM

https://codereview.chromium.org/1534043002/diff/20001/pkg/analysis_server/tes...
File
pkg/analysis_server/test/services/completion/dart/imported_reference_contributor_test.dart
(right):

https://codereview.chromium.org/1534043002/diff/20001/pkg/analysis_server/tes...
pkg/analysis_server/test/services/completion/dart/imported_reference_contributor_test.dart:69:
test_doc_function() async {
We should add a test with c-style comments (or convert one of these to use
them).

https://codereview.chromium.org/1534043002/diff/20001/pkg/analyzer/lib/dart/e...
File pkg/analyzer/lib/dart/element/element.dart (right):

https://codereview.chromium.org/1534043002/diff/20001/pkg/analyzer/lib/dart/e...
pkg/analyzer/lib/dart/element/element.dart:562: * or `null` if this element does
not or cannot have a documentation.
I know you copied the comment, but...

Not clear what "source content" means. Perhaps just "content" and then add
something that clarifies that the content includes the delimiters.

"a documentation" --> "documentation"

https://codereview.chromium.org/1534043002/diff/20001/pkg/analyzer/lib/dart/e...
pkg/analyzer/lib/dart/element/element.dart:570: * Deprecated.  Use
[documentationComment] instead.
Not exactly a replacement...

[pquitslund, 2015-12-18 04:56:50]

Thanks!

https://codereview.chromium.org/1534043002/diff/20001/pkg/analysis_server/tes...
File
pkg/analysis_server/test/services/completion/dart/imported_reference_contributor_test.dart
(right):

https://codereview.chromium.org/1534043002/diff/20001/pkg/analysis_server/tes...
pkg/analysis_server/test/services/completion/dart/imported_reference_contributor_test.dart:69:
test_doc_function() async {
On 2015/12/17 22:51:17, Brian Wilkerson wrote:
> We should add a test with c-style comments (or convert one of these to use
> them).

Good call.  Done.

https://codereview.chromium.org/1534043002/diff/20001/pkg/analyzer/lib/dart/e...
File pkg/analyzer/lib/dart/element/element.dart (right):

https://codereview.chromium.org/1534043002/diff/20001/pkg/analyzer/lib/dart/e...
pkg/analyzer/lib/dart/element/element.dart:562: * or `null` if this element does
not or cannot have a documentation.
On 2015/12/17 22:51:17, Brian Wilkerson wrote:
> I know you copied the comment, but...
> 
> Not clear what "source content" means. Perhaps just "content" and then add
> something that clarifies that the content includes the delimiters.
> 
> "a documentation" --> "documentation"

Done.

https://codereview.chromium.org/1534043002/diff/20001/pkg/analyzer/lib/dart/e...
pkg/analyzer/lib/dart/element/element.dart:570: * Deprecated.  Use
[documentationComment] instead.
On 2015/12/17 22:51:17, Brian Wilkerson wrote:
> Not exactly a replacement...

Acknowledged.

[pquitslund, 2015-12-18 05:07:46]

Description was changed from

==========
Cache element docs (and add to completions) [#23694].

This does away with the expensive call to `computeDocumentationComment` in favor
of cached comments.  Notably this makes adding doc content to code completion
proposals performant (and so is done here).  It should also make `dartdoc`
*much* faster for doc generation since there are no more trips to disk to fetch
comments  for elements (still needed for source though).

For more on the desire for docs in completions see here:
https://github.com/dart-lang/sdk/issues/23694
==========

to

==========
Cache element docs (and add to completions) [#23694].

This does away with the expensive call to `computeDocumentationComment` in favor
of cached comments.  Notably this makes adding doc content to code completion
proposals performant (and so is done here).  It should also make `dartdoc`
*much* faster for doc generation since there are no more trips to disk to fetch
comments  for elements (still needed for source though).

For more on the desire for docs in completions see here:
https://github.com/dart-lang/sdk/issues/23694

R=brianwilkerson@google.com, scheglov@google.com

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

[pquitslund, 2015-12-18 05:07:47]

Committed patchset #3 (id:40001) manually as
1f8eddcc2113ed5a0474520455582066a3ce6aaf (presubmit successful).