描述属性与<摘要>属性标签

Question

我正在 VS 2005 下用 C# 编写一个类库（我知道，与现代接轨，但我们这里的预算很紧张）。

在我看来，如果我在 XML 文档中使用“摘要”标签，我的用户可以通过 Intellisense 和工具提示等看到该信息，但不能在 Studio 的“属性”窗口中看到该信息。

要在该窗口中获取某些内容，我似乎需要使用 [Description("This is it")] 属性。

我的说法正确吗？如果是这样，那么我似乎需要复制描述信息:-(

或者，有更好的方法吗？谢谢！

Answer 1

是的，这是正确的。这两种方法有非常不同的目的。

• ///

  注释用于在编译时为项目生成 XML 文档，Visual Studio 也会对其 IntelliSense 数据库进行解析。

• [DescriptionAttribute] 提供设计器中使用的描述文本，尤其是在属性窗口的底部。

Microsoft 自己的 Windows 窗体库中充斥着这两种内容。

我不知道有什么方法可以将两者合并，但请考虑一下您是否真的希望它们完全相同。在我自己的类库中，我经常希望在设计器中显示与技术文档中包含的信息略有不同的信息。

作为一个简单的示例，我可能想在设计器中明确指出，某些版本的 Windows 不支持此属性，但将此信息归入我的技术文档中的 部分：

/// <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

摘要 XML 文档标签和描述属性是两个完全不同的东西。

摘要标签用于组件的文档。

DescriptionAttribute 是控件组件模型的一部分，并且在运行时在应用程序中可用。这意味着信息被编译到您的二进制程序集文件中。应用程序的最终用户可以看到描述属性的内容（例如，当使用 PropertyGrid 控件时）。

如果您正在寻找文档，请仅使用 XML 文档。如果您希望创建可重用的组件，也可以使用“描述”属性。

Answer 3

我的理解是你是对的。不过，您可以使用 GhostDoc 自动化大部分工作，它有一个免费版本，您可以自定义添加到您的描述属性中。