Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

The purpose of using both <value> and <summary> tags in Visual Studio XML documentation

Tags:

I'm working in C# in VS 2012, adding XML documentation to my code, and I've accidentally turned on a StyleCop rule (SA1609, specifically), which "validates that a public or protected property contains a documentation header with a value tag".

There's also another rule (SA1604, intentionally turned on this time), which "validates that a documentation header contains a properly formatted summary tag".

However, I'm struggling to see what you'd put in the value tag that isn't already in the summary tag. Currently my summary tags say something along the lines of "Gets or sets something". What should be put in the corresponding value tag to complement that?

(Just to clarify, I'm happy with setting up StyleCop - it just drew my attention to the value tag when I accidentally turned on all the documentation rules)

MSDN isn't helping so much with this one:

  • The value tag's page seems to imply you should detail what backing field is being used (which seems like a bad idea in the interest of information hiding anyway).
  • Their How-To on XML documentation says that "a value tag is used to describe the property value". I'm not even sure what that means - it sounds a lot like the summary to me.

tl;dr

What is the point in having both summary and value tags in XML documentation for properties? How should they be used without repeating oneself?

like image 823
Philip C Avatar asked Apr 09 '13 12:04

Philip C


1 Answers

The summary is to give a general overview of what the property can do, whereas the value describes just that, what value to expect from the property.

Here is a good example of the difference on MSDN: List<T>.IList.IsFixedSize Property

Summary: Gets a value indicating whether the IList has a fixed size.

Value: true if the IList has a fixed size; otherwise, false. In the default implementation of List<T>, this property always returns false.

For the most part, summary tags will generally state "Gets or sets a value ...", whereas value tags will generally state what values to expect, including what the default value is expected to be.

like image 195
myermian Avatar answered Oct 11 '22 20:10

myermian