Difference between <summary> and <value> tags

  • Thread starter Thread starter Edward Diener
  • Start date Start date
E

Edward Diener

I really do not understand the difference between the <summary> and <value>
XML document tags for a property. Why would one use one as opposed to the
other for a property, and when would one use both ?
 
Edward,

The two tags are completely different. Summary is used to summarize
what the item it is attached to is (in this case, the property itself).
Value is used to indicate what exactly the value is that the property
get/sets.

If you want to relate it to the MSDN documentation, the summary tag is
the first paragraph before the code declaration, while the value tag will
appear under the "property value" header further down in the documentation.

Summary should give a general overview, while value should give a
detailed explaination about the property.

Hope this helps.
 
I use the <summary> tag to describe what the property provides.

I use the <value> tag to explain what the values coming back mean.

Perhaps the clearest example would be for a boolean property:

<summary>Gets and indication of whether the object is
initialized.</summary>
<value><c>true</c>if the object is initialized; <c>false</c> if it is
not.</value>

Notice that the summary tells you what the property does for you. Value
tells you what the various possible values mean. Sometimes the two
descriptions are almost identical, but often there are special values
or an enumerated list of values. In these cases, the value tag provides
detailed information about what each value means.
 
Bruce Wood said:
I use the <summary> tag to describe what the property provides.

I use the <value> tag to explain what the values coming back mean.

Perhaps the clearest example would be for a boolean property:

<summary>Gets and indication of whether the object is
initialized.</summary>
<value><c>true</c>if the object is initialized; <c>false</c> if it is
not.</value>

Notice that the summary tells you what the property does for you. Value
tells you what the various possible values mean. Sometimes the two
descriptions are almost identical, but often there are special values
or an enumerated list of values. In these cases, the value tag provides
detailed information about what each value means.
Click to expand...

Understood. But regarding properties which can be any value within the range
which the type of the property provides, very often the summary explains the
value. Nonetheless your point, about value being an explanation of the
possible values of the property, is well taken. Thanks !
 
In commenting my code today I also noticed that a great use of the
<value> clause is to indicate what value comes back when the property
returns "nothing" in semantic terms.

For example, a property that returns a collection of "selected items":
what does it do if nothing is selected? Does it return an empty
collection, or a null reference? I use the <value> clause to document
this behaviour, which is more common than the true / false example I
gave above.

However, important information that would help the caller understand
how to use the property, such as units of measure, should be in the
<summary> section, as this is what appears in Intellisense as a tool
tip when the user mouses over your property name.
 
Back
Top