XMLDoc new tag: docsPage

[bellons91]

When using XMLDocs to document a class or a method, it's currently possible to add one or more tags containing links, like see or seealso. Both elements produce a clickable link (if used with the href attribute), but that link can be used to point to any online page, with no specific meaning.

It would be useful to add a specific tag to link to the documentation page.

This way, tools like Visual Studio can open the right page when clicking F1: currently, this functionality is available only for classes and methods provided by Microsoft.

However, it would be nice to give VS the possibility to open the docs page using the same shortcut, regardless of where the documentation is hosted.

It can be useful both for open source libraries (to open public docs) and for internal libraries (to open the internal documentation page).

For example, something like

//<summary>
//</summary>
///<docsPage href="https://nsubstitute.github.io/help/received-calls/" />
Substitute.For<T>();

[colejohnson66]

That can be done with <seealso href="abc" />. Or did you have something else in mind?

[bellons91]

Yes. AFAIK, you can add more than one seealso tag, so a hypothetical shortcut like F1 in Visual Studio would not recognize that this is the link to open to read the documentation.

Also, that tag could actually be everything (from the project page to the author's Instagram profile). I'd like to have something that, at least semantically, says, "Hey, use this tag ONLY for the documentation). Of course, there is no guarantee that it will be used correctly.

[koszeggy]

For cases when the online documentation may provide more information than the displayed tooltip in VS (e.g. Examples section, images in the documentation, or just many chapters that would be too much on a tooltip) I've just started to use the following workaround recently:

• Place a hidden link in the summary:

/// <summary>
/// My visible summary.
/// <div style="display: none;"><br/>See the <a href="https://myhelp.com/myclass.html">online help</a> for examples.</div>
/// </summary>
/// <remarks>Visible both in the tooltip and in the compiled docs</remarks>
/// <example>Visible in the compiled docs only</example>

• It will be displayed in the tooltip from VS:
  

• But it remains hidden in the actual compiled documentation where you can find the additional content.

Btw. I would also love to make F1 work for my libraries somehow (without any VS/registry hack). But up to now this is the best solution I could come up with.