api-docs

API Documentation

Write and review XML API documentation for SkiaSharp.

Key Concepts

• The docs/ directory is a Git submodule pointing to mono/SkiaSharp-API-docs — changes must be committed and PR'd to that repository
• XML files are generated from NuGet assemblies using mdoc — if new APIs were added, regenerate before editing (see Regenerating Docs)
• For existing APIs, you can edit the XML files directly without regenerating

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
• documentation/writing-docs.md - Full docs generation workflow (automated pipeline, local generation, cake targets)

Regenerating Docs

When new APIs have been added (new classes, methods, properties), the XML doc files must be regenerated before you can document them. A daily GitHub Actions workflow does this automatically from the latest CI NuGet packages.

To regenerate locally (e.g., after adding new APIs):

dotnet tool restore
dotnet cake --target=docs-download-output   # Download latest NuGets
dotnet cake --target=update-docs            # Regenerate XML docs

New members will appear with "To be added." placeholders. See documentation/writing-docs.md for full details.

To edit existing docs (no regeneration needed): just edit the XML files directly and run dotnet cake --target=docs-format-docs to format and validate.

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