dotnet-xml-docs

What this skill does

# dotnet-xml-docs

XML documentation comments for .NET: all standard tags (`<summary>`, `<param>`, `<returns>`, `<exception>`, `<remarks>`, `<example>`, `<value>`, `<typeparam>`, `<typeparamref>`, `<paramref>`), advanced tags (`<inheritdoc>` for interface and base class inheritance, `<see cref="..."/>`, `<seealso>`, `<c>` and `<code>`), enabling XML doc generation with `<GenerateDocumentationFile>` MSBuild property, warning suppression strategies for internal APIs (`CS1591`, `<NoWarn>`, `InternalsVisibleTo`), XML doc conventions for public NuGet libraries, auto-generation tooling (IDE quick-fix `///` trigger, GhostDoc-style patterns), and IntelliSense integration showing XML docs in IDE tooltips and autocomplete.

**Version assumptions:** .NET 8.0+ baseline. XML documentation comments are a C# language feature available in all .NET versions. `<GenerateDocumentationFile>` MSBuild property works with .NET SDK 6+. `<inheritdoc>` fully supported since C# 9.0 / .NET 5+.

**Scope boundary:** This skill owns XML documentation comment authoring -- the syntax, conventions, and MSBuild configuration for generating XML doc files. API documentation site generation from XML comments (DocFX, Starlight) is owned by [skill:dotnet-api-docs]. General C# coding conventions (naming, formatting) are owned by [skill:dotnet-csharp-coding-standards].

**Out of scope:** API documentation site generation from XML comments (DocFX setup, OpenAPI-as-docs, doc-code sync) -- see [skill:dotnet-api-docs]. General C# coding conventions and naming standards -- see [skill:dotnet-csharp-coding-standards]. CI/CD deployment of documentation sites -- see [skill:dotnet-gha-deploy].

Cross-references: [skill:dotnet-api-docs] for downstream API documentation generation from XML comments, [skill:dotnet-csharp-coding-standards] for general C# coding conventions, [skill:dotnet-gha-deploy] for doc site deployment.

---

## Enabling XML Documentation Generation

### MSBuild Configuration

Enable XML documentation file generation in the project or `Directory.Build.props`:

```xml
<!-- In .csproj or Directory.Build.props -->
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
```

This generates a `.xml` file alongside the assembly during build (e.g., `MyLibrary.xml` next to `MyLibrary.dll`). NuGet pack automatically includes this XML file in the package, enabling IntelliSense for package consumers.

### Warning Suppression for Internal APIs

When `GenerateDocumentationFile` is enabled, the compiler emits CS1591 warnings for all public members missing XML doc comments. Suppress warnings selectively for internal-facing code:

**Option 1: Suppress globally for the entire project (not recommended for public libraries):**

```xml
<PropertyGroup>
  <NoWarn>$(NoWarn);CS1591</NoWarn>
</PropertyGroup>
```

**Option 2: Suppress per-file with pragma directives (recommended for mixed-visibility assemblies):**

```csharp
#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
public class InternalServiceHelper
{
    // This type is internal-facing despite being public
    // (e.g., exposed for testing via InternalsVisibleTo)
}
#pragma warning restore CS1591
```

**Option 3: Use `InternalsVisibleTo` and keep internal types truly internal:**

```csharp
// In AssemblyInfo.cs or a Properties file
[assembly: InternalsVisibleTo("MyLibrary.Tests")]
```

```csharp
// Mark internal-facing types as internal instead of public
internal class ServiceHelper
{
    // No CS1591 warning -- internal types are not documented
}
```

**Option 4: Treat missing docs as errors for public libraries (strictest):**

```xml
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <!-- Treat missing XML docs as build errors -->
  <WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors>
</PropertyGroup>
```

This forces documentation for every public member. Use this for NuGet packages where consumers depend on IntelliSense documentation.

---

## Standard XML Doc Tags

### `<summary>`

Describes the type or member. This is the primary tag that appears in IntelliSense tooltips.

```csharp
/// <summary>
/// Provides methods for managing widgets in the system.
/// Widget operations are thread-safe and support cancellation.
/// </summary>
public class WidgetService
{
}
```

### `<param>`

Documents a method parameter.

```csharp
/// <summary>
/// Creates a new widget with the specified name and optional category.
/// </summary>
/// <param name="name">The display name for the widget. Must not be null or whitespace.</param>
/// <param name="category">
/// The category to assign. When <see langword="null"/>, the default category is used.
/// </param>
/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
public async Task<Widget> CreateWidgetAsync(
    string name,
    string? category = null,
    CancellationToken cancellationToken = default)
{
}
```

### `<returns>`

Documents the return value.

```csharp
/// <summary>
/// Finds a widget by its unique identifier.
/// </summary>
/// <param name="id">The unique identifier of the widget.</param>
/// <returns>
/// The widget if found; otherwise, <see langword="null"/>.
/// </returns>
public async Task<Widget?> FindByIdAsync(Guid id)
{
}
```

### `<exception>`

Documents exceptions that may be thrown.

```csharp
/// <summary>
/// Updates the widget's name.
/// </summary>
/// <param name="id">The widget identifier.</param>
/// <param name="newName">The new name to assign.</param>
/// <exception cref="ArgumentException">
/// Thrown when <paramref name="newName"/> is null or whitespace.
/// </exception>
/// <exception cref="KeyNotFoundException">
/// Thrown when no widget with the specified <paramref name="id"/> exists.
/// </exception>
/// <exception cref="InvalidOperationException">
/// Thrown when the widget is in a read-only state and cannot be modified.
/// </exception>
public async Task UpdateNameAsync(Guid id, string newName)
{
}
```

### `<remarks>`

Provides additional context beyond the summary. Use for implementation notes, usage guidance, and caveats.

```csharp
/// <summary>
/// Computes the hash of the widget's content for change detection.
/// </summary>
/// <remarks>
/// <para>
/// The hash is computed using SHA-256 over the UTF-8 encoded content.
/// Results are deterministic across platforms and .NET versions.
/// </para>
/// <para>
/// This method is thread-safe. The returned hash is a lowercase hex string
/// without any prefix (e.g., "a1b2c3..." not "0xa1b2c3...").
/// </para>
/// </remarks>
/// <returns>A 64-character lowercase hexadecimal hash string.</returns>
public string ComputeContentHash()
{
}
```

### `<example>`

Provides a code example demonstrating usage. Essential for public library APIs.

```csharp
/// <summary>
/// Creates a new widget and persists it to the repository.
/// </summary>
/// <example>
/// <code>
/// var service = new WidgetService(repository, logger);
///
/// var widget = await service.CreateWidgetAsync(
///     "Dashboard Widget",
///     category: "Analytics",
///     cancellationToken: ct);
///
/// Console.WriteLine($"Created widget: {widget.Id}");
/// </code>
/// </example>
public async Task<Widget> CreateWidgetAsync(
    string name,
    string? category = null,
    CancellationToken cancellationToken = default)
{
}
```

### `<value>`

Documents a property's value. Similar to `<returns>` but for properties.

```csharp
/// <summary>
/// Gets the current status of the widget.
/// </summary>
/// <value>
/// The widget status. Defaults to <see cref="WidgetStatus.Draft"/> for new widgets.
/// </value>
public WidgetStatus Status { get; private set; }
```

### `<typeparam>`

Documents a generic type parameter.

```csharp
/// <summary>
/// A repository that provides CRUD operations for entities.
/// </summary>
/// <typeparam name="TEntity">
/// The entity type. Must implement <see cref="IEntity"/> and have a param