[New Tool] add <summary> links (xml -> docfx)

[ZacharyPatten]

The BCL has a feature that when you press F1 in Visual Studio on a code member, it will take you to MS Docs for that member. We currently don't have a feature like that for custom libraries. But we could...

I wish there was a tool that would update the XML docs of every member in a code base to link to the code member in DocFx.

For example, if I have the following:

namespace Towel
{
	/// <summary>
	/// A type that has clonable instances.
	/// </summary>
	/// <typeparam name="T">The type of instances that can be cloned.</typeparam>
	public interface ICloneable<T>
	{
		/// <summary>
		/// Clones a <typeparamref name="T"/>.
		/// </summary>
		/// <returns>A clone of the <typeparamref name="T"/>.</returns>
		public T Clone();
	}
}

And I happen to be using docfx: https://zacharypatten.github.io/Towel/api/Towel.ICloneable-1.html#Towel_ICloneable_1_Clone

A link could be added in the <summary> of each code member in the source code to the member in the DocFx output:

namespace Towel
{
	/// <summary>
	/// A type that has clonable instances.
	/// <br/><br/><a href="https://zacharypatten.github.io/Towel/api/Towel.ICloneable-1.html">https://zacharypatten.github.io/Towel/api/Towel.ICloneable-1.html</a>
	/// </summary>
	/// <typeparam name="T">The type of instances that can be cloned.</typeparam>
	public interface ICloneable<T>
	{
		/// <summary>
		/// Clones a <typeparamref name="T"/>.
		/// <br/><br/><a href="https://zacharypatten.github.io/Towel/api/Towel.ICloneable-1.html#Towel_ICloneable_1_Clone">https://zacharypatten.github.io/Towel/api/Towel.ICloneable-1.html#Towel_ICloneable_1_Clone</a>
		/// </summary>
		/// <returns>A clone of the <typeparamref name="T"/>.</returns>
		public T Clone();
	}
}

Here is what it looks like from the Visual Studio UI:

This is also be supported in Visual Studio Code:

This would be especially helpful to guide people use nuget packages to the documentation for the nuget package.

The problem is that adding all those links manually to every code member is extremely tedious... We need a tool!

If we just make a tool that would automatically add all these links for us, it would speed up the process and prevent user error, as well as automatically update when code members are renamed/moved. Like, if there was a docfx --addOrUpdateSummaryLinks true --urlBase https://zacharypatten.github.io/Towel/api/ command, it would be amazing. :)

[ZacharyPatten]

Note: one of the major drawbacks/issues of this is <inheritdoc/>. You would never be able to use <inheritdoc/> to inherit the <summary> of other members if there is an explicit <summary> on every member.... So there are a lot of nuances that would need to be considered.

I wish there was a better place to put the link than in the <summary>, but I can't really think of a better place, and we are limited to only the xml nodes that are part of the C# spec if we want IDE support... which is pretty much the entire goal of this discussion.

[KalleOlaviNiemitalo]

Could make an MSBuild task that reads the xrefmap generated by DocFX and edits the xml file generated by the C# compiler, before it is packed for NuGet.

[ZacharyPatten]

I like that idea. :)

[sharwell]

I'm not a fan of this at all. The entire proposal is a workaround for a completely broken feature (F1 should work, but doesn't), and clutters up Quick Info with links that should already work.

[ZacharyPatten]

I agree that this approach isn't ideal, but a few comments...

I don't believe Visual Studio Code supports F1, but I could be wrong. So even if F1 was fixed, it would not prorogate to other IDEs. Also, consider non-IDE topics like code navigation in GitHub. GitHub supports code navigation for C#. Currently there is no support for Quick-Info/XML docs in GitHub (only navigation/references), but if that were ever added in the future, that would be really nice and this this feature would be supported.

[ZacharyPatten]

An example screenshot of GitHub's C# code navigation:

As mentioned... XML/Quick-Info currently isn't integrated on GitHub, but it could be... ;) ;)

[KalleOlaviNiemitalo]

F1 in Visual Studio 2017 opens the Web browser at an URL like https://msdn.microsoft.com/query/dev15.query?appId=Dev15IDEF1&l=EN-US&k=k(System.IO.Path.Combine);k(SolutionItemsProject);k(DevLang-csharp)&rd=true. If Microsoft wanted to expand this to third-party libraries, I imagine they could make Visual Studio look for an alternative URI template in the XML documentation file or in the nuspec file. The library vendor would then have to set up an Web app that redirects to the documentation.

<?xml version="1.0" encoding="utf-8"?>
<doc>
  <assembly>
    <name>Example.Toolkit</name>
  </assembly>

  <!-- RFC 6570 URI Template -->
  <onlinedoc>https://docs.toolkit.example.com/redir?version=toolkit-42{&amp;uid,targetframework}</onlinedoc>

  <members>

Privacy could be a problem with this, as the developer or their employer might not want to disclose to the library vendor, all the same information that Visual Studio now reveals to Microsoft. Clicking a hyperlink in Visual Studio partially mitigates this problem because the developer can see the whole hyperlink beforehand. Some kind of employer override (Group Policy?) might still be needed, though.

DocFX supports Cross reference services like https://xref.docs.microsoft.com/query?uid={uid} but the HTTP response from this contains a lot of information that is not relevant to the F1 scenario. I don't think it should be a goal to make the same Web app usable for both DocFX and F1.

[sharwell]

Every example here for why this should be added is another example of how third-party libraries are penalized for not having been developed at Microsoft and/or published on docs.microsoft.com. It shouldn't be necessary to update the source code to have a textual link to a documentation site, regardless of the manner in which the source is viewed. All of the cases above should be updated to work with the documentation site without relying on the source code to contain the link.