20

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 { ... }
Keith
  • 18,957
  • 10
  • 75
  • 119
myermian
  • 29,999
  • 21
  • 111
  • 199

1 Answers1

18

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.

Keith
  • 18,957
  • 10
  • 75
  • 119
  • Very good point. If Visual Studio's Intellisense choose between one XML comment over another, it's the one that is "more dominant". Would you say that it's considered standard practice to at least place a standard (non-XML comment) as well, or possibly duplicate the comment so it can be seen from either location if someone is inspecting the files themselves? – myermian May 13 '11 at 01:12
  • I think using a standard (non-XML) comment on the 2nd partial definition is the best approach. Use this to explain to the programmers why the partial definition exists and perhaps even to state that the XML comment is defined on the 1st partial. I recommend against duplicating the XML comment for maintainability reasons. – Keith May 13 '11 at 13:48
  • 1
    As for which comment is "more dominant" -- From what I've seen, dominance is simply determined by the last partial definition that Visual Studio comes across. For example if both partials are defined in the same file (not a good use case, I know) then it is always the 2nd definition that overrides the 1st. When the partials are in different files then I have to assume there is a standard order that Visual Studio follows when iterating through project files and that it is this order that will determine dominance. – Keith May 13 '11 at 13:51
  • 3
    @m-y Note that [this StyleCop page](http://stylecop.soyuz5.com/SA1601.html) suggests you use `` on only one part (as advocated by this answer), but then they recommend you use a `` tag on each of the other "parts" that do not carry the ``. However, I am not sure that `` element is standard (as Visual Studio does not appear to have the "IntelliSense" completion for it). – Jeppe Stig Nielsen Jun 14 '16 at 13:45