Background and motivation

When using the option to generate Xml documentation files e.g. from C#, the compiler will write an Xml file with the documentation comments for all types and members in the project.

These types and members are identified with an ID in a fixed format. To do anything programmatically with that file (other than using a ready-made tool, that is), your own code needs to compute the same IDs for any given Type or MemberInfo.

While all the information required for those IDs can be retrieved via reflection, the ID can be non-trivial to compute, e.g. in cases like this:

M:Test.Namespace1.Class3`1.Class4.Method10(Test.Namespace1.Class3{`0}.Class5{`0})

Note that this format is not the same as calling e.g. FullName on a Type, especially when it comes to the treatment of generic parameters, but also in other aspects such as nested types, ref parameters, etc.

Therefore, a way to have the BCL compute this ID would be appreciated, either directly on Type and MemberInfo, or in a helper class specifically for supporting documentation.

API Proposal

public class Type
{
    public string DocumentationId { get { ... } }
}

public class MemberInfo
{
    public string DocumentationId { get { ... } }
}

or

public static class DocumentationIdProvider
{
    public static string GetDocumentationId(Type typeInfo) { ... }

    public static string GetDocumentationId(MemberInfo memberInfo) { ... }
}

API Usage

var myType = typeof(...);
var myMethod = myType.GetMethod("DoSomething");

var methodDocId = myMethod.DocumentationId;

var methodDoc = docXml.SelectSingleNode($"/doc/members/member[@name = '{methodDocId}']");
// Here, we can use of the documentation comments for the method, if any.

Alternative Designs

See above: Either add the information directly on Type and MemberInfo, or provide a separate helper class (possibly from a documentation-specific assembly).

Risks

None. The code is already there; the C# compiler uses it when generating the Xml files. I am just asking for it to be made accessible via the BCL API.