# Csharp Docs
> Write and review C# XML documentation comments for public and complex internal APIs, including summaries, remarks, examples, cref links, parameters, returns, constructors, properties, and exceptions. Use when asked for C# documentation best practices or XML comments.
- Skill: `paulasilvatech/csharp-docs-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add paulasilvatech/csharp-docs-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulasilvatech/csharp-docs-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: paulasilvatech (https://skillmd.com/u/paulasilvatech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paulasilvatech/csharp-docs-2
---
# C# XML documentation
Convert C# APIs into precise XML documentation comments that describe behavior, parameters, return values, examples, exceptions, and cross-references using Microsoft-style phrasing.
## When to invoke
- "Add XML docs to this C# API."
- "Review these C# documentation comments."
- "What should the `` and `` text say?"
- "Document exceptions and examples for this method."
## API coverage
| API surface | Documentation expectation |
| --- | --- |
| Public types and members | Document with XML comments. |
| Internal members | Document when complex, non-obvious, or not self-explanatory, or part of a testable/internal contract. |
| Overrides and interface implementations | Use `` unless behavior materially changes; document differences when it does. |
| Exceptions | Document exceptions thrown directly and nested exceptions users are likely to encounter. |
## Common XML tags
| Tag | Use |
| --- | --- |
| `` | Brief one-sentence description. Start with a present-tense, third-person verb. |
| `` | Extra context, implementation notes, or usage constraints. |
| `` | `language-specific` keywords through `` such as `null`, `true`, `false`, `int`, and `bool`. |
| `` | Inline code snippets. |
| `` | Usage examples. |
| `` | Code blocks inside ``; the `` tag should carry a `language` attribute such as `language="csharp"`. |
| `` | Inline reference in a sentence. |
| `` | Standalone See also reference. |
| `` | Inherit base or interface documentation. |
| `` | Reference a parameter in prose. |
| `` | Reference a generic type parameter in prose. |
## Methods and generics
| Element | Wording rule |
| --- | --- |
| `` | Use a noun phrase that does not specify the data type and begins with an introductory article. |
| Flag enum parameter | Start with "A bitwise combination of the enumeration values that specifies...". |
| Non-flag enum parameter | Start with "One of the enumeration values that specifies..." and treat it as a non-flag enum. |
| Boolean parameter | Use "`` to ...; otherwise, ``." |
| `out` parameter | Use "When this method returns, contains ... . This parameter is treated as uninitialized." |
| `` | Describe generic type parameters. |
| `` | Use a noun phrase that does not specify the data type and begins with an introductory article. |
| Boolean return | Use "`` if ...; otherwise, ``." |
## Constructors, properties, and exceptions
| Member | Required phrasing |
| --- | --- |
| Constructor summary | "Initializes a new instance of the `` class." or "Initializes a new instance of the `` struct." |
| Read-write property | Start `` with "Gets or sets..." for a read-write property. |
| Read-only property | Start `` with "Gets..." for a read-only property. |
| Boolean property | Start with "Gets a value that indicates whether..." or "Gets or sets a value that indicates whether...". |
| `` | Describe the property value as a noun phrase; include default in a separate sentence when known. |
| Boolean `` | Use "`` if ...; otherwise, ``. The default is ..." when a default is known. |
| `` | State the condition directly; omit "Thrown if" and initial "If". The baseline shorthand is ``. |
## Examples
### Good
```csharp
///
/// Gets a value that indicates whether the cache contains the specified key.
///
/// The key to locate.
/// if the cache contains ; otherwise, .
```
### Bad
```csharp
/// Checks a string key and returns bool.
/// String key.
/// Boolean result.
```
## Gotchas
- **Do not restate the type**: parameter and return descriptions should explain meaning, not `string`, `int`, or `bool`.
- **Do not use vague summaries**: describe observable behavior, not "Does the thing".
- **Do not overuse ``**: document behavior differences explicitly.
- **Do not document impossible exceptions**: list exceptions users can actually encounter.
## Output template
````markdown
## C# documentation result
**Target:** ``
```csharp
///
/// .
///
/// .
/// .
/// .
```
### Documentation notes
- ``:
- ``:
- ``:
- ``:
````
## Quality gate
- [ ] Public APIs have XML comments; complex internal APIs are documented when needed.
- [ ] `` starts with a present-tense, third-person verb.
- [ ] Parameters, type parameters, returns, values, and exceptions use the required wording patterns.
- [ ] Boolean, enum, flag enum, and `out` parameter wording follows the specialized rules.
- [ ] Examples use `` with `` when code blocks are included in XML docs.
- [ ] Cross-references use ``, ``, ``, and `` where appropriate.