Roslyn: IDE diagnostics should have HelpLinkUri set

[sharwell]

Version Used: 15.7

Expected Behavior:

All IDE diagnostics should provide a HelpLinkUri linking to information about the diagnostic.

Actual Behavior:

Many diagnostics do not have the HelpLinkUri set at all. The test for this property has been skipped in #26718.

Diagnostics without this URI result in high CPU usage due to COM overhead in VisualStudioBaseDiagnosticListTable.GetHelpLinkToolTipText.

🔗 https://developercommunity.visualstudio.com/content/problem/738158/gro%C3%9Fe-anzahl-an-klassen-verlangsamt-intellisense-u.html

[NickCraver]

Please let's fix this! The current behavior is nearly useless. I don't think I'm exaggerating when I say it's better to not link anything than to generically link to Bing (which is what happens as the fallback today).

As an example I tweeted here, what a dev sees is:

And if they click, they get:

Note that there is a doc for IDE0007 (and many others), they're in the (well done!) .editorconfig doc here.

I get that linking to the above in a hard coded analyzer is a terrible idea. That's a non-starter IMO as it means the doc links and sections become immutable or links broken. Not awesome.

Can we work with the docs.microsoft.com team to create an indirection table somewhere of ID -> link? Or maybe there's a better place to do this? The advantages of this proposal are: we don't need to ship VS changes to ship doc fixes. If we linked to (as an example) https://docs.microsoft.com/vs/messages?id=IDE0007, the docs team would then be able to manage everything on their end (a 301/302 to an existing doc). And the community could likely help.

The above is assuming such indirection is possible with the docs.microsoft.com infrastructure (if it isn't, it'd be a good feature to add). Anyway, just an idea on how to make this more usable and maintainable at the same time. It'd hopefully require little more than 1 function of code changes on the Roslyn side (the Bing default method I linked above).

[jmarolf]

@NickCraver we can create aka.ms links on our side if the docs team doesn't have time to setup the redirects. This is just because we haven't set the URL for these diagnostics.

[NickCraver]

@jmarolf Yep agree that's an option, but it doesn't seem very maintainable (and the community can't help AFAIK). If we could maintain the redirects as one table in the docs repo on GitHub somehow...that seems more maintainable to me, I think.

I realize it's because the URL isn't setup, but I think my entire comment above addresses both that and why setting one to the existing docs also isn't practical (because it's so brittle).

[jongleur1983]

As I'm repeatingly annoyed by the automatic translations: Even if not this is a good issue, but it would be great if the language of the documentation page would be configurable, as the browser choosing to show the auto-translated stuff by default is usually annoying.
I know this is an issue with the documentation/msdn pages in general,
but if it's not fixed there it could be useful to keep in mind some language parameter even in some kind of a shortlink.

[tmat]

@NickCraver I suggest an alternative approach that expands on your proposal. Currently we use API for Bing service https://bingdev.cloudapp.net/BingUrl.svc/Get. It think it would be best if Bing team updated this service to first search in the docs (or some other well known source of analyzer diagnostics) and then did a generic web query.

[tmat]

Updating help links in diagnostics to use perma link is now tracked by https://github.com/dotnet/roslyn-analyzers/issues/2991.