What is the purpose of defining both <summary> and <value> in a C# automatically implemented property?

Question

The C# specification/StyleCop (not sure which) suggests that an auto-property be annotated with two tags -- <summary> and <value>, giving something like:

class Foo
{
    /// <summary>Gets bar.</summary>
    /// <value>Bar.</value>
    public Example Bar { get; set; }
}

But for all practical purposes, the value of <summary> is always Gets <whatever you said for value here\>.

Is the separate tag here to help out a specific documentation generator, or have something to do with the way the compiler stamps out auto-properties, or something else?

Answer 1

The auto-suggested contents of these two tags are redundant, as you point out. However, the text you would put in these two tags should be different for a well documented class, for example as part of a public API.

For example, let's have a look at Microsoft's public API documenation for the DateTime.Date property.

The <summary> and the <value> tags in the comment correspond to two different sections of the documentation. In this case, the docs might have been generated from a comment like:

/// <summary>
///   Gets the date component of this instance.
/// </summary>
/// <value>
///   A new object with the same date as this instance, and the time value
///   set to 12:00:00 midnight (00:00:00).
/// </value>

So you can see that the "summary", which is used in tooltips, is an abbreviated summary of the property, whereas the "value" is a more detailed description of the value returned.

Read the full documentation of the <summary> and <value> tags for more details.