如何在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语法.有关自定义< 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 >块用于定义表或定义列表的标题行.定义表时,只需在标题中提供term的条目.列表中的每个项目都使用< 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>
在< 许可 >标签可以让你记录一个成员的访问.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轻松地使文档编写过程,GhostDoc是Visual Studio的免费插件,可为您生成XML-doc注释.只需将插入符号放在要记录的方法/属性上,然后按Ctrl-Shift-D即可.

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

希望有帮助:)

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

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

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

代码用法的屏幕截图