Share via

Supporting Custom tags in Sandcastle

  • Article

Sandcastle supports C# (and VB) xml tags for developer documentation comments. The list of c# tags are available at https://msdn2.microsoft.com/en-us/library/5ast78ax.aspx. We added the following new custom nDoc tags in November CTP (https://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 https://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:

Custom Tags

Comments

  • Anonymous
    November 22, 2006
    Hi Anand, This feature calls the following question: if I modify Sandcastle XSL files, can I distribute the modified version? The current answer is, I think, no, because the file is licensed as a part of the software, under  "don't modify" and "don't distribute" clauses. It would be necessary to release the XSL files under a more liberal license, or, the best, under the public domain. Otherwise the 'custom tags' feature cannot be used legally... Gael

  • Anonymous
    November 22, 2006
    Good point Gael. I will check this with Microsoft legal contact and will let you know. We cannot meet all the custom tags and this is the bext way to go. I will see if we can exclude the presentation tansforms from the license. Anand..

  • Anonymous
    November 25, 2006
    Un post sur le blog de Sandcastle explique comment gérer les tags personnalisés, en particulier la modification

  • Anonymous
    November 26, 2006
    About two weeks ago, Microsoft have released a new CTP for Sandcastle . For those still in the dark,

  • Anonymous
    December 10, 2006
    Un post sur le blog de Sandcastle explique comment gérer les tags personnalisés, en particulier la modification

  • Anonymous
    November 07, 2007
    The DocProject 1.9.0 Release Candidate is now available on CodePlex. I'm still working on updating the

  • Anonymous
    January 16, 2012
    Hello, anything new about the Licence thing here?

  • Anonymous
    March 25, 2012
    The comment has been removed

  • Anonymous
    March 26, 2013
    So is this legal?

  • Anonymous
    May 31, 2013
    Hi Anand, first of all, congratulations. Your post was very usefull, And I've acomplished my goals and have included some custom information along my Class Anotations. Now, I've some complicated issues with custom tag in class member anotations like custom tags in class properties. Do you have some example in how to do that? Thanks in advance.