codeEntityReference to method on a Sandcastle developerHowToDocument

Question

I'm trying to create a link to a custom extension method using <codeEntityReference> MAML element and once I build the documentation I'm getting the whole <codeEntityReference> tag content instead of a link to the whole method.

A sample of the method would be:

namespace SampleProject 
{
    public static class ExtensionMethods
    {
         public static bool SomeExtension<T>(this T some) => true;
    }
}

And the <codeEntityReference> would look as <codeEntityReference>M:SampleProject.ExtensionMethods.SomeExtension{T}(TObject)</codeEntityReference>

Above link will produce an output like M:SampleProject.ExtensionMethods.SomeExtension{T}(T).

Actually, I'm getting the following error during documentation build:

warning : BuildAssembler : warning : ResolveReferenceLinksComponent: [52e40f26-3dfe-47e0-adf1-09233e98f42e] Unknown reference link target 'M:SampleProject.ExtensionMethods.SomeExtension{T}(T)'

Am I missing something? What's wrong there? I've tried to provide the method reference as:

M:SampleProject.ExtensionMethods.SomeExtension`1

...but it didn't solve the issue.

Answer 1

Finally I solved the issue checking how C# compiler generates the XML documentation file for the assembly.

For example, a <codeEntityReference> to my sample extension method would be:

<codeEntityReference>
     M:SampleProject.ExtensionMethods.SomeExtension``1(``0)
</codeEntityReference>

Answer 2

A better approach would be to use the Entity References tool! You can find it under the View->Other Windows menu in visual studio.

Once you have it open, select "Code Entities" in the Type combobox and search for the method/property/class you want the code reference for. It will display what you need for your code Entity Reference to work.