Adding code snippets

Topics: User Forum
Mar 24, 2008 at 4:04 PM
Hi, I have been using Sandcastle for a couple of months and am pleased with it. I now need to regenerate the API documentation, with relevant "code snippets" provided as an example to the person using the API, and was wondering what would be the best way to do this? Thanks in advance!
Mar 24, 2008 at 7:17 PM
The <code> tag is used to format code snippets in the API documentation. One or more <code> tags are enclosed within an <example> tag. You can place text between the code samples. For example:

This does something interesting
/// Code goes here
Another example that does something else
<code lang="vbnet">
''' This one is a VB.NET example

When using SHFB, it includes a Code Block Component that colorizes the code. If the lang attribute is omitted from the <code> tag, it will assume C#. If you want to use VB.NET as the default or you only ever include VB.NET examples, you can use the ComponentConfigurations project property to add a reference to the Code Block Component and override its default so that it uses VB.NET by default instead.

There are several other attributes that allow you to do such things as add a title, enable outlining and line numbering, and to import code from actual source code files so that you can build the code to make sure its valid and you don't have to maintain it there and in the XML comments. See the Code Block Component topic under the Custom Build Components section in the help file for full details.

Mar 24, 2008 at 7:38 PM
Maintaining code documentation using inline XML code comments is a pain due to the need to entity encode the snippets for the XML syntax, and the readability of the code suffers if you are providing large snippets. The added benefit of importing/linking to an external code file is that you get compile time checking of the examples you are providing, assuming the referenced examples exist in a project that is compiled along with your application. You can also use the region attribute to only import sample code from a particular region in the code file being imported. I have used this methodology to generate documentation for my CodePlex project with great success.

/// <example>
///     <code lang="cs" title="The following code example demonstrates the usage of my class/interface/enum/etc.">
///         <code 
///             source="..\..\Documentation\CodeExamplesLibrary\MyClassExample.cs" 
///             region="Some Region" 
///         />
///     </code>
/// </example>

An excellent guide on XML documentation comments can be found at for those unfamiliar with XML Documentation Comments. This guide is particularly useful as it shows what commenting features Sandcastle supports.
Mar 24, 2008 at 11:31 PM
The example can be simplified as the source and region attributes can be placed on the parent <code> tag. You only need nested <code> tags if you are merging multiple snippets into one code block.

Apr 1, 2008 at 4:28 PM
Is it possible to retrieve and publish code samples stored in .txt files? I have some 50+ code samples in a Word document, that need to be added to specific pages in the API Reference.
Apr 1, 2008 at 6:21 PM
As long as they are plain text, it will work. The filename doesn't matter. It can't read Word documents so you'd have to save them as plain text first. If you save them all in one file, you can wrap the code in #region/#endregion tags to delimit them and then reference them as noted in the messages above.

Apr 2, 2008 at 12:07 PM
Ok, that's great! Thanks Eric!
Apr 11, 2008 at 6:02 PM
Edited Apr 15, 2008 at 4:08 PM
I ended up using a pretty "obvious" way to include code samples. Put all the code samples into one xml file, with the necessary tags required just to define code samples:

<member name="">
Add the file to the project as a comments-only xml file and build the API Ref.
This works very well for me!
I know it may seem like quite an obvious method...