Linking to framework collection classes

Nov 20, 2013 at 2:41 AM
I am having real trouble writing a cref to a framework collection that doesn't generate a build warning in Sandcastle.

I have tried
<see cref="T:System.Collections.Generic.IEnumerable{T}"/>
<see cref="System.Collections.Generic.IEnumerable{T}"/>
<see cref="IEnumerable{T}"/>
<see cref="T:System.Collections.Generic.IEnumerable{My.Fully.Qualified.Type}"/>
Sandcastle always reports a warning similar to:
Warn: ResolveReferenceLinksComponent2: ... Unknown reference link target &#39;System.Collections.Generic.IEnumerable{T}&#39;.
Warn: ResolveReferenceLinksComponent2: ... Invalid reference link target &#39;System.Collections.Generic.IEnumerable{T}&#39;
Obviously because of the warning there is no link generated either, which is what I ideally want.
Coordinator
Nov 20, 2013 at 7:26 PM
The first fully qualified format with prefix is not correct since with the "T:" prefix it will write it out literally to the XML comments files and it expects it to be in the fully qualified and resolved format as generated by the compiler (T:System.Collections.Generic.IEnumerable`1 in this case). The fourth format will not work for similar reasons to the first. However, removing the "T:" prefix will also not work since you can't specify anything other than an identifier such as "{T}" for the generic type. Actual type names are not supported and will result in a compiler warning.

The second or third formats will work and result in a link to the IEnumerable<T> topic on MSDN. You only need to fully qualify the namespace if you haven't included a using statement for it.

If the second or third formats are resulting in unresolved warnings, it could be it failed to resolve it and saved the broken link to the cache file (a problem with earlier releases that has been fixed in the latest release). See if you have a folder called %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder\Cache on your system. If so, delete all of the cache files and folders in it. The next time you build your project it will recreate the cache files.

Eric
Nov 20, 2013 at 8:48 PM
Great thanks for the reply Eric. I did a lot of googling trying to find an explanation such as the one you just provided without much luck. I did read about the cache in one of your other posts yesterday and cleared it out once, but probably was still using the T prefix.

Out of curiosity, when - if ever - is it preferable to use the prefix to suggest the link type? All of my comment references across my entire code base have a T, M or P prefix. Should I not be doing this? I always tend to fully qualify my types as well, simply out of habit but it's good to know that is not needed.

Thanks again.
Coordinator
Nov 21, 2013 at 1:17 AM
It's best to just reference the type as you would in code without the prefix or namespace and let the compiler resolve it. That way, if you've got one that's not correct, the compiler will warn you about it. If using VB, there are a few cases where it won't resolve a few property references (can't remember the specifics offhand) and the workaround is to use the prefix and fully qualified name. Managed C++ doesn't handle forward references very well and the compiler typically fails to generate correct IDs so they too must be fully qualified and prefixed. For C#, there aren't any issues I'm aware of. If you want to link to an overloads page explicitly, you would need to use the "O:" prefix and the overloaded member's fully qualified name. If linking to specific overloaded methods, that isn't necessary and you include the parameter types to distinguish which one to link to. See the XML Comments Guide's see element entry for more info.

Eric