Unknown reference link target when using IEnumerable`1

[shunter]

I'm seeing a case where the correct, fully qualified code entity reference is not found when building help, even though the reference exactly matches what's in the XML documentation file, and exactly matches what the SHFB Entity References tool provides.

The code entity reference that I put in my AML:

<codeEntityReference autoUpgrade="true">M:AGI.Foundation.Graphics.MarkerBatchPrimitive.Set(System.Collections.Generic.IEnumerable`1{AGI.Foundation.Coordinates.Cartesian},AGI.Foundation.Graphics.MarkerBatchPrimitiveOptionalParameters)</codeEntityReference>

Build error:

[...]packages\EWSoftware.SHFB.2016.9.17.0\tools\SandcastleHelpFileBuilder.targets(40,3): warning : BuildAssembler : warning : ResolveReferenceLinksComponent: [GraphicsMarkerBatchPrimitive] Unknown reference link target 'M:AGI.Foundation.Graphics.MarkerBatchPrimitive.Set(System.Collections.Generic.IEnumerable`1{AGI.Foundation.Coordinates.Cartesian},AGI.Foundation.Graphics.MarkerBatchPrimitiveOptionalParameters)'.

This is how the method appears in the relevant XML file:

<member name="M:AGI.Foundation.Graphics.MarkerBatchPrimitive.Set(System.Collections.Generic.IEnumerable`1{AGI.Foundation.Coordinates.Cartesian},AGI.Foundation.Graphics.MarkerBatchPrimitiveOptionalParameters)">

Which matches exactly. The reference documentation for the method in question is generated correctly, and linked correctly from other reference documentation pages (like the containing class member list, etc.)

This only seems to affect this particular method reference, which is pretty complicated.

While testing, I found that this seems to be specific to IEnumerable as a method parameter. We have many other method references that work correctly to find methods in the same XML doc file.

Curiously, if I change the codeEntityReference to take out the backtick indicating generic type, then the method is located correctly even though the reference now seems incorrect. Specifically:

<codeEntityReference autoUpgrade="true">M:AGI.Foundation.Graphics.MarkerBatchPrimitive.Set(System.Collections.Generic.IEnumerable{AGI.Foundation.Coordinates.Cartesian},AGI.Foundation.Graphics.MarkerBatchPrimitiveOptionalParameters)</codeEntityReference>

I can use this alternate reference as a workaround, but I thought I should report this inconsistency anyway.

Thanks for SHFB. We've been using it for many years successfully.

[EWSoftware]

Are you using managed C++ or VB? That's a common issue as those two compilers don't necessarily output an XML comments signature that matches the one in the assembly metadata. The Member ID Fix-Ups plug-in can be added to the project and configured to handle most of the common cases and has support for adding new expressions to correct those it doesn't know about.

[shunter]

You're right, this doc XML file was generated from C++/CLI. We do already have the Member ID Fix-Ups added, with the C++ fixes added. I had not examined those rules closely until now, but I now see that per those fix-ups,

IEnumerable`1{

is actually the wrong syntax, and

IEnumerable{

is actually the correct syntax.

I suppose the real issue here then is that the Entity References tool doesn't apply any fix-ups from the plugin, meaning that the snippets it generates can be wrong, but that might be difficult to change. Feel free to close this if you don't think that's fixable.

Thanks for the help.

[EWSoftware]

I'll take a look at it and see if I can apply the settings from the plug-in to the IDs if it's present in the project.

[VBWebprofi]

👍 Wait for such fix too.