XML Comments - Should see references be fully qualified?

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.

Answer 2

I can't speak for Sandcastle, but based on my experience with other tools e.g. ReSharper, it seems that a type needs to be qualified if a) it isn't in scope or b) it is shadowed by another type that is more-locally defined.

In other words, if you are using System.Collections.Generic, then you won't have to qualify ICollection{T}. If you happen to define your own ICollection{T} interface in the same file, however, you will have to qualify the former (as well as the latter, come to think of it).