api-docs

# API Documentation Write and review the public API prose that `mono/SkiaSharp` owns. C# `///` comments on public declarations are authoritative. Managed builds generate compiler XML from those comments and package it beside the managed assemblies. This repository has no API-reference ECMA/mdoc source, mdoc engine, `docs` submodule, XML-editing workflow, or placeholder-writing workflow. `mono/SkiaSharp-API-docs` independently consumes package/compiler XML and `_DocsMedia`, produces ECMA/mdoc, preserves deferred Uno output, validates, and publishes Learn. Do not edit that repository or generated output here. ## Scope and procedure 1. Resolve the consumer-visible public types and members in scope. Read their declarations and implementations in `binding/` or `source/` before writing any prose. Implementation-assembly XML does not make an API public. 2. Add or correct accurate `///` comments immediately above public declarations. Work from the source declaration, never from compiler XML. 3. Generated bindings are source-controlled. Edit only their `///` comment trivia directly, then run `pwsh -NoLogo -NoProfile -File ./utils/generate.ps1` and verify it preserves the intended comments. Never manually change generated declarations, interop code, or implementation. 4. Follow [`references/adding.md`](references/adding.md) for source-first authoring or [`references/reviewing.md`](references/reviewing.md) for a source-first review. Apply the detailed syntax and prose rules in [`references/patterns.md`](references/patterns.md). 5. Refresh documentation-convention knowledge from the first-party sources listed in [`references/patterns.md`](references/patterns.md) before a broad authoring or review pass. Reconcile a changed official convention with existing source forms and external rendering before applying it; do not mechanically rewrite source comments merely to match a style rule. 6. Verify SkiaSharp and HarfBuzzSharp facts in [`references/skia-patterns.md`](references/skia-patterns.md), and ensure examples avoid error-obsolete APIs with [`references/obsolete-api-map.md`](references/obsolete-api-map.md). 7. Classify findings with [`references/checklist.md`](references/checklist.md) and perform the build, compiler-XML, and package checks in [`references/validation.md`](references/validation.md). ## API-documentation contract - The compiler XML generated from public `///` comments is packaged beside the corresponding managed assemblies in both `lib/<tfm>` and `ref/<tfm>`. - The XML beside the reference assembly is the consumer-visible documentation contract. The copy beside `lib` is intentional but implementation-only XML entries do not expand the public API surface. - `_DocsMedia` is versioned source in this repository and a nonshipping transport artifact. The external API-docs repository retrieves matching package and media inputs and owns downstream ECMA/mdoc generation, validation, and publication. ## References | Need | Read | |---|---| | Adding or updating source comments | [`references/adding.md`](references/adding.md) | | Reviewing documentation and examples | [`references/reviewing.md`](references/reviewing.md) | | C# XML-comment syntax and conventions | [`references/patterns.md`](references/patterns.md) | | Severity bar and reporting | [`references/checklist.md`](references/checklist.md) | | Build, compiler-XML, and package validation | [`references/validation.md`](references/validation.md) | | SkiaSharp/HarfBuzzSharp factual sources | [`references/skia-patterns.md`](references/skia-patterns.md) | | Error-obsolete API replacements | [`references/obsolete-api-map.md`](references/obsolete-api-map.md) | ## Boundaries - Do not manually edit compiler-generated XML or ECMA/mdoc files. In generated bindings, edit only source-controlled `///` comment trivia and verify a generator round trip preserves it. - Do not remove valid public source comments to defer documentation elsewhere. Missing or inaccurate public documentation blocks API review. - Do not claim defaults, validation, ownership, threading, native layout, or standards behavior without verifying the relevant source.