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

Question

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

我怎样才能为我编写的函数和属性使用它？

Answer 1

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

• C#: ///

• VB: '''

有关可以包含在这些 cmets 中的结构化内容的更多信息，请参阅 Recommended Tags for Documentation Comments (C# Programming Guide)。

Answer 2

做 XML 注释，像这样

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

Answer 3

Solmead 有正确的答案。欲了解更多信息，您可以查看XML Comments。

Answer 4

使用 /// 开始注释的每一行，并让注释包含元数据阅读器的 appropriate xml。

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

尽管就我个人而言，我认为这些 cmets 通常是被误导的，除非您正在开发其代码无法被消费者阅读的类。

Answer 5

Visual Studio 插件 Ghost Doc 还将尝试根据您的函数名称创建和填写标头 cmets。

Answer 6

您需要的是 xml cmets - 基本上，它们遵循以下语法（正如 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 7

那些被称为XML Comments。它们一直是 Visual Studio 的一部分。

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

这是来自one of my posts 的示例。

希望有帮助:)

Answer 8

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

Answer 9

在 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 10

<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> 标记允许您引用另一个文件中的 cmets，该文件描述了源代码中的类型和成员。这是将文档 cmets 直接放在源代码文件中的替代方法。通过将文档放在单独的文件中，您可以将源代码控制与源代码分开应用于文档。一个人可以签出源代码文件，其他人可以签出文档文件。 include> 标记使用 XML XPath 语法。有关自定义 include> 使用的方法，请参阅 XPath 文档。

<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> 标记为您提供了一种方法来指示代码中的单词 cmet，例如在 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 11

所有这些其他答案都有意义，但不完整。 Visual Studio 将处理 XML cmets，但您必须打开它们。这样做的方法如下：

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

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

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

Answer 12

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

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

Screenshot of the code usage