# Dotnet XML Docs > Writing XML doc comments. Tags, inheritdoc, GenerateDocumentationFile, warning suppression. - Skill: `wshaddix/dotnet-xml-docs` (Agent Skill) - Install (CLI): `npx skillmds add wshaddix/dotnet-xml-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/wshaddix/dotnet-xml-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: wshaddix (https://skillmd.com/u/wshaddix) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/wshaddix/dotnet-xml-docs --- # dotnet-xml-docs XML documentation comments for .NET: all standard tags (`
`, ``, ``, ``, ``, ``, ``, ``, ``, ``), advanced tags (`` for interface and base class inheritance, ``, ``, `` and `
`), enabling XML doc generation with `` MSBuild property, warning suppression strategies for internal APIs (`CS1591`, ``, `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. `` MSBuild property works with .NET SDK 6+. `` 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


  true

```

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

  $(NoWarn);CS1591

```

**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

  true
  
  $(WarningsAsErrors);CS1591

```

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

---

## Standard XML Doc Tags

### ``

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

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

### ``

Documents a method parameter.

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

### ``

Documents the return value.

```csharp
/// 
/// Finds a widget by its unique identifier.
/// 
/// The unique identifier of the widget.
/// 
/// The widget if found; otherwise, .
/// 
public async Task FindByIdAsync(Guid id)
{
}
```

### ``

Documents exceptions that may be thrown.

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

### ``

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

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

### ``

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

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

### ``

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

```csharp
/// 
/// Gets the current status of the widget.
/// 
/// 
/// The widget status. Defaults to  for new widgets.
/// 
public WidgetStatus Status { get; private set; }
```

### ``

Documents a generic type parameter.

```csharp
/// 
/// A repository that provides CRUD operations for entities.
/// 
/// 
/// The entity type. Must implement  and have a parameterless constructor.
/// 
/// 
/// The type of the entity's primary key. Typically  or .
/// 
public interface IRepository
    where TEntity : class, IEntity
    where TKey : struct
{
}
```

---

## Advanced Tags

### ``

Inherits documentation from a base class or interface. Eliminates duplication when implementing interfaces or overriding virtual members.

**Interface implementation:**

```csharp
public interface IWidgetService
{
    /// 
    /// Creates a new widget with the specified name.
    /// 
    /// The display name for the widget.
    /// The created widget.
    Task CreateWidgetAsync(string name);
}

public class WidgetService : IWidgetService
{
    /// 
    public async Task CreateWidgetAsync(string name)
    {
        // Implementation inherits all documentation from the interface
    }
}
```

**Base class override:**

```csharp
public abstract class RepositoryBase
{
    /// 
    /// Retrieves an entity by its unique identifier.
    /// 
    /// The entity identifier.
    /// The entity if found; otherwise, .
    public abstract Task GetByIdAsync(Guid id);
}

public class OrderRepository : RepositoryBase
{
    /// 
    public override async Task GetByIdAsync(Guid id)
    {
        // Inherits summary, param, and returns docs from base class
    }
}
```

**Selective inheritance with `cref`:**

```csharp
/// 
/// 
/// This implementation validates the name and assigns a default category
/// before persisting to the database.
/// 
public async Task CreateWidgetAsync(string name)
{
}
```

**Inheritance with path filter:**

```csharp
/// 
/// Custom param doc that overrides the interface.
public async Task CreateWidgetAsync(string name)
{
}
```

### `` and ``

Create inline references and "See Also" links.

```csharp
/// 
/// Validates the widget against the rules defined in .
/// Use  to create validated widgets.
/// 
/// 
/// 
/// Validation Guide
public ValidationResult Validate(Widget widget)
{
}
```

**`` variants:**

```csharp
/// 
/// Returns  if the widget is active,
///  otherwise.
/// Use  to change the state.
/// The value is stored as a .
/// 
public bool IsActive { get; }
```

### `` and ``

Format inline code and code blocks within documentation.

```csharp
/// 
/// Parses a widget name from the format "category:name".
/// 
/// 
/// The expected input format:
/// 
/// "analytics:page-views"    // category = "analytics", name = "page-views"
/// "default:my-widget"       // category = "default", name = "my-widget"
/// "my-widget"               // category = null, name = "my-widget" (no colon)
/// 
/// 
public (string? Category, string Name) ParseWidgetName(string input)
{
}
```

### `` and ``

Reference parameters and type parameters within documentation text.

```csharp
/// 
/// Converts  to a DTO of type .
/// If  is , returns the default value
/// of .
/// 
/// The target DTO type.
/// The source entity to convert.
public TDto? ToDto(object? entity)
{
}
```

### ``

Create bulleted, numbered, or table lists within documentation.

```csharp
/// 
/// Applies the specified transformation to the widget.
/// 
/// 
/// Supported transformations:
/// 
/// Resize -- changes the widget dimensions
/// Recolor -- applies a new color scheme
/// Reposition -- moves the widget to new coordinates
/// 
/// 
public void ApplyTransformation(Widget widget, Transformation transform)
{
}
```

---

## Comprehensive XML Doc Example

A complete class demonstrating all tag types working together:

```csharp
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace MyLibrary;

/// 
/// Manages the lifecycle of widgets including creation, retrieval, update, and deletion.
/// All operations are thread-safe and support cancellation via .
/// 
/// 
/// 
///  requires a registered 
/// and  via dependency injection.
/// 
/// 
/// Widget names must be unique within a category. Attempting to create a widget with a
/// duplicate name in the same category throws .
/// 
/// 
/// 
/// Register and use the service:
/// 
/// // Registration
/// builder.Services.AddScoped<IWidgetService, WidgetService>();
///
/// // Usage
/// var widget = await widgetService.CreateWidgetAsync(
///     "My Widget",
///     category: "Dashboard");
/// 
/// 
/// 
/// 
public class WidgetService : IWidgetService
{
    private readonly IWidgetRepository _repository;
    private readonly ILogger _logger;

    /// 
    /// Initializes a new instance of .
    /// 
    /// The widget data repository.
    /// The logger for diagnostic output.
    /// 
    /// Thrown when  or  is
    /// .
    /// 
    public WidgetService(IWidgetRepository repository, ILogger logger)
    {
        _repository = repository ?? throw new ArgumentNullException(nameof(repository));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    /// 
    /// Gets the total number of widgets in the system.
    /// 
    /// A non-negative integer representing the total widget count.
    public int TotalCount => _repository.Count;

    /// 
    public async Task CreateWidgetAsync(
        string name,
        string? category = null,
        CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(name);

        _logger.LogInformation("Creating widget {Name} in category {Category}", name, category);

        var widget = new Widget
        {
            Id = Guid.NewGuid(),
            Name = name,
            Category = category ?? "default",
            CreatedAt = DateTimeOffset.UtcNow,
            Status = WidgetStatus.Draft
        };

        await _repository.AddAsync(widget, cancellationToken);
        return widget;
    }

    /// 
    /// Retrieves all widgets matching the specified filter criteria.
    /// 
    /// 
    /// The filter to apply. Use  for unfiltered results.
    /// 
    /// A token to cancel the operation.
    /// 
    /// A read-only list of widgets matching the filter. Returns an empty list if no
    /// widgets match the criteria.
    /// 
    /// 
    /// Thrown when  is .
    /// 
    public async Task> ListAsync(
        WidgetFilter filter,
        CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(filter);
        return await _repository.FindAsync(filter, cancellationToken);
    }
}
```

---

## XML Doc Conventions for Public Libraries

### Documentation Requirements

For NuGet packages consumed by other developers, follow these conventions:

1. **Every public type must have a ``** -- this is the minimum for IntelliSense to display useful information
2. **Every public method parameter must have a ``** -- describe what the parameter controls, valid ranges, and null behavior
3. **Every method that can throw must document exceptions with ``** -- callers need to know what to catch
4. **Return values must have ``** -- describe the return value semantics, especially for nullable returns
5. **Properties should have ``** -- describe what the property represents and its default value
6. **Generic type parameters must have ``** -- describe constraints and expected usage
7. **Complex APIs should include ``** -- show real usage, not trivial one-liners
8. **Use `` for caveats and threading behavior** -- important context that does not belong in the summary

### Writing Style

- Use third person declarative: "Gets the widget name" not "Get the widget name" or "This gets the widget name"
- Start `` with a verb: "Creates...", "Retrieves...", "Validates...", "Computes..."
- Avoid restating the obvious: do not write "Gets the Name property" for a property called `Name`
- Document behavior, not implementation: "Returns the cached value if available" not "Checks the dictionary and returns the value"
- Use `` for all type and member references -- enables IDE navigation and refactoring support
- Use ``, ``, `` instead of bare `null`, `true`, `false`

### CancellationToken Convention

Standardize documentation for `CancellationToken` parameters:

```csharp
/// A token to cancel the asynchronous operation.
```

This one-line description is sufficient for the standard `CancellationToken cancellationToken = default` pattern. Do not over-document what cancellation means -- callers understand the pattern.

---

## Auto-Generation Tooling

### IDE Quick-Fix Generation

All major .NET IDEs generate XML doc skeletons when you type `///` above a member:

**Visual Studio / VS Code (C# Dev Kit):**
- Type `///` above a method, class, or property
- The IDE generates a `` skeleton with ``, ``, `` tags pre-filled based on the member's signature

**JetBrains Rider:**
- Type `///` to trigger the same skeleton generation
- Rider additionally warns about missing XML docs and offers quick-fixes to add them

### GhostDoc-Style Patterns

GhostDoc and similar tools generate documentation text from member names using naming convention heuristics:

- `GetWidgetById` generates "Gets the widget by identifier"
- `IsActive` generates "Gets a value indicating whether this instance is active"
- `CreateWidgetAsync` generates "Creates the widget asynchronously"

These auto-generated descriptions are a starting point. Always review and improve generated text to add domain-specific context, parameter constraints, exception conditions, and examples.

### EditorConfig Integration

Enforce XML documentation requirements through `.editorconfig`:

```ini
# .editorconfig
[*.cs]
# Require XML documentation for public members
dotnet_diagnostic.CS1591.severity = warning

# For public libraries, treat as error:
# dotnet_diagnostic.CS1591.severity = error
```

---

## IntelliSense Integration

### How XML Docs Surface in IDEs

XML documentation comments are the primary source of IntelliSense tooltips:

- **Hover tooltips:** Display `` text when hovering over a type or member
- **Parameter hints:** Display `` text in the parameter info popup during method calls
- **Completion list:** Display `` in the autocomplete dropdown
- **Quick Info:** Display ``, ``, and `` in expanded documentation panels
- **Signature help:** Display parameter names and types with `` descriptions

### NuGet Package IntelliSense

When `` is enabled and the package is published to NuGet, the XML file is included in the package. Consumers get full IntelliSense support without needing source access:

```xml


  true
  

```

No additional NuGet packaging configuration is needed -- `dotnet pack` includes the XML doc file automatically when `GenerateDocumentationFile` is `true`.

### Source Link Integration

Combine XML docs with Source Link for the best developer experience:

```xml

  true
  
  true
  true
  true
  snupkg

```

With both XML docs and Source Link enabled, consumers can hover for documentation and navigate to the original source code.

---

## Agent Gotchas

1. **Always enable `` for public libraries** -- without it, NuGet consumers get no IntelliSense documentation. Add it to `Directory.Build.props` to apply across all projects in a solution.

2. **Use `` for interface implementations and overrides** -- do not duplicate documentation text between an interface and its implementation. Duplication causes maintenance drift.

3. **Do not suppress CS1591 globally for public NuGet packages** -- global suppression via `CS1591` hides all missing documentation warnings. Use per-file `#pragma` suppression for intentionally undocumented types, or make internal types truly `internal`.

4. **Use `` for all type references, not bare type names** -- `` enables IDE navigation and is validated at build time. Bare text "Widget" is not linked and can become stale if the type is renamed.

5. **Use `` instead of bare `null` in documentation text** -- this renders with proper formatting in IntelliSense and API doc sites. Same applies to `true`, `false`, and other C# keywords.

6. **`` resolves at build time, not design time** -- some older IDE versions may show "Documentation not found" for `` in tooltips. The documentation is correctly resolved in the generated XML file and in API doc sites.

7. **XML doc comments must use `<` and `>` for generic type syntax in prose** -- but `` handles generics automatically. Use `` (curly braces), not ``.

8. **In `` blocks, use `<` and `>` for angle brackets** -- XML doc comments are XML, so `<` and `>` in code examples must be escaped. Alternatively, use `` to avoid escaping.

9. **Do not generate API documentation sites from XML comments** -- API doc site generation (DocFX, OpenAPI-as-docs) belongs to [skill:dotnet-api-docs]. This skill covers the XML comment authoring side only.

10. **Document cancellation tokens with a single standard line** -- use "A token to cancel the asynchronous operation." for all `CancellationToken` parameters. Do not over-document the cancellation pattern.