# Dotnet XML Docs > Use when writing, reviewing, or generating XML documentation comments (///) for C# or .NET code. Trigger on: "add XML docs", "document this class", "write doc comments", "add IntelliSense comments", "document the API", "add triple-slash comments", "add summary comments", or any request involving /// documentation in C#/.NET. Also trigger proactively when the user asks to review or complete a public API surface that lacks documentation. - Skill: `jzills/dotnet-xml-docs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add jzills/dotnet-xml-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/jzills/dotnet-xml-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: jzills (https://skillmd.com/u/jzills) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jzills/dotnet-xml-docs --- # .NET XML Documentation Writer You are writing production-quality XML documentation comments for C# public APIs. Documentation should be accurate, concise, and useful in IntelliSense — not verbose padding. For the complete tag specification and attribute reference, see @xml-doc-reference.md. --- ## Tag Quick Reference | Tag | Applied to | Purpose | |-----|-----------|---------| | `

` | Any member | One-sentence description (required for all public members) | | `` | Any member | Supplemental detail beyond the summary | | `` | Methods, constructors | Documents a single parameter | | `` | Methods | Describes the return value | | `` | Methods, properties | Documents a thrown exception | | `` | Generic types/methods | Documents a type parameter | | `` | Properties | Describes what the property represents | | `` | Any member | Usage example, typically contains `

` |
| `` | Inline | Inline cross-reference to another member or URL |
| `` | Top-level | Generates a "See Also" section |
| `` | Overrides/implementations | Inherits docs from base or interface |
| `` | Inside other tags | Double-spaced paragraph break |
| `` | Inline | Inline monospace code |
| `` | Block | Multi-line code block |
| `` | Block | Bulleted, numbered, or table list |
| `
` | Inline | Single-spaced line break |

---

## Core Patterns

### Type and method documentation

```csharp
/// 
/// Processes a payment and returns the resulting transaction.
/// 
/// 
/// Retries up to three times on transient failures before throwing.
/// 
/// The payment details to process.
/// A  representing the completed payment.
/// Thrown when the payment is declined.
/// Thrown when  is .
public Transaction ProcessPayment(PaymentRequest request)
```

### Generic types and methods

```csharp
/// 
/// A thread-safe pool of reusable  instances.
/// 
/// The type of object to pool. Must be a class with a parameterless constructor.
public class ObjectPool where T : class, new()
```

### Properties

```csharp
/// 
/// Gets or sets the maximum number of concurrent connections.
/// 
/// The connection limit. Defaults to 100.
public int MaxConnections { get; set; }
```

### Inheriting from interface or base class

```csharp
/// 
public override string ToString()

// Or inherit from a specific member:
/// 
public void Dispose()
```

### Cross-references

```csharp
// Code member reference (compiler-verified):
/// See  for the synchronous version.

// Language keyword:
/// Returns  if the user is not found.

// External URL:
/// See C# Guide for background.

// "See Also" section:
/// 
/// 
```

### Usage examples

```csharp
/// 
/// 
/// var pool = new ObjectPool<Connection>();
/// var conn = pool.Rent();
/// try { /* use conn */ }
/// finally { pool.Return(conn); }
/// 
/// 
```

### Lists inside remarks

```csharp
/// 
/// Supported modes:
/// 
///   FastLow latency, higher memory usage.
///   BalancedDefault mode for most workloads.
///   EfficientLower memory, higher latency.
/// 
/// 
```

---

## Rules

- Write `` as a complete sentence ending with a period.
- Document every public parameter, return value, and thrown exception.
- Use `cref` for code references — the compiler validates them. Use `href` for external URLs.
- Prefer `List{T}` brace syntax over `List<T>` in cref attributes — it's less noisy.
- Don't write `` just to repeat the summary. Only add it when there's genuinely more to say.
- Don't document obvious things: `The value.` adds nothing.
- Keep `` to one sentence. Move longer explanations to ``.

---

## Output Format

When documenting a class:

1. **Read the class** — understand every public member, its parameters, return types, and generic constraints.
2. **Identify what needs docs** — all public types, methods, properties, events, and constructors.
3. **Write complete, compilable comments** — no `TODO` placeholders, no orphaned tags.
4. **Verify cref targets exist** — don't reference types or members that aren't in scope.

Output the fully documented file unless the user asks for isolated snippets.