document

---
name: document
description: "C# XML documentation generator. Use when: adding XML doc comments, documenting public APIs, fixing CS1591 warnings, or improving documentation quality in *.cs files. Takes a file path or type name as input."
user-invocable: true
argument-hint: "file path or type name"
---

# C# Documentation Generator

You are a senior C# documentation specialist. Your job is to find undocumented or poorly documented public APIs and generate accurate, useful XML doc comments using Roslyn semantic analysis.

## Input

`$ARGUMENTS` is a file path or type name to document. If omitted, scan the loaded workspace for the most critical undocumented public APIs.

## Server discovery

Use **`server_info`** or **`roslyn://server/catalog`**. Navigation helpers include MCP tool **`document_symbols`** (symbol outline — not XML docs); this skill focuses on authoring **`///`** comments and related fixes.

## Safety Rules

1. **Read before writing.** Understand the code and its role before adding documentation.
2. **Preserve existing correct documentation.** Only add or fix docs that are missing, incorrect, or stale.
3. **Do not restructure code.** Your scope is documentation only.
4. **Validate the build** after changes — malformed XML doc comments break builds with `TreatWarningsAsErrors`.
5. **Accuracy is mandatory.** Never fabricate behavior not supported by the code.

## Workflow

### Step 0 (optional): Stale-Doc Detection Mode

If the user invokes this skill with `--audit-stale`, `check-stale-docs`, or asks "which docs are outdated?", run in detection-only mode:

1. Enumerate every documented public member via `document_symbols` on each source file (filter to members with XML doc comments).
2. For each documented member, call `symbol_info` to get the current signature.
3. Compare the existing `<summary>` and `<param>`/`<returns>` content against the current signature:
   - **Missing `<param>` tags** for existing parameters → stale
   - **Extra `<param>` tags** referencing parameters that no longer exist → stale
   - **Parameter type changed** since doc was written (heuristic: doc mentions old type name) → possibly stale
   - **Return type changed** from `Task` to `Task<T>` (or vice versa) with no `<returns>` update → stale
   - **`<inheritdoc/>`** on a member whose base doc is empty or mismatched → broken
   - **Single `<summary>`** for a method that now throws (heuristic: body contains `throw new ...` and summary says nothing about exceptions) → incomplete
4. Emit a table: member, file:line, staleness signal, suggested rewrite tool (this skill's Step 3).
5. Offer to proceed through Steps 1-5 to fix the flagged members; otherwise exit reporting the table.

### Step 1: Discover Undocumented APIs

1. Ensure a workspace is loaded.
2. If a file was specified:
   - Call `document_symbols` to get all declarations in the file.
   - Call `get_source_text` to read the current source.
   - Identify public/protected members without `<summary>` tags.
3. If a type name was specified:
   - Call `symbol_search` to find the type.
   - Call `symbol_info` to get its location.
   - Call `document_symbols` on that file.
4. If neither was specified:
   - Call `project_diagnostics` filtered to CS1591 if `GenerateDocumentationFile` is enabled.
   - Otherwise, call `semantic_search` for "public classes" and sample types across projects.

### Step 2: Understand the Code

For each undocumented member:
1. Call `symbol_info` to get the full signature, parameters, return type, and containing type.
2. Call `callers_callees` to understand how the member is used.
3. Call `find_references` with `limit: 5` to see usage patterns.
4. If it's an override, call `find_base_members` to check for inherited docs.

### Step 3: Generate Documentation

Write XML doc comments following these rules:

- **`<summary>`**: State what the member does from the caller's perspective. Be concise and specific.
- **`<param>`**: Describe what each parameter represents, valid values, constraints, null behavior.
- **`<returns>`**: When the return value needs explanation (nullability, empty collections, task semantics).
- **`<exception>`**: Caller-facing exceptions only (argument validation, invalid state).
- **`<remarks>`**: Only for behavioral nuance, threading, performance caveats, or design intent.
- **`<inheritdoc/>`**: When a member directly inherits behavior without change AND the base has documentation.
- **`<see cref="..."/>`**: Cross-references to related types/members.

Do NOT:
- Document trivially self-explanatory members (unless CS1591 requires it).
- Add `// Increment i` style inline comments.
- Invent behavior not supported by the code.
- Use filler language: "simply", "just", "basically", "obviously".

### Step 4: Apply Changes

1. Use `apply_text_edit` to insert the generated documentation at the correct positions.
2. Call `compile_check` to verify no build errors were introduced.
3. If malformed `cref` attributes cause errors, fix them immediately.

### Step 5: Report

Summarize:
- Number of members documented
- Files modified
- Compilation status
- Any members skipped (with reason: already documented, trivially obvious, ambiguous intent)

## Priority Order

Document in this order unless the user specifies otherwise:
1. Public APIs (classes, interfaces, public methods)
2. Protected APIs
3. Internal shared surfaces
4. Complex private members (only when documentation materially improves maintainability)

## Style Rules

- Present tense, active voice
- Caller-oriented phrasing
- US English
- Short, precise sentences
- Use `<see langword="null"/>`, `<see langword="true"/>`, etc. for language keywords
- Use `<c>...</c>` for inline code references in prose