No docs in code completion

[bwilkerson]

The CompletionSuggestion should have a value for the docSummary and docComplete fields when the source code has documentation, but they don't. For example, asking for code completion at the end of the next-to-last line in this sample code will return null (missing) fields:

/// This is a dummy method.
///
/// But I'm no dummy!
noDoc() {
}

main() {
  noDo
}

[devoncarew]

I ran into this as well; it would be great to be able to preview dartdoc info when completing methods.

[scheglov]

I remember that:

1. In Dart Editor we decided to use analysis.getHover to get documentation.
2. Couple months ago we discussed this again and... I don't remember the resolution, but I remember that @lukechurch was concerned about amount of data.

I'm also concerned about amount of work we would need to perform to extract documentation for each CompletionSuggestion.

Also, could one of the clients remind me what is, or what do they expect to see in docSummary?
What's the difference between it and method signature, which can be composed using element?
@danrubel , do you remember?

[devoncarew]

docSummary would I assume be the first markdown paragraph from the dartdoc documentation. The Atom client will likely never use the docComplete field. Perhaps that field could be deprecated.

I'm also concerned about amount of work we would need to perform to extract documentation for each CompletionSuggestion.

Can we implement it, and measure the actual cost? If we do see a significant cost to populating the field, this could be something that clients opt into.

[scheglov]

https://codereview.chromium.org/1380223003/

[scheglov]

I'm coping this performance difference from the CL.

For the first time when we complete top-level elements, such as "Str^" it takes
about 500-600 ms vs. 300 ms without documentation.
For the second and subsequent completions difference is not so high, but still
exists.

For prefixed completions difference is pretty high - 15 ms vs. 3 ms for
stringLiteral.^ completion.
I.e. documentation makes it 5 times more expensive.

I'm not sure that we want to take such performance hit.```

[scheglov]

It is still slow to compute and not put into JSON.
So, I'm trying to optimize its computation.
https://codereview.chromium.org/1376473007

[scheglov]

Done.
Performance is still not perfect though.

#23694

[scheglov]

Err...
1af7b15

[scheglov]

It's very slow during switching tabs.
Rolling back...

[devoncarew]

Switching to @pq; Phil, let's meet about this - this is the last big item left.

[pq]

A bit of profiling has confirmed that caching doc comment contents with elements shouldn't add too much overhead. (Needless to say, this too will benefit from summaries.)

For example, this shows the number of elements, docs and char counts for a flutter app and the flutter lib. Adds up to ~500k.

[pq]

https://codereview.chromium.org/1534043002/

🤘

[pq]

Landed in 1f8eddc.