| name | xml-doc-writer |
| description | Write, validate, and improve XML documentation comments in C# source code. Use when asked to add, fix, review, or complete XML docs for C# APIs. |
XML Doc Writer
Write accurate, consistent XML documentation for the exact C# APIs in scope. This
skill may be invoked directly or loaded by another agent working on those APIs.
Workflow
1. Gather context
Identify the exact types and members whose documentation is in scope. Read their
signatures, nearby documentation, inherited APIs, and relevant implementation
details before editing. Do not change API behavior while updating documentation.
2. Write and improve the documentation
- Add XML docs for undocumented public and protected types and members in scope.
- Remove documentation whose complete content is
To be added., then replace it
with useful documentation when the API is in scope.
- Verify existing documentation for correctness, grammar, consistency, and clear
descriptions of parameters, return values, exceptions, and side effects.
- Use
<see cref="..."/> and <paramref name="..."/> when they make references
clearer and can be resolved from the documented API.
- Prefer
/// <inheritdoc /> for overrides and interface implementations when the
inherited documentation is accurate.
- Replace XML documentation
include attributes with the referenced content.
Search for all references before removing inlined content from the include file,
and delete the include file only when it has no remaining content or consumers.
- Rewrite mentions of Xamarin.iOS or Xamarin.Mac using the current product names.
- Remove empty
<para> and <remarks> elements.
3. Normalize formatting
- Keep the existing code indentation and remove extra whitespace between
/// and
the XML element (keep a single space, as in /// <summary>).
- Indent nested XML elements by two spaces per level.
- Order top-level elements as:
<summary>, <value>, <typeparam>, <param>,
<returns>, <exception>, <remarks>, and <seealso>.
- Preserve a final newline in every modified file.
4. Validate
Review the final diff for valid XML, resolvable cref values, complete parameter
and type-parameter coverage, and documentation that matches the API signatures and
behavior.
