XML Comment on ‘X’ Has CRef Attribute That Could Not Be Resolved


Overview

Here’s a scenario that a lot of us developers have probably faced or are still facing. You’re developing an application and you want to provide really good documentation. So, you dutifully XML document every single method, property, etc. in the project. However, you notice that when you build the project there are a number of Warnings similar to the following.

XML comment on ‘Namespace.Method()’ has cref attribute ‘System.Collections.Generic.List’ that could not be resolved.

XML comment on ‘Namespace.Method()’ has cref attribute ‘System.Collections.Generic.Dictionary’ that could not be resolved.

After double-checking the correct location of List as well as your spelling, you’re probably left scratching your head or “Googling” and reading articles. Well here’s the answer.

The Answer

The generic collections in the System.Collections.Generic namespace get the “generic” moniker from their ability to mold themselves to fit the type you’re working with. Within the definition of the generic collections this generic type is generally specified with a “<T>”. Well, the XML comment system also needs a type specifier to match up with the generic object’s definition. In XML comments we can’t use the less-than (<) or greater-than (>) characters in text so we instead use curly braces ({ and }). Below are some examples of how you specify this in the XML comments.

List

/// <summary>
/// Returns things for a given Id.
/// </summary>
/// <param name="Id">A <see cref="System.Int32"/> containing the 
/// identifier to return all of the things for.</param>
/// <returns>A <see cref="System.Collections.Generic.List{T}"/> 
/// containing all of the things.
public List<string> GetThings(int Id) { }

Dictionary

/// <summary>
/// Returns key and things for a given Id.
/// </summary>
/// <param name="Id">A <see cref="System.Int32"/> containing the 
/// identifier to return all of the things for.</param>
/// <returns>A <see cref="System.Collections.Generic.Dictionary{K,V}"/> 
/// containing all of the keys and things.
public Dictionary<int, string> GetThings(int Id) { }

 

In the List example, notice that in the <returns> section of the XML it shows a reference to the “System.Collections.Generic.List{T}” type. If you update all of the XML references that are throwing the error described above to have “{T}” at the end, the XML comment system will recognize it and resolve the error. If you have a Dictionary or other generic type, simply include the generic type characters appropriate to that definition. For instance the Dictionary object has a key and value so I simply put “{K,V}” after its definition.

Summary

I hope this helps you resolve those pesky little warnings you get when doing XML comments! If you liked this article, please feel free to check out my other posts. As always, please comment and share. I enjoy hearing from my readers!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s