Roslyn: Intellisense Return Value Documentation

[vsfeedback]

I can't believe this still hasn't been done in VS...can someone PLEASE make it possible to display the <return> xml doc content in Intellisense? The return value documentation is usually only a single line and it is extremely important to properly using methods and properties. I really don't understand why it's expected that I go to the online docs everytime I want to figure out what a method is returning.

_This issue has been moved from https://developercommunity.visualstudio.com/content/idea/402037/intellisense-return-value-documentation.html
VSTS ticketId: 743723_
_These are the original issue comments:_
(no comments)

[sharwell]

We discussed this in a design review today. The team agrees that Quick Info might benefit from more comprehensive documentation, but wants to see a more complete proposal addressing at least the following:

• <remarks> (implemented for 16.6 Preview 2 in #42135)
• <examples>
• <exception> (#1515)
• <returns> and <value> (implemented for 16.6 Preview 2 in #42128)

The proposal would then be implemented together so the feature ships to users in a coherent manner. I'm assigned to creating the proposal, which will then be taken to a future design meeting for approval.

[mikernet]

From that list I really think that <return> is the only critical one. I want to use intellicode but without the return value intellisense is just too tedious to use. All the others might be "nice to haves" as long as they don't clutter things but return value doc is absolutely 100% critical, I just don't understand how anyone gets by without it.

I really think <remarks> / <examples> is better left to F1-ing if you need that extended info and the current method of obtaining those docs is sufficient. I'm not sure how you would incorporate that into quick info, it's usually rather long. That said, the default F1 behavior should be to open a tab in visual studio with the docs, not an external browser. Having an option so people can use their browser if they prefer might be a good idea though, some people like docs opening in their browser that is opened on another monitor.

What the heck is <value>?

[sharwell]

better left to F1-ing if you need that extended info and the current method of obtaining those docs is sufficient

There is no F1 experience at all for documentation for third-party libraries (e.g. ones provided through NuGet). Either way, hopefully this issue gets the ball rolling on some of these items I've been thinking about for a while now. 😄

What the heck is <value>?

<value> is used instead of <returns> when documenting a property or field.

[mikernet]

Ah, you're right...well continuing with my suggestion that F1 should open a VS tab instead, that could be used to extract the full docs and show them there.

As for value...ah I forgot about that little sucker, we just put that info in summary for fields and properties, it's always mostly just repeated anyway and it actually shows up in intellisense ;)

[gerardo-lijs]

I agree with the comments of @sharwell and @mikernet. This is how I imagine it could work for your own code and also for NuGet/any library.

1) <returns> or <value> would be great to show directly like in the pic in this link
2) F1 or a Hyperlink to click in the popup would be great to get the or direct access to docs. Maybe this could be done with a in the method of the referenced NuGet/dll so VS can get that with Reflection and open it either inside VS or in browser. Ideally if a method does not have an specific it would be great to "bubble" up to the Class .
3) For configuration classes I sometime find myself documenting a Default value in the

so that when I hover the mouse over the property I can see the default since

/// <summary>
/// Sample options.
/// Default value = 2
/// </summary>
public int Option {get; set:} = 2;`

Maybe there is a better way for this cases if you are able to modify VS.

[Barina]

We discussed this in a design review today. The team agrees that Quick Info might benefit from more comprehensive documentation, but wants to see a more complete proposal addressing at least the following:

• <remarks>
• <examples>
• <exception> (#1515)
• <returns> and <value>

The proposal would then be implemented together so the feature ships to users in a coherent manner. I'm assigned to creating the proposal, which will then be taken to a future design meeting for approval.

I would suggest to implement all of these and let the user decide (in settings) what to show in the quick view.

[BertdeJong]

How about this:
Keep the tool tip like it is, except add the word "More" in the bottom left corner of the tool tip. When the user hovers its mouse over this "More" word, the tool tip expands and reveals all the other information.
This way the tool tip remains lean, but all additional information is easily accessible.

[AroglDarthu]

I would prefer the tool tip/quick view to be configurable like @Barina proposed. A good default would be to have the summary mandatory and returns enabled.

Perhaps also make the tool tip clickable, in order to have it show all the available documentation in case not all options have been enabled.

[jinujoseph]

also requested here

[bert2]

Can't we have a first iteration that only adds the content of <returns>, then a second one that deals with the rest, and then a third one that makes it configurable/interactive etc. etc.?

This issue always bugs me when I'm writing documentation for public libraries, because I'm forced to squeeze all the critical stuff into the <summary>.

[Mhburg]

To echo the OP, I can't believe after more than a year, there has been exactly zero release on this front.

[sharwell]

@Mhburg See the update to https://github.com/dotnet/roslyn/issues/31618#issuecomment-446203381. Support for <value>, <returns>, and <remarks> was added for 16.6 Preview 2.

[mikernet]

@sharwell Is it in preview 1 or preview 2? Your edited comment below the OP indicates it's in preview 1 but your reply above says preview 2.

[sharwell]

@mikernet It's in Preview 2.

[prejedj]

So this is still an issue? Really? Even MS documentation shows users how to use the returns tag without specifying you need a tool like resharper just to see it....
https://docs.microsoft.com/en-us/visualstudio/ide/reference/generate-xml-documentation-comments?view=vs-2019

[jnm2]

@prejedj The returns and remarks tags show in IntelliSense in non-preview VS as of the 16.6.0 release on May 19.

[prejedj]

Wow @jnm2 Perfect timing! Just updated my VS and sure enough, returns is there. Thanks 👍

[prejedj]

Now what do we do about the other tags? such as <example>?

[jnm2]

I think you might need to type \\ to escape the tag or use backticks.

[prejedj]

Ha, sure enough! sorry. should have previewed first. I am referring to the \ tag

[sharwell]

I don't think Quick Info is the right UI for examples, but as an author of some long examples I agree it would be nice if users could see them.

[jnm2]

Maybe have a link to expand quick info or open a popup?

[mikernet]

I think it should just open a tab with the full documentation and render it MSDN style

[jnm2]

So an Open in Object Browser to see example link?