c# - 如何在 IntelliSense 中为 Visual Studio 中的功能添加注释？

Question

在 Visual Studio 和 C# 中，当使用 ToString() 等内置函数时，IntelliSense 会显示一个黄色框来解释它的作用。

对于我编写的函数和属性，我怎样才能拥有它？

Answer 1

要生成一个区域，您可以在其中指定函数的描述和函数的每个参数，请在函数之前的行中键入以下内容并点击Enter：

• C＃： ///

• VB： '''

有关可以包含在这些注释中的结构化内容的更多信息，请参阅文档注释的推荐标签（C# 编程指南） 。

Answer 2

您需要的是xml 注释- 基本上，它们遵循以下语法（正如 Solmead 模糊描述的那样）：

C＃

///<summary>
///This is a description of my function.
///</summary>
string myFunction() {
     return "blah";
}

VB

'''<summary>
'''This is a description of my function.
'''</summary>
Function myFunction() As String
    Return "blah"
End Function

Answer 3

<c>text</c>- 您想表示为代码的文本。
< c > 标签为您提供了一种方法来指示描述中的文本应标记为代码。使用 < code > 将多行表示为代码。

<code>content</code>- 您想要标记为代码的文本。
< code > 标签为您提供了一种将多行指示为代码的方法。使用 < c > 表示描述中的文本应标记为代码。

<example>description</example>- 代码示例的描述。
< example > 标签让您指定如何使用方法或其他库成员的示例。这通常涉及使用 < code > 标签。

<exception cref="member">description</exception>- 异常的描述。
< exception > 标签让你指定可以抛出哪些异常。此标记可应用于方法、属性、事件和索引器的定义。

<include file='filename' path='tagpath[@name="id"]' />
< include > 标记允许您引用另一个文件中描述源代码中的类型和成员的注释。这是直接在源代码文件中放置文档注释的替代方法。通过将文档放在单独的文件中，您可以将源代码控制与源代码分开应用于文档。一个人可以签出源代码文件，其他人可以签出文档文件。< include > 标记使用 XML XPath 语法。请参阅 XPath 文档以了解自定义 < include > 使用的方法。

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

< listheader > 块用于定义表或定义列表的标题行。定义表格时，您只需在标题中提供术语条目。列表中的每个项目都使用 < item > 块指定。创建定义列表时，您需要指定术语和描述。但是，对于表格、项目符号列表或编号列表，您只需要提供一个条目进行描述。列表或表格可以根据需要包含任意数量的 < item > 块。

<para>content</para>
< para > 标签用于标签内部，例如< summary >、< remarks > 或< returns >，并允许您为文本添加结构。

<param name="name">description</param>
< param > 标签应该用在方法声明的注释中，以描述方法的参数之一。要记录多个参数，请使用多个 < param > 标签。< param
> 标记 的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报告中。

<paramref name="name"/>
< paramref > 标记为您提供了一种方法来指示代码注释中的单词，例如在 < summary > 或 < remarks > 块中引用参数。可以处理 XML 文件以以某种不同的方式格式化该单词，例如使用粗体或斜体字体。

< permission cref="member">description</permission>
< permission > 标签让您记录成员的访问权限。PermissionSet 类允许您指定对成员的访问权限。

<remarks>description</remarks>
< remarks > 标签用于添加关于类型的信息，补充 < summary > 指定的信息。此信息显示在对象浏览器中。

<returns>description</returns>
< returns > 标签应该用在方法声明的注释中来描述返回值。

<see cref="member"/>
< see > 标签允许您从文本中指定链接。使用 < seealso > 指示文本应放置在 See Also 部分中。使用 cref 属性为代码元素创建指向文档页面的内部超链接。

<seealso cref="member"/>
< seealso > 标记可让您指定可能希望出现在“另见”部分中的文本。使用 < see > 从文本中指定链接。

<summary>description</summary>
< summary > 标签应该用于描述类型或类型成员。使用 < remarks > 将补充信息添加到类型描述中。使用 cref 属性启用文档工具，例如 Sandcastle，以创建指向代码元素文档页面的内部超链接。< summary > 标记的文本是 IntelliSense 中类型信息的唯一来源，也显示在对象浏览器中。

<typeparam name="name">description</typeparam>
< typeparam > 标签应该用在泛型类型或方法声明的注释中来描述类型参数。为泛型类型或方法的每个类型参数添加一个标记。< typeparam > 标记的文本将显示在 IntelliSense（对象浏览器代码注释 Web 报告）中。

<typeparamref name="name"/>
使用此标签可以使文档文件的使用者以某种不同的方式格式化单词，例如斜体。

<value>property-description</value>
< value > 标签让你描述一个属性代表的值。请注意，当您在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它将为新属性添加一个 < summary > 标记。然后，您应该手动添加一个 < value > 标记来描述该属性所代表的值。

Answer 4

做 XML 注释，像这样

/// <summary>
/// This does something that is awesome
/// </summary>
public void doesSomethingAwesome() {}

Answer 5

使用 /// 开始评论的每一行，并让评论包含元数据阅读器的适当 xml。

///<summary>
/// this method says hello
///</summary>
public void SayHello();

尽管就我个人而言，我相信这些评论通常是被误导的，除非你正在开发代码不能被消费者阅读的类。

Answer 6

这些被称为XML 注释。它们一直是 Visual Studio 的一部分。

您可以使用GhostDoc 简化文档过程，它是 Visual Studio 的免费插件，可为您生成 XML 文档注释。只需将插入符号放在要记录的方法/属性上，然后按 Ctrl-Shift-D。

这是我的一篇文章中的一个例子。

希望有帮助:)

Answer 7

定义这样的方法，您将获得所需的帮助。

    /// <summary>
    /// Adds two numbers and returns the result
    /// </summary>
    /// <param name="first">first number to add</param>
    /// <param name="second">second number to </param>
    /// <returns></returns>
    private int Add(int first, int second)
    {
        return first + second;
    }

代码使用截图

Answer 8

在 CSharp 中，如果您使用 Parms 创建方法/函数大纲，那么当您添加三个正斜杠时，它将自动生成摘要和 parms 部分。

所以我输入：

public string myMethod(string sImput1, int iInput2)
{
}

然后我把三个 /// 放在它前面，Visual Studio 给了我这个：

/// <summary>
/// 
/// </summary>
/// <param name="sImput1"></param>
/// <param name="iInput2"></param>
/// <returns></returns>
public string myMethod(string sImput1, int iInput2)
{
}

Answer 9

阅读http://msdn.microsoft.com/en-us/library/3260k4x7.aspx仅指定注释不会在智能感知中显示帮助注释。

Answer 10

所有这些其他答案都是有道理的，但并不完整。Visual Studio 将处理 XML 注释，但您必须打开它们。以下是如何做到这一点：

Intellisense 将使用您在源代码中输入的 XML 注释，但您必须通过 Visual Studio 选项启用它们。转到Tools> Options> Text Editor。对于 Visual Basic，启用Advanced>Generate XML documentation comments for '''设置。对于 C#，启用Advanced>Generate XML documentation comments for ///设置。Intellisense 将在输入时使用摘要注释。编译引用的项目后，它们将在其他项目中可用。

要创建外部文档，您需要通过控制编译器选项的Project Settings>>路径生成 XML 文件Build。您将需要一个外部工具，它将 XML 文件作为输入并以您选择的输出格式生成文档。XML documentation file:/doc

请注意，生成 XML 文件会显着增加编译时间。

Answer 11

此外，Visual Studio 插件 Ghost 文档将尝试根据您的函数名称创建和填写标题注释。

Answer 12

Solmead 有正确的答案。有关更多信息，您可以查看XML 注释。