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

发布于 2024-07-13 13:40:02 字数 379 浏览 5 评论 0原文

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

替代文本替代文本

我如何才能为我编写的函数和属性拥有它?

In Visual Studio and C#, when using a built in function such as ToString(), IntelliSense shows a yellow box explaining what it does.

alt text

alt text

How can I have that for functions and properties I write?

如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

扫码二维码加入Web技术交流群

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

评论(12

云醉月微眠 2024-07-20 13:40:02

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

  • C#: ///

  • VB: '''

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

To generate an area where you can specify a description for the function and each parameter for the function, type the following on the line before your function and hit Enter:

  • C#: ///

  • VB: '''

See Recommended Tags for Documentation Comments (C# Programming Guide) for more info on the structured content you can include in these comments.

人│生佛魔见 2024-07-20 13:40:02

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

What you need is xml comments - basically, they follow this syntax (as vaguely described by 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
风筝在阴天搁浅。 2024-07-20 13:40:02

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

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

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

description - 异常的描述。
<例外> 标签允许您指定可以抛出哪些异常。 此标记可应用于方法、属性、事件和索引器的定义。


<包括> 标签允许您引用另一个文件中描述源代码中的类型和成员的注释。 这是直接将文档注释放入源代码文件中的替代方法。 通过将文档放在单独的文件中,您可以将源代码控制与源代码分开应用于文档。 一个人可以签出源代码文件,其他人可以签出文档文件。
<包括> 标签使用 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>

<列表标题> 块用于定义表或定义列表的标题行。 定义表格时,您只需在标题中提供术语条目。
列表中的每个项目都用<item>指定。 堵塞。 创建定义列表时,您需要指定术语和描述。 但是,对于表格、项目符号列表或编号列表,您只需提供一个描述条目。
列表或表格可以有尽可能多的<item> 根据需要进行块。

内容
<para> 标签用于标签内部,例如<摘要>、<备注>或<返回>,并允许您为文本添加结构。

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


<paramref> 标签为您提供了一种方法来指示代码注释中的单词,例如在<摘要>中。 或<备注> block 指的是一个参数。 可以对 XML 文件进行处理,以某种不同的方式格式化该单词,例如使用粗体或斜体字体。

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

<备注>描述
<备注> 标签用于添加有关类型的信息,补充用 <summary> 指定的信息。 该信息显示在对象浏览器中。

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

<参见 cref="member"/>
<参见> 标签允许您指定文本内的链接。 使用<seealso> 指示文本应放置在“另请参阅”部分中。 使用 cref 属性创建代码元素文档页面的内部超链接。


<另请参阅> 标签允许您指定可能希望出现在“另请参阅”部分中的文本。 使用<参见> 指定文本内的链接。

<摘要>描述
<总结> 标签应用于描述类型或类型成员。 使用<备注> 将补充信息添加到类型描述中。 使用 cref 属性可以启用 Sandcastle 等文档工具来创建指向代码元素文档页面的内部超链接。
<摘要> 的文本 标记是有关 IntelliSense 中类型的唯一信息源,并且也显示在对象浏览器中。

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


使用此标签使文档文件的使用者能够以某种不同的方式格式化单词,例如斜体。

<值>属性描述
<> 标签允许您描述属性所代表的值。 请注意,当您在 Visual Studio .NET 开发环境中通过代码向导添加属性时,它将添加一个<摘要> 新属性的标签。 然后,您应该手动添加一个<> 标签来描述属性所代表的值。

<c>text</c> - The text you would like to indicate as code.
The <c> tag gives you a way to indicate that text within a description should be marked as code. Use <code> to indicate multiple lines as code.

<code>content</code> - The text you want marked as code.
The <code> tag gives you a way to indicate multiple lines as code. Use <c> to indicate that text within a description should be marked as code.

<example>description</example> - A description of the code sample.
The <example> tag lets you specify an example of how to use a method or other library member. This commonly involves using the <code> tag.

<exception cref="member">description</exception> - A description of the exception.
The <exception> tag lets you specify which exceptions can be thrown. This tag can be applied to definitions for methods, properties, events, and indexers.

<include file='filename' path='tagpath[@name="id"]' />
The <include> tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file. By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code. One person can have the source code file checked out and someone else can have the documentation file checked out.
The <include> tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize your <include> use.

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

The <listheader> block is used to define the heading row of either a table or definition list. When defining a table, you only need to supply an entry for term in the heading.
Each item in the list is specified with an <item> block. When creating a definition list, you will need to specify both term and description. However, for a table, bulleted list, or numbered list, you only need to supply an entry for description.
A list or table can have as many <item> blocks as needed.

<para>content</para>
The <para> tag is for use inside a tag, such as <summary>, <remarks>, or <returns>, and lets you add structure to the text.

<param name="name">description</param>
The <param> tag should be used in the comment for a method declaration to describe one of the parameters for the method. To document multiple parameters, use multiple <param> tags.
The text for the <param> tag will be displayed in IntelliSense, the Object Browser, and in the Code Comment Web Report.

<paramref name="name"/>
The <paramref> tag gives you a way to indicate that a word in the code comments, for example in a <summary> or <remarks> block refers to a parameter. The XML file can be processed to format this word in some distinct way, such as with a bold or italic font.

<permission cref="member">description</permission>
The <permission> tag lets you document the access of a member. The PermissionSet class lets you specify access to a member.

<remarks>description</remarks>
The <remarks> tag is used to add information about a type, supplementing the information specified with <summary>. This information is displayed in the Object Browser.

<returns>description</returns>
The <returns> tag should be used in the comment for a method declaration to describe the return value.

<see cref="member"/>
The <see> tag lets you specify a link from within text. Use <seealso> to indicate that text should be placed in a See Also section. Use the cref Attribute to create internal hyperlinks to documentation pages for code elements.

<seealso cref="member"/>
The <seealso> tag lets you specify the text that you might want to appear in a See Also section. Use <see> to specify a link from within text.

<summary>description</summary>
The <summary> tag should be used to describe a type or a type member. Use <remarks> to add supplemental information to a type description. Use the cref Attribute to enable documentation tools such as Sandcastle to create internal hyperlinks to documentation pages for code elements.
The text for the <summary> tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser.

<typeparam name="name">description</typeparam>
The <typeparam> tag should be used in the comment for a generic type or method declaration to describe a type parameter. Add a tag for each type parameter of the generic type or method.
The text for the <typeparam> tag will be displayed in IntelliSense, the Object Browser code comment web report.

<typeparamref name="name"/>
Use this tag to enable consumers of the documentation file to format the word in some distinct way, for example in italics.

<value>property-description</value>
The <value> tag lets you describe the value that a property represents. Note that when you add a property via code wizard in the Visual Studio .NET development environment, it will add a <summary> tag for the new property. You should then manually add a <value> tag to describe the value that the property represents.

腹黑女流氓 2024-07-20 13:40:02

做XML注释,像这样

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

Do XML commenting , like this

/// <summary>
/// This does something that is awesome
/// </summary>
public void doesSomethingAwesome() {}
千里故人稀 2024-07-20 13:40:02

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

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

尽管就我个人而言,我认为这些评论通常会被误导,除非您正在开发其代码无法被其使用者读取的类。

use /// to begin each line of the comment and have the comment contain the appropriate xml for the meta data reader.

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

Although personally, I believe that these comments are usually misguided, unless you are developing classes where the code cannot be read by its consumers.

迟到的我 2024-07-20 13:40:02

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

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

代码使用截图

Define Methods like this and you will get the help you need.

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

千鲤 2024-07-20 13:40:02

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

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

这是我的一篇文章的示例。

希望有帮助:)

Those are called XML Comments. They have been a part of Visual Studio since forever.

You can make your documentation process easier by using GhostDoc, a free add-in for Visual Studio which generates XML-doc comments for you. Just place your caret on the method/property you want to document, and press Ctrl-Shift-D.

Here's an example from one of my posts.

Hope that helps :)

野侃 2024-07-20 13:40:02

在 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)
{
}

In CSharp, If you create the method/function outline with it's Parms, then when you add the three forward slashes it will auto generate the summary and parms section.

So I put in:

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

I then put the three /// before it and Visual Studio's gave me this:

/// <summary>
/// 
/// </summary>
/// <param name="sImput1"></param>
/// <param name="iInput2"></param>
/// <returns></returns>
public string myMethod(string sImput1, int iInput2)
{
}
爱冒险 2024-07-20 13:40:02

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

read http://msdn.microsoft.com/en-us/library/3260k4x7.aspx Just specifying the comments will not show the help comments in intellisense.

心如狂蝶 2024-07-20 13:40:02

所有其他答案都有道理,但并不完整。 Visual Studio 将处理 XML 注释,但您必须将其打开。 操作方法如下:

Intellisense 将使用您在源代码中输入的 XML 注释,但您必须通过 Visual Studio 选项启用它们。 转到工具> 选项 > 文本编辑器。 对于 Visual Basic,启用高级 > 为 ''' 设置生成 XML 文档注释。 对于 C#,启用高级 > 为 /// 设置生成 XML 文档注释。 Intellisense 将在输入时使用摘要注释。 编译引用的项目后,它们将从其他项目中可用。

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

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

All these others answers make sense, but are incomplete. Visual Studio will process XML comments but you have to turn them on. Here's how to do that:

Intellisense will use XML comments you enter in your source code, but you must have them enabled through Visual Studio Options. Go to Tools > Options > Text Editor. For Visual Basic, enable the Advanced > Generate XML documentation comments for ''' setting. For C#, enable the Advanced > Generate XML documentation comments for /// setting. Intellisense will use the summary comments when entered. They will be available from other projects after the referenced project is compiled.

To create external documentation, you need to generate an XML file through the Project Settings > Build > XML documentation file: path that controls the compiler's /doc option. You will need an external tool that will take the XML file as input and generate the documentation in your choice of output formats.

Be aware that generating the XML file can noticeably increase your compile time.

不一样的天空 2024-07-20 13:40:02

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

Also the visual studio add-in ghost doc will attempt to create and fill-in the header comments from your function name.

戒ㄋ 2024-07-20 13:40:02

索尔米德给出了正确答案。 有关详细信息,您可以查看XML 注释

Solmead has the correct answer. For more info you can look at XML Comments.

~没有更多了~
我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
原文