xml-doc-writer

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.