Question

Is there a standard way that the tools used to generate the API documents handle having XML Style comments on partial classes? Basically, how should one comment a partial class/method so that the resulting help documents aren’t mangled? This question could vary depending on the tool used, in which case, I guess the two tools that are the most important are:

• Visual Studio’s built in method to create XML documentation
• Microsoft’s Sandcastle

I don’t want my XML documentation to come out funky is all

/// <summary>Some Foo class</summary>
public partial class Foo { ... }

/// <summary>Some Foo class that implements some interface.</summary>
public partial class Foo : ISomeInterface { ... }

Answer 1

The best practice is to give XML comments to just 1 of the partial definitions. There should be no need to split public comments for 1 class into 2 places. (Of course regular comments still make sense to have in each partial definition.)

The way Visual Studio works is that a comment in one partial definition will override the other. You can confirm this by creating 2 partial definitions of the same class with different XML comments, then create a variable of this type. The intellisense will show only 1 of the XML comments.

This will also be the behavior of any documentation tool that uses the XML comments file generated by Visual Studio, which includes Sandcastle.