C# Documentation <example><code>…</code></example> for a class

Question

I have a class that I would like to create a simple example on how to use. However, when I use the tag on the class declaration, the example does not appear in the Sandcastle output. It works fine for the object's members but not for the class itself. Can sandcastle handle this?

An example of what I would like to do would be.

MSDN TcpClient Documentation

This has an example on how the class would be used. How can I include such a thing for my class?

This is would I would like to do:

/// <summary> My example class </summary>
/// <example>
///   <code>
///      // Example code on how to use the class
///   </code>
/// </example>
public class MyClass
{
    public string MyString {get;set;}
}

Answer 1

Due to the example containing generics, the documentation was not parsed correctly and I had to replace all < with < and > with >.

I had tested documentation with by putting this is a test in the documentation example and it worked fine, but for some reason it wasn't working correctly with my real code. after replacing the tags with the appropriate escape sequences, everything worked correctly.

Also note, that the claimed {T} did not work correctly either as it was printed verbatim rather than translated to a generic statement. Although I would expect this in a <code></code> statement, I would also expect a List<string> declaration to work properly also.

Answer 2

For Sandcastle, Custom tags can be created by modifying the main_sandcastle.xslt file with your own tag transform definitions. Files you would be interested in are :

transforms/main_sandcastle.xslt content/shared_content.xml