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; }