C# Documentation - User Defined Tags

Question

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

Is there a reason you could not simply include that info in the <param name="args"> and <returns> content? — AnthonyWJones
– AnthonyWJones, Commented Aug 28, 2009 at 10:35
Yes. Simplest precondition imply direct parameter connection; in this case you're right. But classes could be more complex, and methods could be called only on certain class states... describing it without underlaying pre-post conditions could be a pity, especially when all my classes have defined with DBC. — Luca
– Luca, Commented Aug 28, 2009 at 11:04

PVitt · Accepted Answer · 2009-08-28 10:41:49Z

5

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.

answered Aug 28, 2009 at 10:41

PVitt

11.8k5 gold badges54 silver badges85 bronze badges

Sign up to request clarification or add additional context in comments.

9 Comments

Luca Over a year ago

I know how to document C# code. You're stating that is not possible to extent documentation tags, without at least an iteration with the software generating documentation?

Chris S Over a year ago

Both NDoc and Sandcastle support extended tags. NDoc always has since its release

atconway Over a year ago

The link that supports this answer is broken, and Sandcastle does support customization of the associated main_sandcastle.xsl file to add in self made tags.

PVitt Over a year ago

@atconway A broken link after three and a half year is a reason for downvoting?

meataxe Over a year ago

Not sure if this is useful so long after the original question, but here is the last saved copy (from 2009) of the page in this response: web.archive.org/web/20090604112954/http://thoughtpad.net/…

|

Chris S · Accepted Answer · 2009-08-28 13:27:29Z

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.

edited Aug 28, 2009 at 13:27

answered Aug 28, 2009 at 11:30

Chris S

65.6k53 gold badges225 silver badges240 bronze badges

Collectives™ on Stack Overflow

C# Documentation - User Defined Tags

2 Answers 2

9 Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

9 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related