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


139

在Visual Studio和C#中,当使用诸如ToString()之类的内置函数时,IntelliSense会显示一个黄色框,说明其功能。

替代文字 替代文字

对于编写的函数和属性,我该如何使用?

Answers:


215

要生成一个区域,您可以在其中指定功能说明和功能的每个参数,请在功能之前的行上键入以下内容,然后单击Enter

  • C#: ///

  • VB: '''

有关可包含在这些注释中的结构化内容的更多信息,请参见文档注释的推荐标签(C#编程指南)


2
要强调的是:这是C ++ / C#中的三斜杠(正常注释为双斜杠)。在VB中,其两个单引号而不是双引号。
abelenky

1
实际上是vb中的三个单引号
Joel Coehoorn

1
实际上,在VB中,它用3个单引号引起来:“''
hometoast

2
或者,可以在VB文件中右键单击一个函数或类,然后单击“插入注释”。对于C#,您可以使用StyleCop,它会提示您编写好的文档标题
user1069816

GhostDoc是一个很棒的工具,可以为您添加很多文本。submain.com/products/ghostdoc.aspx
Karl Gjertsen

74

您需要的是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

23

<c>text</c>-您想表示为代码的文本。
< c >标记为您提供一种指示,说明中的文本应标记为代码。使用< 代码 >将多行表示为代码。

<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 >块用于定义表或定义列表的标题行。定义表时,只需在标题中提供术语条目。列表中的每个项目都用< item >块指定。创建定义列表时,需要同时指定术语和描述。但是,对于表,项目符号列表或编号列表,您只需要提供一个条目即可进行描述。列表或表可以根据需要包含任意多个< item >块。

<para>content</para>
< para >标记用于标记之内,例如< summary >,< remarks >或< turns >,并允许您在文本中添加结构。

<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>
< 备注 >标记用于添加有关类型的信息,以< summary > 指定的信息补充。此信息显示在对象浏览器中。

<returns>description</returns>
注释中应使用 < turns >标记来声明方法,以描述返回值。

<see cref="member"/>
< see >标记使您可以从文本中指定链接。使用< seealso >指示应将文本放在“另请参见”部分中。使用cref属性为代码元素的文档页面创建内部超链接。

<seealso cref="member"/>
< seealso >标记使您可以指定希望在“另请参阅”部分中显示的文本。使用< see >从文本内指定链接。

<summary>description</summary>
< summary >标记应用于描述类型或类型成员。使用< 备注 >将补充信息添加到类型描述中。使用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 >标记以描述该属性表示的值。


11

像这样做XML注释

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

6
对于参数,请添加:///<param name="paramName">Tralala</param>
The Oddler

10

使用///来开始注释的每一行,并使注释包含适用于元数据读取器的xml

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

虽然我个人认为这些注释通常会被误导,除非您正在开发不能使其使用者读取代码的类。


2
它们对于快捷方式提醒很有用,或者在您有库代码的任何地方都可以读取代码,但是这样做需要一些额外的工作。
Joel Coehoorn

1
从理论上讲,我同意您的意见,但是,如果您使用该ghostdoc东西,那么您会将噪声/信号比提高到某种程度,以至于其余评论都没有用。
DevelopingChris


6

在CSharp中,如果使用Parms创建方法/函数大纲,则在添加三个正斜杠时,它将自动生成Summary and 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)
{
}

6

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

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

代码用法的屏幕截图



2

所有其他所有答案都是有道理的,但并不完整。Visual Studio将处理XML注释,但是您必须打开它们。这样做的方法如下:

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

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

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


1

此外,Visual Studio加载项虚幻文档还将尝试从您的函数名称创建并填写标题注释。


By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.