Tip - Documenting generics in .NET

If, like me, you're nuts about documenting all your classes, methods and properties so that NDoc or Sandcastle will generate nicely formatted API documentation for you, then you may have found that when it comes to documenting code that includes generics in its signature causes an error. This is because the angled brackets in the generics syntax gets confused with the angled brackets that are the nature of XML.

You can get around this by using the appropriate entity objects, but it's not particularly pretty to look at:

using System.Collections.Generic; public class MyProgram { /// <summary> /// Processes the contents of a <see cref="List&lt;T&gt;" />. /// </summary> /// <param name="parameters">The parameters.</param> public void MyMethod(List<int> parameters) { // Process the list } }

Fortunately, the .NET team thought this one through, and you can use curly brackets in the XML comments instead:

using System.Collections.Generic; public class MyProgram { /// <summary> /// Processes the contents of a <see cref="List{T}" />. /// </summary> /// <param name="parameters">The parameters.</param> public void MyMethod(List<int> parameters) { // Process the list } }

and they will be rendered as angled brackets when the documentation is created.

btw, if you're curious, the code samples were formatted using CarlosAg's Insert Colorized Code plug-in for the most excellent Windows Live Writer.