Rory Primrose

Learn from my mistakes, you don't have time to make them yourself

View project on GitHub

Guidance on use of include in XML documentation comments

I have previously posted about using the include element for my XML documentation in cases where there is duplicated content. After a recent code review, the reviewer commented that the include element made it difficult to read the documentation because large parts of the XML documentation were abstracted out to an XML file. This made me look at ways around this and the affect of the include tag had on the tooling support.

As a quick overview, the include element in XML documentation tells the compiler to go to the specified XML file and run an XPath query (recursively). It pulls in the result of that XPath query and injects the content into the XML documentation being generated for a code element.

Advantages

  • Documentation reuse
  • Removes noise in a code file if the bulk of the documentation points to an included reference

Disadvantages

Guidance

There is a tug of war between the reducing noise advantage and the readability disadvantage so the decision between the two must be made with respect to the code and its readers/consumers.

The disadvantages listed are primarily regarding the tooling support. With the issues stated for Visual Studio and R#, they are only issues for when the interpretation of the XML documentation is done from the source directly (meaning intellisense within the same solution), rather than the compiler generated XML documentation file. The SC issue is a bigger disadvantage especially if you are using the tool for strict validation as part of a continuous integration process.

To satisfy all but the readability disadvantage, I suggest that you avoid using an include to:

  1. Define XML documentation structure required by SC (summary, param and returns elements)
  2. Define content that affect SC validation (summary, param and returns elements)
  3. Define XML documentation structure parsed by Visual Studio intellisense (exception element)
  4. Define content that affect Visual Studio and R# intellisense (summary, param and returns elements)

The include element is very useful for moving remarks and code examples out of the code file to reduce noise. When reading the code file, these items are not normally required for the readability of the file and don’t affect intellisense.

Note: The SC issues should be fixed in the next version. There is no indication about intellisense fixes to Visual Studio or R#. The use of the include element may change as these issues are fixed.

Written on January 12, 2009