Question

Basically, when is it truly necessary (if at all) to use a fully qualified xml see reference:

<see cref="T:MyNamespace.Sub.MyType"/> //Option 1
<see cref="T:MyType"> //Option 2

Also, what about referencing to the .NET Framework objects?

<see cref="T:System.Collections.Generic.ICollection{T}"/> //Option 1
<see cref="T:ICollection{T}"/> //Option 2

I understand that fully qualifying items will always allow Microsoft’s Sandcastle to link things properly, but is it necessary for everything to be fully qualified?

---

Sidenote: Will Microsoft Sandcastle be able to link to the .NET Framework help files or am I wasting my time by referencing <see cref="T:System.Collections.Generic.ICollection{T}"/>?

Answer 1

Both Joseph and Ben touch on useful points but I think my recent Sandcastle experience may be helpful:

1. When you compile your project Visual Studio will usually tell you immediately whether your reference is valid by issuing a warning if it cannot resolve a reference in your doc-comments, whether this is a reference to your own types or to system types (and VS does honor your “using” statements).

2. In the scenario of having a local type masking a system type, there are two cases to consider: your signature uniquely qualifies your type (covered by (1) above), or your signature exactly duplicates a system type. The latter case requires explicit disambiguation by fully qualifying the name.

3. You touched upon the use of explicitly specifying the member type prefix (e.g. “T:SuperWidget”), but this is more significant than most people realize: if you use a member type prefix then fully qualified names are required. This is actually documented on MSDN but in the very fine print–see Processing the XML File. And to make matters worse, if you omit the fully qualified name you get no warning at build time(!); simply no link is generated in the final Sandcastle rendering. There are other issues if you explicitly specify a member type prefix–see the Disambiguating and Resolving References section of my article on practical Sandcastle tips, Taming Sandcastle: A .NET Programmer’s Guide to Documenting Your Code.