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

Question

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?

Answer 1

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 out of range.
/// </returns>

Unlike what @Bertie seems to be suggesting, I always try to reduce the verbosity and increase the information content - As you know what the method does, you may not need so much detail in the parameter description to describe what it is for, as it's often pretty obvious/intuitive - but you will often be able to add more detail about what values are legal or how the parameter is used, to help the reader understand how best to use it. Similarly for detail about what kind of return value I will get (e.g. whether I might get back zero, negative values, nulls, etc)

Think of this documentation as defining the code contract - the more explicitly you state the contract, the less ambiguous it becomes and the more easily another programmer will be able to work out how they can (and cannot) use your method without having to read the source code. Or identify if the behaviour of your method is as intended or a bug. Or know how much they can alter the behaviour of your method without breaking any of the existing calling code.

Of course, in some cases a method really is simple and obvious enough that you can just comment it with AtomineerUtils and move on, saving time for more important work. Often programming needs to be a balance between being practical (get the work done and the product shipped) and meeting theoretical ideals (DRY, etc).