Move API documentation into C# comments and normalize BOMs

[mattleibow]

Description

Extracts the complete comments-only review base from #5064 and deterministically removes matching UTF-8 BOMs. This standalone PR carries the frozen final XML documentation-comment prose for declarations already present on main; it contains zero functional or tooling changes.

Related issues

Related to #5064

Required skia PR

None.

Areas affected

• Managed API (binding/)
• Native / C API (externals/skia/src/c, include/c)
• Generated P/Invoke bindings
• Native dependency or Skia update (libpng, HarfBuzz, FreeType, zlib, milestone bump, …)
• Views & integrations (MAUI, Uno, WPF, WinUI, Blazor, …)
• Rendering output / visual behavior
• Performance
• Tests
• Build, packaging, or CI
• Documentation or samples

Changes

None — documentation comments plus deterministic UTF-8 BOM normalization only; no public API or behavior changes.

Testing

Machine-checked partition against immutable source 0e1d5f755cb6b15160832a0fcc117c03719a0e83..06f6413d86bc00eec0d01da2b2e18cec93539f58 (frozen tree d9b70ef5b518083c699414bdf2985e96a0dda87b):

Delta	C# paths	Added /// lines	Removed /// lines	Total
S — frozen source	368	22,643	151	22,794
B — documentation comments in this PR	349	22,382	151	22,533
R — reconstructed top	45	0	261	261

The partition proof verifies that B and R exactly partition S with no unclassified residual hunk, and applying B plus the complete reconstructed top produces the frozen source tree byte-for-byte. The persistent inventory records 44 R hunk identities, each with an accompanying declaration signature/code-change witness.

A raw-byte BOM inventory compared this PR with frozen source 06f6413d86bc00eec0d01da2b2e18cec93539f58. It authorizes and removes UTF-8 BOMs from 199 paths where this PR had EF BB BF and frozen source does not. (The immutable comparison produced 199, rather than the originally estimated 200; the three other BOM-bearing changed files retain BOMs in frozen source and were not changed.) The validator proves every remaining non-documentation byte equals main, all changed paths are existing .cs files, and no unlisted BOM changed.

Completed dotnet cake --target=externals-download; dotnet cake --target=docs-format-docs passed (the uninitialized docs submodule has no XML type files to scan). Built the core binding targeting net10.0.

Ran pwsh -NoLogo -NoProfile -File ./utils/generate.ps1 after initializing Skia and its DEPS checkout. SHA-256 snapshots before and after confirm generated files are byte-identical, including the generated documentation trivia.

Checklist

• Tests added or updated (if omitted, explain why above)
• Changes above lists all public API and behavioral changes (or "None.")
• New/changed public API? Filed a docs issue in mono/SkiaSharp-API-docs so reference docs can be written later
• Native change? Companion mono/skia PR linked above and bindings regenerated

[github-actions]

📦 Try the packages from this PR

Warning

Do not run these scripts without first reviewing the code in this PR.

Step 1 — Download the packages

bash / macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.sh | bash -s -- 5078

PowerShell / Windows:

iex "& { $(irm https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.ps1) } 5078"

Step 2 — Add the local NuGet source

dotnet nuget add source ~/.skiasharp/hives/pr-5078/packages --name skiasharp-pr-5078

More options

Option	Description
--successful-only / -SuccessfulOnly	Only use successful builds
--force / -Force	Overwrite previously downloaded packages
--list / -List	List available artifacts without downloading
--build-id ID / -BuildId ID	Download from a specific build

Or download manually from Azure Pipelines — look for the nuget artifact on the build for this PR.

Remove the source when you're done:

dotnet nuget remove source skiasharp-pr-5078

[github-actions]

📖 Documentation Preview

Add the automation/staging label to build and publish a documentation preview for this PR.

Removing the label removes the preview. While the label is present, each new commit updates it.

---

This comment is automatically updated by the documentation staging workflow.

[github-actions]

📊 SkiaSharp benchmarks — PR #5078

⭐ this PR (full source build) vs 🌙 nightly · Linux · Windows · macOS

Informational only — this never blocks the PR. 🟢 faster / less allocation · 🔴 slower / more allocation; moves under 5% are hidden as noise.

⏱️ Times are raw BenchmarkDotNet means, and the ⭐ PR and baseline legs run on separate CI runners, so microbenchmarks can swing run-to-run — treat small time deltas as noise. Allocations are deterministic and the reliable signal. The interactive perf-dashboard (linked below) applies smoothing for the trend view.

Highlights

⏱️ Time — 🔴 24 slower · 🟢 36 faster

• 🔴 MatrixMapPointsBenchmark.MapPoints(Points: 4096) · Windows · 2.29 µs → 4.03 µs (+76%)
• 🔴 MatrixMapPointsBenchmark.MapPoints(Points: 256) · Windows · 189.3 ns → 319.9 ns (+69%)
• 🟢 RuntimeEffectShaderBenchmark.DrawFrame · Linux · 5.68 ms → 2.83 ms (-50%)
• 🟢 SceneRenderBenchmark.RenderFrame(Complexity: 4) · Linux · 30.96 ms → 18.33 ms (-41%)
• 🟢 SceneRenderBenchmark.RenderFrame(Complexity: 1) · Linux · 6.67 ms → 3.99 ms (-40%)
• …and 55 more (see details below)

Full per-OS benchmark deltas

Linux

⏱️ Time (vs 🌙 nightly 4.154.0-nightly.26463.1)

Benchmark	baseline	this PR	Δ
RuntimeEffectShaderBenchmark.DrawFrame	5.68 ms	2.83 ms	🟢 -50%
SceneRenderBenchmark.RenderFrame(Complexity: 4)	30.96 ms	18.33 ms	🟢 -41%
SceneRenderBenchmark.RenderFrame(Complexity: 1)	6.67 ms	3.99 ms	🟢 -40%
MatrixMapPointsBenchmark.MapPoints(Points: 4096)	4.45 µs	2.94 µs	🟢 -34%
ColorMathBenchmark.UnPreMultiply(Colors: 4096)	9.43 µs	12.11 µs	🔴 +28%
ColorMathBenchmark.PreMultiply(Colors: 4096)	10.55 µs	12.86 µs	🔴 +22%
CanvasDrawBenchmark.Draw(Shapes: 512)	42.87 ms	33.59 ms	🟢 -22%
CanvasDrawBenchmark.Draw(Shapes: 64)	5.33 ms	4.21 ms	🟢 -21%
MatrixMapPointsBenchmark.MapRect(Points: 4096)	211.31 µs	176.53 µs	🟢 -16%
ColorMathBenchmark.ToColor(Colors: 4096)	12.21 µs	14.12 µs	🔴 +16%
MatrixMapPointsBenchmark.MapRect(Points: 256)	13.06 µs	11.04 µs	🟢 -15%
MatrixMapPointsBenchmark.MapPoint(Points: 4096)	65.91 µs	73.80 µs	🔴 +12%
ColorMathBenchmark.ToColorF(Colors: 4096)	14.85 µs	13.13 µs	🟢 -12%
LargeImageScaleBenchmark.UpscaleCrossfade(Size: 2048)	8.77 ms	7.88 ms	🟢 -10%
MatrixMapPointsBenchmark.MapPoint(Points: 256)	4.26 µs	4.62 µs	🔴 +8%
MatrixMapPointsBenchmark.MapVector(Points: 256)	11.88 µs	10.92 µs	🟢 -8%
BitmapDrawBenchmark.DrawUnscaledTiles(Tiles: 64)	274.28 µs	252.27 µs	🟢 -8%
LargeImageScaleBenchmark.UpscaleCrossfade(Size: 1024)	2.17 ms	2.01 ms	🟢 -7%
RasterImageLifecycleBenchmark.CreateRasterImage(Count: 256)	254.08 µs	272.53 µs	🔴 +7%
MatrixMapPointsBenchmark.MapPoints(Points: 256)	335.6 ns	313.1 ns	🟢 -7%
BitmapDrawBenchmark.DrawScaledTiles(Tiles: 256)	1.43 ms	1.33 ms	🟢 -7%
BitmapDrawBenchmark.DrawUnscaledTiles(Tiles: 256)	1.02 ms	951.46 µs	🟢 -6%
BitmapDrawBenchmark.DrawScaledTiles(Tiles: 64)	378.44 µs	356.81 µs	🟢 -6%
ColorParseBenchmark.Parse(Iterations: 1000)	68.69 µs	72.53 µs	🔴 +6%
LargeImageScaleBenchmark.UpscaleOpaque(Size: 1024)	714.36 µs	678.38 µs	🟢 -5%

Windows

⏱️ Time (vs 🌙 nightly 4.154.0-nightly.26463.1)

Benchmark	baseline	this PR	Δ
MatrixMapPointsBenchmark.MapPoints(Points: 4096)	2.29 µs	4.03 µs	🔴 +76%
MatrixMapPointsBenchmark.MapPoints(Points: 256)	189.3 ns	319.9 ns	🔴 +69%
RasterImageLifecycleBenchmark.CreateDataWithReleaseProc(Count: 256)	99.11 µs	127.12 µs	🔴 +28%
ColorMathBenchmark.ToColorF(Colors: 4096)	14.44 µs	17.45 µs	🔴 +21%
LargeImageScaleBenchmark.UpscaleOpaque(Size: 2048)	3.26 ms	3.93 ms	🔴 +21%
MatrixMapPointsBenchmark.MapPoint(Points: 4096)	87.72 µs	69.94 µs	🟢 -20%
MatrixMapPointsBenchmark.MapRadius(Points: 4096)	158.36 µs	131.27 µs	🟢 -17%
RuntimeEffectShaderBenchmark.DrawFrame	1.20 ms	996.45 µs	🟢 -17%
MatrixMapPointsBenchmark.MapPoint(Points: 256)	5.38 µs	4.54 µs	🟢 -16%
MatrixOpsBenchmark.Concat(Count: 4096)	269.43 µs	228.38 µs	🟢 -15%
MatrixMapPointsBenchmark.MapVector(Points: 4096)	140.35 µs	119.06 µs	🟢 -15%
MatrixOpsBenchmark.Invert(Count: 4096)	149.49 µs	127.17 µs	🟢 -15%
RasterImageLifecycleBenchmark.CreateRasterImage(Count: 256)	252.88 µs	290.40 µs	🔴 +15%
PathBoundsBenchmark.TightBounds(Points: 64)	1.57 µs	1.79 µs	🔴 +14%
MatrixMapPointsBenchmark.MapRadius(Points: 256)	9.73 µs	8.37 µs	🟢 -14%
LargeImageScaleBenchmark.UpscaleCrossfade(Size: 1024)	2.81 ms	2.50 ms	🟢 -11%
ColorMathBenchmark.UnPreMultiply(Colors: 4096)	13.03 µs	11.61 µs	🟢 -11%
MatrixMapPointsBenchmark.MapVector(Points: 256)	8.49 µs	7.61 µs	🟢 -10%
BitmapDrawBenchmark.DrawUnscaledTiles(Tiles: 64)	268.34 µs	244.27 µs	🟢 -9%
BitmapDrawBenchmark.DrawScaledTiles(Tiles: 256)	1.33 ms	1.25 ms	🟢 -6%
BitmapDrawBenchmark.DrawScaledTiles(Tiles: 64)	353.16 µs	331.07 µs	🟢 -6%
ColorMathBenchmark.PreMultiply(Colors: 4096)	14.69 µs	13.81 µs	🟢 -6%
MatrixMapPointsBenchmark.MapRect(Points: 256)	8.11 µs	7.64 µs	🟢 -6%
PathBoundsBenchmark.TightBounds(Points: 1024)	16.64 µs	17.48 µs	🔴 +5%

macOS

⏱️ Time (vs 🌙 nightly 4.154.0-nightly.26463.1)

Benchmark	baseline	this PR	Δ
BitmapDrawBenchmark.DrawScaledTiles(Tiles: 64)	283.19 µs	212.56 µs	🟢 -25%
LargeImageScaleBenchmark.UpscaleCrossfade(Size: 1024)	1.77 ms	1.46 ms	🟢 -18%
MatrixMapPointsBenchmark.MapRadius(Points: 4096)	101.24 µs	117.20 µs	🔴 +16%
MatrixMapPointsBenchmark.MapPoints(Points: 4096)	1.72 µs	1.99 µs	🔴 +15%
CanvasDrawBenchmark.Draw(Shapes: 64)	1.47 ms	1.66 ms	🔴 +13%
CanvasDrawBenchmark.Draw(Shapes: 512)	11.07 ms	12.44 ms	🔴 +12%
PathBoundsBenchmark.TightBounds(Points: 1024)	9.31 µs	10.32 µs	🔴 +11%
MatrixMapPointsBenchmark.MapPoints(Points: 256)	157.5 ns	172.0 ns	🔴 +9%
MatrixMapPointsBenchmark.MapPoint(Points: 4096)	20.34 µs	22.17 µs	🔴 +9%
LargeImageScaleBenchmark.UpscaleCrossfade(Size: 2048)	6.36 ms	6.77 ms	🔴 +6%
RasterImageLifecycleBenchmark.CreateRasterImage(Count: 256)	170.48 µs	180.86 µs	🔴 +6%

📈 Full interactive perf-dashboard & run details →