Generating XML Documentation and Including It in a NuGet Package in C#

1. Intellisense: They provide helpful comments to developers when using your code.
2. Documentation File: They allow you to generate an XML documentation file that can be included in your build and NuGet package.

This guide shows how to automatically generate an XML documentation file and include it in a NuGet package.

1. Write XML Documentation Comments in Your Code

For instance, if you have a method called MergeInPlace() that merges two dictionaries in-place, you can add XML documentation comments like this:

/// <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,
/// the left value will be retained.
/// </para>
/// </summary>
/// <typeparam name="Key"></typeparam>
/// <typeparam name="Value"></typeparam>
/// <param name="left">Dictionary to merge into</param>
/// <param name="right">Dictionary from which to merge items into the left dictionary</param>
/// <returns>Reference to the original left dictionary.</returns>
public static Dictionary<Key, Value> MergeInPlace<Key, Value>(this Dictionary<Key, Value> left, 
    Dictionary<Key, Value> right)

Note: The compiler will check these XML doc comments and warn you about issues, such as incorrect parameters.

With these comments, Intellisense will display the documentation in both your current project and any other project that references your assembly (non-package references). The comments will appear like this in Intellisense:

Example in Intellisense showing XML documentation comments for the MergeInPlace() method.

2. Automatically Generate the XML Documentation File

To generate the XML documentation file automatically, add the following properties to your .csproj file:

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

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

After building your project, an XML documentation file will be generated in the build output directory. This file will have the same name as your assembly (e.g., if your assembly is DictionaryUtils.dll, the file will be DictionaryUtils.xml).

3. Include the XML Documentation File in the NuGet Package

To ensure that users with a package reference can see your comments in Intellisense, you need to include the XML documentation file in the NuGet package.

The easiest way to do this is by setting the GeneratePackageOnBuild property in your .csproj file, as shown:

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

This will ensure that, when you build your project, both the NuGet package and the XML documentation file are generated and included.

If you are manually specifying the files to include in your NuGet package (e.g., using a .nuspec file), make sure to include the automatically generated XML documentation file. This file will have the same name as your assembly.

Example of a .nuspec file:

<?xml version="1.0" encoding="utf-8"?>
<package>
  <!-- Other package info -->
  <files>
    <file src="bin\$configuration$\$id$.dll" target="lib\netcoreapp3.1" />
    <file src="bin\$configuration$\$id$.xml" target="lib\netcoreapp3.1" />
  </files>
</package>

Since the auto-generated XML file shares the same name as the assembly, you can use the $id$ token, which resolves to your assembly name.