Skip to content

Commit 2a84d97

Browse files
v-thepetv-thepet
committed
2 articles
1 parent 2e1eb12 commit 2a84d97

5 files changed

+176
-128
lines changed

Diff for: ‎docs/ide/media/code-snippet-description-author.png

-42.3 KB
Loading

Diff for: ‎docs/ide/media/snippet-replacement-parameter-tooltip.png

-13.5 KB
Loading

Diff for: ‎docs/ide/reference/generate-xml-documentation-comments.md

+103-46
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,115 @@
11
---
22
title: Insert XML documentation comments
3-
description: Learn how to insert XML documentation comments in your code that you can use to create a compiler-generated XML file to distribute alongside your .NET assembly.
4-
ms.date: 11/23/2021
5-
ms.topic: reference
3+
description: Learn how to insert XML documentation comments in your code and create a compiler-generated XML comments file to distribute with your .NET assembly.
4+
ms.date: 04/10/2024
5+
ms.topic: how-to
66
author: mikadumont
77
ms.author: midumont
88
manager: mijacobs
99
ms.subservice: general-ide
1010
---
1111
# Insert XML comments for documentation generation
1212

13-
Visual Studio can help you document code elements such as classes and methods, by automatically generating the standard XML documentation comment structure. At compile time, you can generate an XML file that contains the documentation comments. To enable that option, select **Generate a file containing API documentation** on the **Build** > **Output** tab of your project's properties.
13+
This article describes how Visual Studio can help you document code elements such as classes and methods by automatically generating the standard XML documentation comment structure. At compile time, you can generate an XML file that contains the documentation comments.
1414

15-
> [!TIP]
16-
> If you want to configure a non-default name and location for the documentation file, add the [DocumentationFile](/dotnet/core/project-sdk/msbuild-props#documentationfile) property to your *.csproj*, *.vbproj*, or *.fsproj* file.
17-
18-
The compiler-generated XML file can be distributed alongside your .NET assembly so that Visual Studio and other IDEs can use IntelliSense to show quick information about types and members. Additionally, the XML file can be run through tools like [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://www.microsoft.com/download/details.aspx?id=10526) to generate API reference websites.
19-
20-
> [!NOTE]
21-
> The **Insert Comment** command that automatically inserts XML documentation comments is available in [C#](/dotnet/csharp/programming-guide/xmldoc/) and [Visual Basic](/dotnet/visual-basic/programming-guide/program-structure/how-to-create-xml-documentation). However, you can manually insert [XML documentation comments in C++](/cpp/build/reference/xml-documentation-visual-cpp) files and still generate XML documentation files at compile time.
22-
23-
## To insert XML comments for a code element
24-
25-
1. Place your text cursor above the element you want to document, for example, a method.
26-
27-
2. Do one of the following:
28-
29-
- Type `///` in C#, or `'''` in Visual Basic
30-
31-
- From the **Edit** menu, choose **IntelliSense** > **Insert Comment**
32-
33-
- From the right-click or context menu on or just above the code element, choose **Snippet** > **Insert Comment**
34-
35-
The XML template is immediately generated above the code element. For example, when commenting a method, it generates the **\<summary\>** element, a **\<param\>** element for each parameter, and a **\<returns\>** element to document the return value.
36-
37-
![XML comment template - C#](media/doc-preview-cs.png)
38-
39-
![XML comment template - Visual Basic](media/doc-preview-vb.png)
40-
41-
3. Enter descriptions for each XML element to fully document the code element.
42-
43-
![Screenshot showing the completed comment.](media/doc-result-cs.png)
44-
45-
You can use styles in XML comments that will render in Quick Info when hovering over the element. These styles include: italics, bold, bullets, and a clickable link.
46-
47-
![Screenshot showing the completed comment with style tags for italics, bold, bullets, and a clickable link.](media/doc-style-cs.png)
15+
You can distribute the compiler-generated XML file along with your .NET assembly so that Visual Studio and other IDEs can use IntelliSense to show quick information about types and members. You can also run the XML file through tools like [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://www.microsoft.com/download/details.aspx?id=10526) to generate API reference websites.
4816

4917
> [!NOTE]
50-
> There is an [option](../../ide/reference/options-text-editor-csharp-advanced.md) to toggle XML documentation comments after typing `///` in C# or `'''` Visual Basic. From the menu bar, choose **Tools** > **Options** to open the **Options** dialog box. Then, navigate to **Text Editor** > **C#** (or **Visual Basic**) > **Advanced**. In the **Editor Help** section, look for the **Generate XML documentation comments** option.
51-
52-
## See also
53-
54-
- [Documenting your code with XML comments (C# Guide)](/dotnet/csharp/language-reference/xmldoc/)
55-
- [How to: Create XML documentation (Visual Basic)](/dotnet/visual-basic/programming-guide/program-structure/how-to-create-xml-documentation)
56-
- [C++ Comments](/cpp/cpp/comments-cpp)
57-
- [XML Documentation (C++)](/cpp/build/reference/xml-documentation-visual-cpp)
58-
- [Code generation](../code-generation-in-visual-studio.md)
18+
> The **Insert Comment** command to automatically insert XML documentation comment structure is available in [C#](/dotnet/csharp/programming-guide/xmldoc/) and [Visual Basic](/dotnet/visual-basic/programming-guide/program-structure/how-to-create-xml-documentation). For C++, you can [manually insert XML documentation comments](/cpp/build/reference/xml-documentation-visual-cpp) and generate XML documentation files at compile time.
19+
20+
## Enable documentation generation
21+
22+
To enable documentation generation, select **Generate a file containing API documentation** on the **Build** > **Output** tab of your project's properties.
23+
24+
By default, a documentation file named the same as your assembly with an *.xml* file extension is generated in the same directory as the assembly. If you want to configure a non-default name or location for the file, enter or browse to an alternate location under **XML documentation file path**.
25+
26+
Alternatively, you can add the [GenerateDocumentationFile](/dotnet/core/project-sdk/msbuild-props#generatedocumentationfile) or [DocumentationFile](/dotnet/core/project-sdk/msbuild-props#documentationfile) properties to your *.csproj*, *.vbproj*, or *.fsproj* file. Set `GenerateDocumentationFile` to `true` to generate a documentation file with the default name and location. Add the `DocumentationFile` property to specify a different name or location.
27+
28+
If you use `DocumentationFile` by itself or with the `GenerateDocumentationFile` property set to `true`, a documentation file with the specified name and location is generated. However, if you set `GenerateDocumentationFile` to `false`, no documentation file is generated even if you set the `DocumentationFile` property.
29+
30+
## Enable comment insertion keyboard shortcut
31+
32+
You can set the [Comments](options-text-editor-csharp-advanced.md#comments) option to automatically insert XML comment structures after you type `///` in C# or `'''` in Visual Basic.
33+
34+
1. From the Visual Studio menu bar, choose **Tools** > **Options**.
35+
1. In the **Options** dialog box, navigate to **Text Editor** > **C#** (or **Visual Basic**) > **Advanced**.
36+
1. Under the **Comments** section, select or deselect **Generate XML documentation comments for \\\\\\** (or **'''**).
37+
38+
## Automatically insert an XML comment structure
39+
40+
1. In Visual Studio, place your cursor above the element you want to document, for example a method.
41+
42+
1. Take one of the following actions:
43+
44+
- If the automatic comment insertion shortcut is enabled, type `///` in C#, or `'''` in Visual Basic.
45+
- From the **Edit** menu, choose **IntelliSense** > **Insert Comment**.
46+
- From the right-click or context menu, choose **Snippet** > **Insert Comment**.
47+
48+
The XML comment structure is immediately generated above the code element. For example, when commenting a method, the template generates the `<summary>` element, a `<param>` element for each parameter, and a `<returns>` element to document the return value.
49+
50+
```csharp
51+
/// <summary>
52+
///
53+
/// </summary>
54+
/// <param name="id"></param>
55+
/// <returns></returns>
56+
public string GetUserName(int id)
57+
{
58+
return "username";
59+
}
60+
```
61+
62+
```vb
63+
''' <summary>
64+
'''
65+
''' </summary>
66+
''' <param name="id"></param>
67+
''' <returns></returns>
68+
Public Function GetUserName(id As Integer) As String
69+
Return "username"
70+
End Function
71+
```
72+
73+
1. Enter descriptions for each XML element to fully document the code element. For example:
74+
75+
```csharp
76+
/// <summary>
77+
/// Gets the username associated with the specified ID.
78+
/// </summary>
79+
/// <param name="id">The unique user ID.</param>
80+
/// <returns>A string containing the username for the specified ID.</returns>
81+
public string GetUserName(int id)
82+
{
83+
return "username";
84+
}
85+
```
86+
You can use styles in XML comments that render in Quick Info when you hover over the element. These styles include italics, bold, bulleted or numbered lists, and clickable `cref` or `href` links.
87+
88+
For example, enter the following code in Visual Studio:
89+
90+
```csharp
91+
/// <summary>
92+
/// There are two <see href="https://bing.com">params</see>.
93+
/// <list type="number">
94+
/// <item><param name="id">The user <em>id</em></param></item>
95+
/// <item><param name="username">The user <em>name</em></param></item>
96+
/// </list>
97+
/// </summary>
98+
/// <returns>The <strong>username</strong>.</returns>
99+
public static string GetUserName(int id)
100+
{
101+
return "username";
102+
}
103+
```
104+
105+
When you hover over **GetUserName**, the following formatting appears in the Quick Info pane:
106+
107+
![Screenshot showing the completed comment with style tags for a clickable link, a numbered list with italics, and bold formatting.](media/doc-style-cs.png)
108+
109+
## Related content
110+
111+
- [Documentation comments](/dotnet/csharp/language-reference/xmldoc/)
112+
- [How to: Create XML documentation in Visual Basic](/dotnet/visual-basic/programming-guide/program-structure/how-to-create-xml-documentation)
113+
- [Comments (C++)](/cpp/cpp/comments-cpp)
114+
- [XML Documentation (Visual C++)](/cpp/build/reference/xml-documentation-visual-cpp)
115+
- [Generate, fix, or refactor code](writing-code-in-the-code-and-text-editor.md#generate-fix-or-refactor-code)

Diff for: ‎docs/ide/reference/media/doc-style-cs.png

33.8 KB
Loading

0 commit comments

Comments
 (0)