mono / api-docs

Skill Content

---
name: api-docs
description: >
  Write and review XML API documentation for SkiaSharp following .NET guidelines.
  
  Triggers: "document 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", API documentation requests.
---

# 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`](https://github.com/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](#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](references/patterns.md)
4. **After editing a file, validate XML syntax** (see [XML Validation](#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](references/checklist.md)
3. Fix issues following [references/patterns.md](references/patterns.md)
4. Run `dotnet cake --target=docs-format-docs` to validate

### Quick Issue Search

```bash
# 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](references/patterns.md) - XML syntax and examples
- [references/checklist.md](references/checklist.md) - Review severity criteria
- [documentation/writing-docs.md](../../../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):

```bash
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](../../../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

```bash
# 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 `&lt;`, `&gt;`, `&amp;`
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