Reference Prefixes in .NET XML Documentation

Question

I've been attempting to fully document all types, methods, properties, etc. of a class library using XML comments but have run into a curious effect involving the cref attribute (used by see tags for example). Going by the advice of this MSDN page as well as following various other examples on MSDN and other websites, it seems that whenever one specifies a reference value using the cref tag, it must be prefixed with a certain marker that classifies the refence (such as 'T:' for type and 'M:' for method).

Using Microsoft Sandcastle, however, I've observed that by missing out these prefixes there is an effect in the generated documentation (CHM help file in this case). Including prefixes (in all situations I belive), the reference is rendered on the page as bold text... Yet discluding the prefix the reference is rendered as an anchor (link) to the appropiate page within the API reference. It seems rather strange to me that the recommended method of prefixing (all?) references is giving the least useful result - why should the reference be rendered as bold in one case and linked in another? I would appreciate if someone could shed some light on this.

Answer 1

This appears to have been a bug in sandcastle

What version of sandcastle are you using?

That said recent discussions seem to indicate that, at least for System types, the suggested method is to actually avoid using the qualified names since the examples posited in that answer dropped the T: and M: entirely Your confusion is therefore not unexpected or uncommon.

This documentation strongly implies that the compiler, where it can spot what type/method/constant you're pointing to inserts the prefixes for you. Have you verified this in the xml?