8

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!

Cody Gray - on strike
  • 239,200
  • 50
  • 490
  • 574
John66NY
  • 121
  • 1
  • 6
  • Thanks everyone, that's what I thought... not necessarily what I wanted ;-) – John66NY Apr 05 '11 at 12:42
  • If you're really intent on eliminating duplication, consider placing all the strings into a resource file. Then, you can simply extract the string values from the resource file, rather than writing them directly in your code. It also makes localization easier, if that's important to you. I neglected to mention this in my answer below; I'll be happy to add it if you find it's the missing link. – Cody Gray - on strike Apr 06 '11 at 06:34

3 Answers3

10

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; }
Cody Gray - on strike
  • 239,200
  • 50
  • 490
  • 574
3

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 component.

The DescriptionAttribute is part of the controls component model and is available within the application at run-time. That means that info gets compiled into your binary assembly file. The content of the Description Attribute can be 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.

jlehenbauer
  • 599
  • 2
  • 11
  • 33
Foxfire
  • 5,675
  • 21
  • 29
0

My understanding is that you are correct. However, you can automate most of this work by using GhostDoc, which has a free version that you can customize to add in your Description attribute.

BrandonZeider
  • 8,014
  • 2
  • 23
  • 20