Storing XML Comments in Separate Files

Problem
You’re concerned about XML comments causing clutter in your source files. You wonder if there are other options.

Solution
Use the include tag in XML comments to reference an external .xml file that contains the actual documentation.

Comments
Keeping XML comments in a separate file reduces clutter and allows two different people to work on the source code and documentation.

Examples
Here’s an example of how to use the include tag. First, prepare an XML file named doc.xml that includes the following text:

<?xml version="1.0" encoding="utf-8" ?>
<MyDoc>
    <Doc name="Account">
        <summary>
            An account type.
        </summary>
    </Doc>
</MyDoc>

Next, reference the documentation in the source like so:

/// <include file='doc.xml' path='MyDoc/Doc[@name="Account"]/*' />
public class Account
{
    ...
}

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s