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).

Answer 3

You are not wasting your time in <see cref />-ing the Framework, in my opinion. The Visual Studio help provider should be able to intercept and interpret at runtime when the call is made for that help topic. I haven't used it recently, but it had worked quite nicely in the past.

As to fully qualifying, it is not needed in most scenarios, but depends on your usings, as Ben has mentioned. As long as what you are referencing is in scope (and either should be, as you are likely to be using it if you are referencing it, or you should add the using so that your code isn't using the fully qualified form), just the type should suffice.