C# Documentation - User Defined Tags

Question

Hi all!

I want to document my source (C# sources), indeed I use XML documentation tags defined. How I can define by specific tags?

For example I use a lot Design by Contract assertions. I'd like to have documentation sections for preconditions, postconditions, invariants... It should be desiderable to write documentation like:

/// <precond>arg != null</precond>
/// <postcond>return > 0</postcond>

Since I'm not an XML guru, someone of you (gurus) coould advice me?

I tried to use < include >, but it's impossible (to me) to have documentation built correctly.

Thank you very much

Answer 1

First a very usefull description of what is possible with xml comments.

Next thing is, that the applications generating your documentation have to be aware of your self made tags. I'm currently not aware of a documentation builder that can be extended with additional attribtes or elements.

Answer 2

Using NDoc to build the documentation and its custom tags might be a solution. One problem with NDoc is the development stopped a while ago.

Sandcastle also supports custom tags, I'm not sure if that works Sandcastle Builder though if that is an issue.

Both are done by customising the default XSL either uses for its transform, e.g.

<xsl:template match="myTag" mode="seealso-section">
    <h1 class="green">
         <xsl:value-of select="." mode="slashdoc"/>
    </h1>
    </xsl:template>     
    <xsl:template match="null" mode="slashdoc">
    <xsl:text> null reference (Nothing in Visual Basic) </xsl:text>
</xsl:template>

The XML (csc.exe /doc) that is built by the compiler has no namespaces enforced in the tags, so you are free to use any tags you like.