我正在 VS 2005 下用 C# 编写一个类库(我知道,与现代同步,但我们这里的预算很紧)。
在我看来,如果我在 XML 文档中使用“摘要”标签,我的用户可以通过 Intellisense 和工具提示等查看该信息,但不能在 Studio 的“属性”窗口中查看。
为了在那个窗口中得到一些东西,我似乎需要使用一个[Description("This is it")]
属性。
我对此是否正确?如果是这样,那么我似乎需要复制描述信息:-(
或者,还有更好的方法?谢谢!
我正在 VS 2005 下用 C# 编写一个类库(我知道,与现代同步,但我们这里的预算很紧)。
在我看来,如果我在 XML 文档中使用“摘要”标签,我的用户可以通过 Intellisense 和工具提示等查看该信息,但不能在 Studio 的“属性”窗口中查看。
为了在那个窗口中得到一些东西,我似乎需要使用一个[Description("This is it")]
属性。
我对此是否正确?如果是这样,那么我似乎需要复制描述信息:-(
或者,还有更好的方法?谢谢!
对,那是正确的。这两种方法有非常不同的目的。
注释用于在/// <summary></summary>
编译时为您的项目生成 XML 文档,Visual Studio 也会对其 IntelliSense 数据库进行解析。
提供了在设计器中使用的[DescriptionAttribute]
描述文本,尤其是在“属性”窗口的底部。
微软自己的 Windows 窗体库中到处都是这些。
我不知道有什么方法可以将两者合并,但请考虑您是否真的希望它们完全相同。在我自己的类库中,我经常希望在设计器中显示与我希望包含在我的技术文档中的信息略有不同的信息。
举个简单的例子,我可能想在设计器中明确指出,某些版本的 Windows 不支持此属性,但将此信息归入<remarks>
我的技术文档中的部分:
/// <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; }
摘要 XML 文档标记和描述属性是两个完全不同的东西。
摘要标签用于组件的文档中。
描述属性是 contols 组件模型的一部分,可在应用程序运行时使用。这意味着信息被编译到您的二进制程序集文件中。描述属性的内容可能对您的应用程序的最终用户是可见的(例如,当使用 PropertyGrid 控件时)。
如果您正在寻找文档,请仅使用 XML 文档。如果你想创建一个可重用的组件,你也可以使用 Description 属性。
我的理解是你是对的。但是,您可以使用 GhostDoc自动完成大部分工作,它有一个免费版本,您可以自定义添加到您的 Description 属性中。