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;}
}

Dunno about sandcastle but monodoc and doxygen give me examples from this. — IanNorton
– IanNorton, Commented Sep 4, 2012 at 21:02
indeed it does, as usual I should have given a more representative example or the actual code. Unfortunately the system I code on cannot be connected to outside networks and therefore requires me to write from scratch any questions. — galford13x
– galford13x, Commented Sep 4, 2012 at 21:48
Hint. Look up the <![CDATA[ .. ]]> tag w3schools.com/xml/xml_cdata.asp and stackoverflow.com/questions/2784183/what-does-cdata-in-xml-mean — John Alexiou
– John Alexiou, Commented Sep 4, 2012 at 22:54

ideafountain · Accepted Answer · 2012-09-12 17:10:20Z

1

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

answered Sep 12, 2012 at 17:10

ideafountain

5755 silver badges17 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

galford13x Over a year ago

This is very interesting, I didn't realize Sandcastle had that feature. Thanks for the tip!

galford13x · Accepted Answer · 2012-09-04 21:49:17Z

0

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.

edited Sep 4, 2012 at 21:49

answered Sep 4, 2012 at 21:46

galford13x

2,5614 gold badges32 silver badges39 bronze badges

2 Comments

Jason Williams Over a year ago

To clarify: An Xml Documentation comment is an XML fragment that is embedded in a code comment. It must be valid XML - so as you have found, an < anywhere within the text of doc entries needs to be represented as an XML entity, < (and similarly for other characters like >, &, etc). Even within the <code> block, these characters need to be represented as entities so that the XML can be parsed correctly. (Also every <tag> must be closed with a corresponding </tag> etc). If you have problems with chunks of a comment going missing in intellisense or sandacastle, check for xml syntax errors.

galford13x Over a year ago

@Jason: That does make sense. how would the parser know when the code segment has finished if it ignored xml tags. There would need to be some sort of escape sequence which is what the < provides. I guess I figured if the {T} worked in the special case tags like <see cref="" /> then it would work in the <code> tag but I suppose that would limit the use of brackets as well.

Collectives™ on Stack Overflow

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

2 Answers 2

1 Comment

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related