Alex Rivera | Logout

How should I write XML comments to avoid repeating myself between the summary and returns tags?

Asked 2012-01-26T10:27:13.330
17

When the purpose of a method is to calculate a value and return it, I find myself documenting it as follows:

/// <summary>
/// Calculates the widget count.
/// </summary>
/// <param name="control">The control to calculate the widget count of.</param>
/// <returns>The widget count.</returns>

Here the returns tag does not provide any new information: it's just repeating what's in the summary. (The exception is methods that return bool, where it's easy to explain what the true and false return values mean.)

Am I missing something? Is there a standard way of wording XML documentation blocks to avoid repetition between the summary and returns tags?

c# documentation comments xml-documentation
Edit
Report

1 Answer

11

Sometimes documentation does tend to repeat itself, especially with Properties (to an external caller they should look and feel just like simple values, so it is hard to see any point in providing both 'summary' and 'value' entries).

So I try to draw a distinction between the summary and param/returns/value etc that reduces the repetitiveness. The summary briefly describes what the method does (calculate the widget count), while the param/returns/value give detail of the inputs/outputs (and nothing else). In many cases you then see a more marked difference between the entries - reading your example, I immediately have questions about the API that the documentation doesn't answer, so I'd be hoping to see something more like one of these alternatives:

/// <summary>Recursively calculates the widget count for a given control.</summary> 
///
/// <param name="control">The root control of the subtree to process, or null.</param> 
///
/// <returns>
/// The number of widgets that are contained within 'control' and its
/// entire subtree of descendant controls (or 0 if control is null).
/// </returns>

or...

/// <summary>Calculates the widget count for a given control.</summary> 
///
/// <param name="control">The control to process. May be null.</param> 
///
/// <returns>
/// The number of widgets that are direct children of 'control', or
/// -1 if it is null/not a registered control.
/// </returns>

or even ...

/// <summary>
/// Calculates the widget 'count' for a given control using the
/// Wicker-Bartland meanest minimum average algorithm.
/// </summary>
///
/// <param name="control">
/// The Wicker-Bartland control-input-value, in the range 1.0 .. 42.6
/// </param> 
///
/// <returns>
/// The widget count, in the range -2PI .. +2PI, or Double.NaN if the
/// input control value is o
answered 2012-01-27T23:51:24.690

Your Answer