8

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;}
}
galford13x
  • 2,483
  • 4
  • 30
  • 39
  • Dunno about sandcastle but monodoc and doxygen give me examples from this. – IanNorton Sep 04 '12 at 21:02
  • Your example should work properly according to MSDN. – BlueM Sep 04 '12 at 21:31
  • 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 Sep 04 '12 at 21:48
  • 1
    Hint. Look up the `<![CDATA[ .. ]]>` tag http://www.w3schools.com/xml/xml_cdata.asp and http://stackoverflow.com/questions/2784183/what-does-cdata-in-xml-mean – John Alexiou Sep 04 '12 at 22:54

2 Answers2

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

ideafountain
  • 575
  • 5
  • 17
0

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

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.

galford13x
  • 2,483
  • 4
  • 30
  • 39
  • 2
    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 block, these characters need to be represented as entities so that the XML can be parsed correctly. (Also every must be closed with a corresponding etc). If you have problems with chunks of a comment going missing in intellisense or sandacastle, check for xml syntax errors. – Jason Williams Sep 04 '12 at 22:03
  • @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 then it would work in the tag but I suppose that would limit the use of brackets as well. – galford13x Sep 04 '12 at 22:24