Can I add subsections to my XML comments?

Oct 6, 2009 at 8:44 AM

I would like to include a reference to the application specification to some class methods. Right now I'd include them in a separate paragraph in the <remarks> section. But as with <threadsafety> and <seealso>, I think it would be cool to get those in their own subsection like "Specification".

Is there a way to add those subsections to the reference documentation from within the method XML comments?

I've checked Dynicity's incomplete PDF reference on XML comments, the SHFB documentation on additional/conceptual content, this forum and the Sandcastle XSL files but couldn't find a definitive solution. My XSL skills are limited so I can barely understand what's going on but I couldn't add my own tag.

Oct 6, 2009 at 12:55 PM

While this is really a Sandcastle question, I'll try to describe what we have done for our documentation. We use a custom tag related-demos:


  1. Modify <Sandcastle_Dir>\Presentation\<your style>\transforms\main_sandcastle.xsl:
  • Add a template match (I just put it near the other sections, as threadsafety etc.
      <xsl:template match="related-demos">
        <xsl:call-template name="section">
          <xsl:with-param name="toggleSwitch" select="'relatedDemos'"/>
          <xsl:with-param name="title">
            Demos
          </xsl:with-param>
          <xsl:with-param name="content">
            <xsl:element name="ul">
             <xsl:apply-templates />
            </xsl:element>
          </xsl:with-param>
        </xsl:call-template>
      </xsl:template>
    
    The important part is to call the "section" template
  • At the top of the file, in the "body" template, add a template selector
        <xsl:apply-templates select="/document/comments/related-demos" />
    
    at the location where you want your subsection to appear.

You can use the existing section templates (as for threadsafety) as a guideline...

 

Oct 7, 2009 at 11:00 AM

Thank you, that works fine.

I sometimes don't know where to draw the line between Sandcastle and SHFB as the latter one also extends it IIRC. In those cases, I start with what I see, and that's the foremost GUI...