Skip to content

Latest commit

 

History

History
62 lines (41 loc) · 4.02 KB

generate-xml-documentation-comments.md

File metadata and controls

62 lines (41 loc) · 4.02 KB
title description ms.date ms.topic author ms.author manager ms.technology ms.workload
Insert XML documentation comments
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.
11/23/2021
reference
mikadumont
midumont
jmartens
vs-ide-general
dotnet

How to: Insert XML comments for documentation generation

[!INCLUDE Visual Studio]

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.

Tip

If you want to configure a non-default name and location for the documentation file, add the DocumentationFile property to your .csproj, .vbproj, or .fsproj file.

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 and Sandcastle to generate API reference websites.

Note

The Insert Comment command that automatically inserts XML documentation comments is available in C# and Visual Basic. However, you can manually insert XML documentation comments in C++ files and still generate XML documentation files at compile time.

To insert XML comments for a code element

  1. Place your text cursor above the element you want to document, for example, a method.

  2. Do one of the following:

    • Type /// in C#, or ''' in Visual Basic

    • From the Edit menu, choose IntelliSense > Insert Comment

    • From the right-click or context menu on or just above the code element, choose Snippet > Insert Comment

    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.

    XML comment template - C#

    XML comment template - Visual Basic

  3. Enter descriptions for each XML element to fully document the code element.

    Screenshot showing the completed comment.

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.

Screenshot showing the completed comment with style tags for italics, bold, bullets, and a clickable link.

Note

There is an option 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.

See also