Windows Phone 8 project misses methods with pointer params

Topics: User Forum
Sep 30, 2013 at 9:59 PM

I am using Sandcastle to document a Windows Runtime Component for Windows Phone 8. For the most part, it works great (the only tricky part was getting the assembly references right, which I got from help from someone else's post here).

One small problem I found: any methods I have that take pointer parameters do not seem to be documented, and cause Sandcastle to warn that there is missing documentation. For example:
void GetLoop(int* startFrame, int* endFrame);
causes this warning:

Warn: ShowMissingComponent: [M:CricketTechnology.Audio.Sound.GetLoop(System.Int32@,System.Int32@)] Missing <summary> documentation

and the summary for that method is not included in the class documentation.

Anyone know of any workarounds for this?

Oct 1, 2013 at 7:51 PM
The first thing to check is that the XML comments file referenced in the build log is up to date and does actually contain the member comments it says are missing. It could be a simple matter of rebuilding the project to get it up to date with any new member comments.

Judging from the method signature I'm assuming this is a C++ project. If so, the C++ compiler has a tendency to generate XML comment member IDs that differ from the ones generated from the assembly metadata by Sandcastle. If you compare the member ID in the build log warning to the member ID in the XML comments file and they are different, that's what is happening.

In some cases, enabling the "Fix up method signature issues" option in the Build category of project properties can allow SHFB to fix the IDs so that they match. Those typically relate to method signatures with generics though and there are several cases where that doesn't help. My plan is to create a plug-in that will let you map the invalid IDs to the good ones so that they can be fixed up even when they don't match the well-known patterns fixed by the project option. If I can, I'll try to get it into the next release.

Oct 2, 2013 at 5:47 AM
Thanks Eric!

The method does appear to be in the XML file:
<member name="M:CkSound.getLoop(System.Int32*!System.Runtime.CompilerServices.IsImplicitlyDereferenced,System.Int32*!System.Runtime.CompilerServices.IsImplicitlyDereferenced)">
Get the loop start and end.
I can see that the method signatures are different, but I'm not sure what the difference is between "System.Int32@" and "System.Int32*!System.Runtime.CompilerServices.IsImplicitlyDereferenced" is. Enabling the "fix up method signature issues" option didn't seem to help, though.
Oct 3, 2013 at 2:35 PM
If you run ILDASM on the .winmd file, what does it show as the signature of getLoop?
Oct 3, 2013 at 4:30 PM
.method public hidebysig newslot virtual final 
        instance void  GetLoop([out] int32& startFrame,
                               [out] int32& endFrame) runtime managed
  .override CricketTechnology.Audio.__ISoundPublicNonVirtuals::GetLoop
} // end of method Sound::GetLoop