How to have comments in IntelliSense for function in Visual Studio?

Question

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

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

Solution 1

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.

Solution 2

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

Solution 3

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

Solution 4

Do XML commenting , like this

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

Solution 5

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.

View more solutions

Comments

[abelenky]

To emphasize: That is triple-slash in C++/C# (normal comments are double-slash). And in VB, its two single-quotes, not a double-quote.

[Joel Coehoorn]

It's actually three single quotes in vb

[hometoast]

Actually, in VB, it's 3 single quotes: '''

[Joel Coehoorn]

they're good for shortcuts reminders, or anywhere you have library code where maybe the code is readable but it takes a little extra work to get to it.

[DevelopingChris]

I agree with you in theory, but if you use that ghostdoc thing, then you are raising the noise/signal ratio to such an extent that the rest of the comments are useless.

[user1069816]

As an alternative, in a VB file you can right click on a function or class and click "Insert Comment". For C# you can use StyleCop which will prompt you to write good documentation headers

[The Oddler]

For parameters add: ///<param name="paramName">Tralala</param>

[Karl Gjertsen]

GhostDoc is a great tool that can add a lot of the text in the comments for you. submain.com/products/ghostdoc.aspx

[Karl Gjertsen]

If you have the code in a dll, you might also want to turn on the XML Output. In the project settings, on the build tab is an output section. Check the 'XML document file' checkbox.

[Suncat2000]

They will if you have XML comments enabled. See my answer below.

[Eric D. Johnson]

This Document your code with XML comments Walkthrough is also very helpful.