Supporting Custom tags in Sandcastle
Sandcastle supports C# (and VB) xml tags for developer documentation comments. The list of c# tags are available at http://msdn2.microsoft.com/en-us/library/5ast78ax.aspx. We added the following new custom nDoc tags in November CTP (http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en):
1. <overloads>
2. <preliminary>
3. <threadsafety>
4. <note>
These custom tags are supported in nDoc and you can see the tags under tag reference section at http://ndoc.sourceforge.net/usersguide.html.
This blog provides details on how to define your custom tags. To support custom tags the user can modify the presentation transforms (XSLT) that are shipped with Sandcastle. The following steps provides details:
1) Add the custom tag to the code in C# file [test.cs]:
/// <customTag>This is a custom tag.</customTag>
public class StoredNumber
{
}
2) Compile the C# file and extract the /// comments to, say comments.xml.
csc /t:library /doc:comments.xml test.cs
The custom tag will be included in the XML.
3) Update main_sandcastle.xsl with the following:
<xsl:template name="body">
<!--Add this depending on where we want our custom tag to be displayed-->
<xsl:apply-templates select="/document/comments/customTag" />
</xsl:template>
<xsl:template match="customTag">
<!--Customstyle can be defined in Presentaion.css stylesheet-->
<div class="CustomStyle">
<xsl:apply-templates />
</div>
</xsl:template>
The resulting page for the topic would look like the following with custom tag at the top of the page:
