How to generate XML documentation and include it in a nuget package

XML documentation comments serve two purposes:

• Intellisense shows the comments to devs using your code.
• You can generate a documentation file and include it in your build and nuget package.

In this article I’ll show how to automatically generate an XML documentation file and how to include it in a nuget package.

1 – Write the XML documentation comments in your code

I have a method called MergeInPlace() (which merges two dictionaries in-place). To explain what this is doing and show an example of how to use it, I added the following XML documentation comments.

/// <summary>
/// Merges two dictionaries together.
/// 
/// <para>
/// Example usage:
/// <c>leftDict.MergeInPlace(rightDict)</c>
/// </para>
/// 
/// <para>
/// If a key exists in both the left and the right dictionary,
/// it'll take the left value.
/// </para>
/// </summary>
/// <typeparam name="Key"></typeparam>
/// <typeparam name="Value"></typeparam>
/// <param name="left">Dictionary to merge into</param>
/// <param name="right">Merges items from this dictionary into left dictionary</param>
/// <returns>Reference to original left dictionary.</returns>
public static Dictionary<Key, Value> MergeInPlace<Key, Value>(this Dictionary<Key, Value> left, 
	Dictionary<Key, Value> right)
Code language: C# (cs)

Note: The compiler checks these XML doc comments and will warn you about problems (such as the parameters being wrong).

Intellisense will now show these comments in the same project and other projects that have a non-package reference to this project.

These comments look like this in Intellisense:

2 – Automatically generate the XML documentation file

Put the following property in your .csproj file (or in a props file):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  </PropertyGroup>
  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
</Project>

Code language: HTML, XML (xml)

Note: If you’re using a non-SDK style .NET Framework project, go into Project Properties > Build > and check the XML Documentation File box.

Now when you build the project, it’ll generate an XML documentation file in the build output directory. This file will have the same name as your assembly. For example, my assembly is called DictionaryUtils.dll. This generated an XML documentation file in the build output directory called DictionaryUtils.xml.

3 – Include the XML documentation file in the nuget package

To make it so people with a package reference see your comments in Intellisense, you’ll need to generate the XML documentation file and include it in the nuget package.

The simplest way to generate a nuget package is to add the GeneratePackageOnBuild property to your .csproj file and set it to true. This is equivalent to running dotnet pack.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  </PropertyGroup>
  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
</Project>

Code language: HTML, XML (xml)

Now when you build, it’ll create a nuget package and include the XML documentation file.

If you’re generating a nuget package and manually specifying files

If you’re using some other method to generate the nuget package, and you’re explicitly specifying all of the files to include, then make sure to include the automatically generated XML file. This will have the same name as your assembly.

For example, if you’re using a nuspec file, it might look like this:

<?xml version="1.0" encoding="utf-8"?>
<package>
...other info...
  <files>
    <file src="bin$configuration$$id$.dll" target="lib\netcoreapp3.1" />
    <file src="bin$configuration$$id$.xml" target="lib\netcoreapp3.1" />
  </files>
</package>
Code language: HTML, XML (xml)

Because the auto-generated XML documentation file has the same name as the assembly, you can use the $id$ token (which resolves to your assembly name).