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

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…