Write detailed C# XML documentation and still keep the source code clean

October 20, 2014, (updated on January 12, 2015), Software Development

For my open-source project MyToolkit I write a lot of documentation. Currently the documentation for a class has to be updated in two locations: The source code and the project’s wiki. I asked myself how to avoid this and document everything in the source code file – while keeping the source code simple by not putting too much documentation in it.

To write detailed documentation in your C# code, you can use the tags <remarks> and <example> (<summary> should always be there). To avoid polluting the source code file with documentation, you can additionally use the <include> tag to “outsource” the documentation to an external XML file.

As an example, your class may look like this:

/// <summary>My class summary. </summary>
/// <include file='/Documentation.xml' path='Documentation/MyClass/Class/*'/>
public class MyClass
{
    ...

In your project root, add a new XML file called “Documentation.xml” with the following content:

<Documentation>
  <MyClass>
    <Class>
      <remarks>
        Add your remarks here. 
      </remarks>
      <example>
        Add your example code here. 
      </example>
    </Class>
  </MyClass>
</Documentation>

Now the <remarks> and <example> tags get copied into the documentation of the class and the source code file does not contain too much documentation.

Now I have to decide whether it is a good idea to start replacing the project wiki with a documentation which is only generated from source code. Generating a HTML documentation from XML doc can be done by using a tool like Sandcastle Help File Builder

Tweet about this on TwitterShare on FacebookEmail this to someoneShare on TumblrShare on LinkedIn

Tags: , , ,

Leave a Reply

Your email address will not be published. Required fields are marked *

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    
    Markdown is turned off in code blocks:
     [This is not a link](http://example.com)

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see http://daringfireball.net/projects/markdown/syntax