API Documentation

Add and review SkiaSharp API documentation. This file is a router: it picks a procedure and points to the reference and tooling files that do the work. The detailed instructions live in references/ so they load only when needed.

Key facts

• docs/ is the mono/SkiaSharp-API-docs submodule — one ECMA/mdoc .xml per type, generated from NuGet assemblies via mdoc. CDATA <remarks> may hold csharp code fences. Run git submodule update --init docs if it is empty.
• Each <Type>.xml maps 1:1 to binding/SkiaSharp/<Type>.cs (or binding/HarfBuzzSharp/) → always read source before documenting.
• Edit the XML directly. Safety comes from docs-format-docs, which formats every file and fails the build on broken XML/CDATA (references/validation.md).
• Never edit generated files: index.xml, ns-*.xml, _filter.xml, FrameworksIndex/.

How to work

One agent does the whole pass. Read the relevant reference, resolve scope into an explicit file list, then work in batches of ~25–40 files so each pass stays auditable and resumable.

If the task is…	Read
Documenting new APIs / filling To be added. placeholders	references/adding.md
Reviewing/correcting/expanding existing docs (one type, a theme, what changed, or all)	references/reviewing.md

The user asks in plain language ("review the font docs", "fill in what's missing"). The docs live at docs/SkiaSharpAPI/<Namespace>/<Type>.xml; list them directly, and use git -C docs diff --name-only origin/main...HEAD for "what changed". Each <Type>.xml maps to its source at binding/<Namespace>/<Type>.cs, and you pick the files a request covers — for a theme, scan the list and select the matching types yourself; the chosen procedure file covers the rest.

All findings use one machine-parseable contract: SEVERITY | class | file | docId | message.

References (canonical facts)

• references/patterns.md — .NET XML doc syntax, verb conventions, formatting.
• references/skia-patterns.md — domain facts (color layouts, struct defaults, standard-based enums, caller-owned vs parent-owned).
• references/checklist.md — CRITICAL/IMPORTANT/MINOR severity taxonomy.
• references/obsolete-api-map.md — obsolete members and their modern replacements; the writer and example reviewer read it (not the linter — obsolete use is a model judgement, see the reference for why).

DRY rule: the procedures describe what to do; the reference tables hold the facts. Procedures point to references — they must not restate the tables. Keep reference chains one level deep.

Tooling & validation

• Format + checks (one Cake target in scripts/infra/docs/docs.cake): docs-format-docs formats every type file and runs the deterministic content checks — warnings for missing/quality issues, build-failing errors for broken XML/CDATA. See references/validation.md.
• Snippet build (C#-only, download is fine): dotnet cake --target=externals-download then dotnet build binding/SkiaSharp/SkiaSharp.csproj.

Landing changes

The docs submodule protects main — commit on a dev/... branch and open a PR (per-wave). Skill asset changes land in the parent mono/SkiaSharp repo; the auto-api-docs-writer agentic workflow that runs this skill on CI lives in mono/SkiaSharp-API-docs.