---

name: api-docs description: Write and review XML API documentation for SkiaSharp following .NET guidelines. Use when user asks to document a class, add XML docs, write XML documentation, add triple-slash comments, review documentation quality, check docs for errors, fix doc issues, fill in missing docs, remove "To be added" placeholders, or mentions API documentation.

API Documentation

Write and review XML API documentation for SkiaSharp.

File Locations

docs/SkiaSharpAPI/
├── SkiaSharp/              # Main namespace
│   ├── SKCanvas.xml        # One XML file per type
│   ├── SKPaint.xml
│   ├── SKImage.xml
│   └── ...
├── HarfBuzzSharp/          # HarfBuzz namespace
├── SkiaSharp.Views.*/      # Platform-specific views
└── index.xml               # Extension methods (auto-synced, don't edit)

Writing Documentation

1. Find the type's XML file in docs/SkiaSharpAPI/<Namespace>/<TypeName>.xml
2. Edit <summary>, <param>, <returns>, <value> tags within <Docs> sections
3. Follow patterns in references/patterns.md
4. After editing a file, validate XML syntax (see XML Validation below)
5. Run dotnet cake --target=docs-format-docs to validate and format

Reviewing Documentation

1. Search for issues using grep patterns below
2. Classify by severity using references/checklist.md
3. Fix issues following references/patterns.md
4. Run dotnet cake --target=docs-format-docs to validate

Quick Issue Search

# Find placeholders
grep -r "To be added" docs/SkiaSharpAPI/

# Find empty tags (self-closing)
grep -rE "<(summary|value|returns)\s*/>" docs/SkiaSharpAPI/

# Find empty tags (open/close with optional whitespace)
grep -rE "<(summary|value|returns)>\s*</" docs/SkiaSharpAPI/

# Find spelling errors (common ones)
grep -riE "teh|recieve|seperate|occured|paramter" docs/SkiaSharpAPI/

# Find whitespace issues
grep -rE " </|  </" docs/SkiaSharpAPI/

Resources

• references/patterns.md - XML syntax and examples
• references/checklist.md - Review severity criteria

XML Validation

CRITICAL: After completing all edits to an XML file, validate its XML syntax before moving to the next file.

Validation Command

# Validate a single file
xmllint --noout docs/SkiaSharpAPI/SkiaSharp/SKCanvas.xml

# Validate all XML files in a namespace
find docs/SkiaSharpAPI/SkiaSharp -name "*.xml" -exec xmllint --noout {} \;

# Validate entire docs directory
find docs/SkiaSharpAPI -name "*.xml" -exec xmllint --noout {} \;

Common XML Errors to Avoid

1. Duplicate closing tags: </param></param> - happens when copy/pasting
2. Mismatched tags: <summary>...</param> - tag names must match
3. Unescaped characters: <, >, & must be <, >, &
4. Missing closing tags: <summary>text without </summary>

Workflow

1. Make all edits to a file
2. Run xmllint --noout <file> to validate
3. If errors, fix them before proceeding
4. Move to next file