DescriptionAttribute vs. <summary> tag for Properties

Question

I'm writing a Class Library in C# under VS 2005 (I know, get with modern times, but we're on a tight budget here).

It appears to me that if I use a "summary" tag in the XML documentation, my users can see that info via Intellisense and tooltips, etc., but not in the Properties window in Studio.

To get something in that window, I seem to need to use a [Description("This is it")] attribute.

Am I correct on this? If so, then it would seem that I need to duplicate the description info :-(

Or, is there a better way? Thanks!

Answer 1

Yes, that's correct. The two methods have very different purposes.

• The /// <summary></summary> comments are used to generate XML documentation for your project at compile-time, which is also parsed by Visual Studio for its IntelliSense database.

• The [DescriptionAttribute] provides description text that is used in the designer, most notably at the bottom of the Properties Window.

Microsoft's own Windows Forms library is littered with both these.

I don't know of any way to merge the two, but consider whether you really want them to be exactly the same. In my own class libraries, I often want to display slightly different information in the designer than I want to include in my technical documentation.

As a simple example, I might want to make clear in the designer that this property is not supported under certain versions of Windows, but relegate this information to the <remarks> section in my tech docs:

/// <summary>
/// Gets or sets a value indicating whether a shield should be displayed
/// on this control to indicate that process elevation is required.
/// </summary>
/// <remarks>
/// The elevation-required shield is only supported under Windows Vista
/// and later. The value of this property will be ignored under earlier
/// operating systems.
/// </remarks>
[Category("Appearance")]
[Description("Displays a shield to indicate that elevation is required. " +
             "(Only applies under Windows Vista and later.)")]
public bool ShowShield { get; set; }

Answer 2

A summary XML doc tag and a Description Attribute are two completely different things.

The summary tag is for use in the DOCUMENTATION for a componenent.

The Description Attribute is part of the contols component model and is available within the application at run-time. That means that info gets compiled into your binary assembly file. Potentially the content of the Description Attribute is even visible to end users of your application (e.g. when using the PropertyGrid control).

If you are looking for documentation only use the XML doc. If you are looking to create a reusable component you may use the Description attribute, too.