views:

312

answers:

1

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.

+1  A: 

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?

ShuggyCoUk
Ah, good find. It's strange that it's supposably been fixed however. I'm using the latest (May 2008) version of Sandcastle with the patch from http://sandcastlestyles.codeplex.com/.
Noldorin
It does indeed seem like the compiler adds the prefix automatically (as well as fully qualifying the reference name). I did a bit more testing and the problem seemed to be that if you include the prefix, you must also fully qualify the type namne or the reference won't make any sense. In conclusion, it seems that I can avoid using prefixes in code in all cases. (Correct me if I'm wrong.) Anyway, thanks for answer!
Noldorin
I would think the only time you would need to use the specific, annotated form is when there is a name collision (something really nasty like: class Bar : ICloneable { public object Clone; object ICloneable.Clone() {} }I wouldn't think you would need to use this often if ever.
ShuggyCoUk