XML Comment Documentation out of date

[aremes]

Type of issue

Outdated article

Description

Under the <summary> tag, it says

The text for the <summary> tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser window.

This does not appear to be true anymore. VS2022 (17.8.3) will happily display all the remarks, examples, etc. too.

Page URL

https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags

Content source URL

https://github.com/dotnet/docs/blob/main/docs/csharp/language-reference/xmldoc/recommended-tags.md

Document Version Independent Id

d135d0a6-53d2-1567-0b1b-7aae5e07739f

Article author

@BillWagner

Metadata

• ID: 3bcb925f-ef72-9a64-3762-c0b4a96f9dc4
• Product: dotnet-csharp
• Technology: csharp-language-reference

[BillWagner]

ping @CyrusNajmabadi

I think this is still correct for intellisense,

[CyrusNajmabadi]

We do show more information now. However, i'm not sure if doc'ing this is relevant given that we may change it at any point in time. Basically, API authors should doc their code as well as possible, and the IDE will try to give users way to see that info. At the very elast, we can take the user to the code, so they can see all the info.

[gewarren]

For the "remarks and examples" that Visual Studio shows, are you referring to the GitHub examples/docs? (If so, those aren't coming from the API XML comments AFAIK.)

[aremes]

@gewarren no, i dont mean that

@CyrusNajmabadi i understand your reasoning about the behavior changing in the future. Rather than trying to add/correct information about what shows up in intellisense, I would suggest completely removing that information alltogether. Currently it's just plain wrong because the summary tag is not the only thing that shows up in intellisense.

And I'm a strong believer that the only documentation worse than no documentation is wrong documentation..

I know and understand that this is not a priority (when is documentation ever treated as a priority ;)) I'd still appreciate the team considering the change. If not, confused users like me will hopefully at least stumble upon this issue and learn that its not them doing or understanding something wrong :)