如何在IntelliSense中为Visual Studio中的函数添加注释？

Question

在Visual Studio和C＃中，当使用内置函数（如ToString（））时，IntelliSense会显示一个黄色框，说明它的作用。

如何为我编写的功能和属性提供此功能？

Answer 1

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

• C＃： ///

• VB： '''

有关您可以在这些评论中添加的结构化内容的详情，请参阅Recommended Tags for Documentation Comments (C# Programming Guide)。

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> - 您要表示为代码的文字。
＆lt; c ＆gt; tag为您提供了一种方法，用于指示描述中的文本应标记为代码。使用＆lt; 代码＆gt;将多行表示为代码。

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

<example>description</example> - 代码示例的说明 ＆lt; 示例＆gt; tag允许您指定如何使用方法或其他库成员的示例。这通常涉及使用＆lt; 代码＆gt;标签

<exception cref="member">description</exception> - 例外说明 ＆lt; 例外＆gt; tag允许您指定可以抛出的异常。此标记可以应用于方法，属性，事件和索引器的定义。

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

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

＆lt; listheader ＆gt; block用于定义表或定义列表的标题行。定义表时，只需在标题中提供term的条目。 列表中的每个项目都使用＆lt; item ＆gt;指定。块。创建定义列表时，您需要同时指定术语和描述。但是，对于表，项目符号列表或编号列表，您只需提供描述条目。 列表或表可以包含尽可能多的＆lt; item ＆gt;根据需要阻止。

<para>content</para>
＆lt; para ＆gt;标记用于标记内，例如＆lt; 摘要＆gt;，＆lt; 备注＆gt;或＆lt; 返回＆gt;，并允许您在文本中添加结构。

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

<paramref name="name"/>
＆lt; paramref ＆gt; tag为您提供了一种在代码注释中指示单词的方法，例如在＆lt; 摘要＆gt;中或＆lt; 备注＆gt;块指的是一个参数。可以处理XML文件以便以某种不同的方式格式化此单词，例如使用粗体或斜体字体。

＆lt; permission cref="member">description</permission>
＆lt; 权限＆gt; tag允许您记录成员的访问权限。 PermissionSet类允许您指定对成员的访问权。

<remarks>description</remarks>
＆lt; 备注＆gt; tag用于添加有关类型的信息，补充用＆lt; summary ＆gt;指定的信息。此信息显示在对象浏览器中。

<returns>description</returns>
＆lt; 返回＆gt; tag应该在注释中用于描述返回值的方法声明。

<see cref="member"/>
＆lt; 参见＆gt; tag允许您从文本中指定链接。使用＆lt; seealso ＆gt;表示文本应放在另请参阅部分中。使用cref属性为代码元素的文档页面创建内部超链接。

<seealso cref="member"/>
＆lt; seealso ＆gt; tag允许您指定您可能希望在“请参阅”部分中显示的文本。使用＆lt; 参见＆gt;从文本中指定链接。

<summary>description</summary>
＆lt; 摘要＆gt; tag应该用于描述类型或类型成员。使用＆lt; 备注＆gt;将补充信息添加到类型描述中。使用cref属性可以启用Sandcastle等文档工具来创建代码元素文档页面的内部超链接。 ＆lt; 摘要＆gt;的文字tag是有关IntelliSense中类型的唯一信息源，也显示在对象浏览器中。

<typeparam name="name">description</typeparam>
＆lt; typeparam ＆gt; tag应该在注释中用于泛型类型或方法声明来描述类型参数。为泛型类型或方法的每个类型参数添加标记。 ＆lt; typeparam ＆gt;的文本标签将显示在IntelliSense中，即对象浏览器代码注释网站报告。

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

<value>property-description</value>
＆lt; 值＆gt; tag允许您描述属性表示的值。请注意，在Visual Studio .NET开发环境中通过代码向导添加属性时，它将添加＆lt; 摘要＆gt;标签为新属性。然后，您应手动添加＆lt; 值＆gt;用于描述属性表示的值的标记。

Answer 4

执行XML评论，例如

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

Answer 5

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

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

虽然就个人而言，我认为这些评论通常是误导的，除非您正在开发其消费者无法读取代码的类。

Answer 6

这些被称为XML Comments。他们永远是Visual Studio的一部分。

使用GhostDoc，Visual Studio的免费加载项，可以为您生成XML-doc注释，从而使您的文档编制过程更加轻松。只需将您的插入符号放在要记录的方法/属性上，然后按Ctrl-Shift-D。

以下是one of my posts的示例。

希望有所帮助：）

Answer 7

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

阅读http://msdn.microsoft.com/en-us/library/3260k4x7.aspx只是指定评论不会在intellisense中显示帮助评论。

Answer 9

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

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

Answer 10

Visual Studio插件幽灵文档也会尝试创建并填写函数名称中的标题注释。

Answer 11

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

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

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

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

Answer 12

Solmead有正确的答案。有关详细信息，请查看XML Comments。