[docs] Fix broken API doc cross-references - #152
Conversation
Correct 16 dangling <see>/<value> cross-references that the AED documentation-fill PRs (#150, #151) left pointing at removed, renamed, or mistyped SkiaSharp members. Removes the resulting docfx xref-not-found warnings. ECMA-XML prose only; no mdoc regeneration. - SKColorTable.MaxLength -> SKColorFilter.TableMaxLength (type removed) - SKCodec.Origin -> SKCodec.EncodedOrigin (renamed) - SKSurfaceProps -> SKSurfaceProperties (renamed) - GrVkYcbcrConversionInfo -> GRVkYcbcrConversionInfo (casing) - SKPathVerb.Close: E: -> F: (enum field, wrong prefix) - SKFontStyleWeight/Width: F: -> T: (type, wrong prefix) - *.Empty (SKMatrix, SKPoint, SKColorSpaceXyz, SKColorSpaceTransferFn): P: -> F: - SKMatrix44 Create* remarks: drop references to removed Set* instance methods Co-authored-by: Copilot <[email protected]>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 6d1c722:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| SkiaSharpAPI/SkiaSharp/SKPath+Iterator.xml | Details | ||
| SkiaSharpAPI/SkiaSharp/GRVkImageInfo.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKColorFilter.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKColorSpace.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKColorSpaceIccProfile.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKEncodedOrigin.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKFontStyle.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKMatrix44.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKPathMeasure.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKSurfacePropsFlags.xml | ✅Succeeded |
SkiaSharpAPI/SkiaSharp/SKPath+Iterator.xml
- Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.SKPath.Iterator.Next(SkiaSharp.SKPoint[],System.Boolean,System.Boolean)'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.SKPath.Iterator.Next(SkiaSharp.SKPoint[],System.Boolean,System.Boolean)'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.SKPath.Iterator.Next(SkiaSharp.SKPoint[],System.Boolean,System.Boolean)'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
Learn build validation on the docs flagged M:SkiaSharp.SKPath.Iterator.Next(SkiaSharp.SKPoint[],System.Boolean,System.Boolean) as xref-not-found. The 3-arg overload was removed upstream; SKPath.Iterator now exposes only Next(SKPoint[]) and Next(Span<SKPoint>) (verified against binding/SkiaSharp/SKPath.cs and the SKPath+Iterator.xml member list). Repoint all 10 occurrences (3 in SKPath+Iterator.xml, 7 in SKPathVerb.xml) to M:SkiaSharp.SKPath.Iterator.Next(SkiaSharp.SKPoint[]). Sibling RawIterator.Next(SKPoint[]) crefs are valid and left unchanged. This was missed initially because the xref scan matched on type+method name and ignored the overload signature; the scan now requires exact full-DocId matches, and a strict whole-repo re-audit confirms zero remaining internal dangling crefs. Co-authored-by: Copilot <[email protected]>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit b1a4747:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| SkiaSharpAPI/SkiaSharp/GRVkImageInfo.xml | Details | ||
| SkiaSharpAPI/SkiaSharp/GrVkYcbcrConversionInfo.xml | Details | ||
| SkiaSharpAPI/SkiaSharp/SKColorFilter.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKColorSpace.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKColorSpaceIccProfile.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKEncodedOrigin.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKFontStyle.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKMatrix44.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKPath+Iterator.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKPathMeasure.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKPathVerb.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKSurfacePropsFlags.xml | ✅Succeeded |
SkiaSharpAPI/SkiaSharp/GRVkImageInfo.xml
- Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'.
SkiaSharpAPI/SkiaSharp/GrVkYcbcrConversionInfo.xml
- Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkFilter'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
The ChromaFilter property doc in the legacy GrVkYcbcrConversionInfo struct referenced a type that does not exist — `<see cref="T:SkiaSharp.GRVkFilter"/>`. ChromaFilter is a plain `uint` holding a raw Vulkan `VkFilter` value; there is no GRVkFilter type in the docs corpus or the SkiaSharp API, so docfx emits an xref-not-found warning. The modern GRVkYcbcrConversionInfo struct already documents the same field correctly as a raw `<c>VkFilter</c>` value; mirror it. This dangling cref was missed by the prior xref sweep because the repo contains a case-collision pair — GRVkYcbcrConversionInfo.xml (modern) and GrVkYcbcrConversionInfo.xml (legacy) differ only by case. On a case-insensitive filesystem only one of the two physically checks out, so a working-tree glob silently drops the shadowed legacy file. Staged via git plumbing so the fix lands on the legacy blob without materializing both colliding paths on disk. Co-authored-by: Copilot <[email protected]>
|
Learn Build status updates of commit 4ae0eee:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| SkiaSharpAPI/SkiaSharp/GRVkImageInfo.xml | Details | ||
| SkiaSharpAPI/SkiaSharp/GrVkYcbcrConversionInfo.xml | Details | ||
| SkiaSharpAPI/SkiaSharp/SKColorFilter.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKColorSpace.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKColorSpaceIccProfile.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKEncodedOrigin.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKFontStyle.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKMatrix44.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKPath+Iterator.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKPathMeasure.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKPathVerb.xml | ✅Succeeded | ||
| SkiaSharpAPI/SkiaSharp/SKSurfacePropsFlags.xml | ✅Succeeded |
SkiaSharpAPI/SkiaSharp/GRVkImageInfo.xml
- Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'.
SkiaSharpAPI/SkiaSharp/GrVkYcbcrConversionInfo.xml
- Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'. - Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
The legacy [Obsolete("Use GRVkYcbcrConversionInfo instead.")] forwarder struct
GrVkYcbcrConversionInfo (lowercase-r) and the modern GRVkYcbcrConversionInfo
(uppercase-R) differ only by one letter's case. mdoc documents both
soft-obsolete types, producing two ECMA-XML files whose names collide on a
case-insensitive filesystem (the Learn / OpenPublishing build). One file
shadows the other, so crefs to the shadowed type fail with
"Cross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'".
PR #152 repointed GRVkImageInfo.xml from the wrong lowercase casing to the real
uppercase type; that correct fix exposed this latent collision (the GR page is
the one shadowed). Rather than revert the casing, remove the collision at its
source: stop publishing the obsolete forwarder's page. The legacy type only
forwards to the modern one via two implicit conversion operators.
- Delete SkiaSharpAPI/SkiaSharp/GrVkYcbcrConversionInfo.xml
(T:SkiaSharp.GrVkYcbcrConversionInfo) via the index, leaving the modern
GRVkYcbcrConversionInfo.xml blob untouched.
- Remove its <Type> block from SkiaSharpAPI/FrameworksIndex/skiasharp.xml.
- Remove its entry from SkiaSharpAPI/index.xml.
No surviving file references T:SkiaSharp.GrVkYcbcrConversionInfo; the modern
GRVkYcbcrConversionInfo page is kept and now resolves cleanly. A companion
generator-side exclusion is being added in mono/SkiaSharp
scripts/infra/docs/docs.cake so mdoc won't regenerate the page.
Co-authored-by: Copilot <[email protected]>
|
Learn Build status updates of commit 9cf7bfa: ❌ Validation status: errorsPlease follow instructions here which may help to resolve issue.
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
The previous build failed on a transient infrastructure error (restore-template-repository-failed: could not clone Microsoft/templates.docs.msft#main); all changed files validated Succeeded with zero cross-reference errors. Empty commit to re-run. Co-authored-by: Copilot <[email protected]>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 95b8066: ✅ Validation status: passed
For more details, please refer to the build report. |
Go Live: publish latest API docs (#171) Publish the accumulated SkiaSharp / HarfBuzzSharp API documentation from main to the live (published) branch. This is the first Go Live since #66 and rolls up a large batch of docs automation, a full regeneration, and content/cross-reference cleanup. Highlights in this batch: - Docs automation: automated API docs writer (#92, hardened in #155), daily update workflow, go-live workflow (#65), and a Learn Build status-based auto-merge gate (#82, #83) backed by check-learn-build.py and a .github/known-warnings.csv baseline. - Regeneration: frameworks docs switched to latest-only monikers (#141), baseline reset to the Windows-generated output (#142), and stub regeneration moved to Linux via Mono (#147). This drops older, no-longer-shipping member/type pages (e.g. pre-v1.68 view APIs, the removed Android ISKRenderer interface, and the SKPaint text properties that moved to SKFont). - Content: filled API documentation placeholders (#150, #151, #172) and fixed broken cross-references (#152). - Cross-reference cleanup (#173): removed/repointed 36 obsolete xref-not-found references left behind by the latest-only-moniker regeneration — dangling links in 2019-era remarks to members that were since removed or relocated. Without this the Go Live build reported 160 warnings and the auto-merge gate (correctly) blocked the publish. Build health at publish: 0 errors, 124 warnings, 0 suggestions. All 124 remaining warnings are expected xref-not-found references to external framework types (OpenTK, Gdk/Cairo/Graphene, ElmSharp/Tizen.NUI, Windows.UI.Xaml, Microsoft.UI.Xaml, SharpVk, Vortice) that Learn cannot resolve and which are tracked in the known-warnings.csv baseline — 0 new warnings versus baseline, so the gate passes. Co-authored-by: Matthew Leibowitz <[email protected]> Co-authored-by: Copilot App <[email protected]>
1 participant
Summary
The "Auto API Docs Writer" workflow regenerated mdoc stubs against the current SkiaSharp surface (~m148 / 4.150), and the AI documentation-fill PRs (#150, #151) wrote prose that referenced members which were since removed, renamed, or that it referenced with the wrong DocId prefix / wrong overload signature. These produce docfx / Learn
xref-not-foundwarnings.This PR repoints/corrects 19 distinct dangling
<see>/<value>cross-references (32 occurrences) across 12 ECMA-XML files, and removes one obsolete duplicate type page that caused a case-collision build break. ECMA-XML prose only — no mdoc regeneration, no unrelated reformatting.Validation: built the authoritative valid-target set from every
<TypeSignature>/<MemberSignature Language="DocId">in the docs — using the exact full DocId string including the overload parameter signature — and confirmed a strict whole-repo re-audit reports zero internalSkiaSharp*/HarfBuzzSharp*dangling crefs, with no new ones introduced. The validation oracle is the doc corpus itself — docfx/Learn builds its xref map only from the ECMA-XML set, so a cref is valid iff its exact DocId exists in the corpus. Every replacement target was confirmed present in the corpus, and stale stubs were deliberately left intact (not cross-checked against the live API, which would cause over-fixing). The "removed/renamed upstream" notes in the table below are explanatory context for why a member changed, not the validation authority.Fixes (from → to)
SKPath+Iterator.xml(×3) +SKPathVerb.xml(×7)M:SkiaSharp.SKPath.Iterator.Next(SkiaSharp.SKPoint[],System.Boolean,System.Boolean)M:SkiaSharp.SKPath.Iterator.Next(SkiaSharp.SKPoint[])SKPath.Iteratornow only exposesNext(SKPoint[])andNext(Span<SKPoint>)(binding/SkiaSharp/SKPath.cs). SiblingRawIterator.Next(SKPoint[])crefs are valid and left unchangedSKColorFilter.xml(×5)F:SkiaSharp.SKColorTable.MaxLengthF:SkiaSharp.SKColorFilter.TableMaxLengthSKColorTabletype removed; replacement constant (= 256) already used by the sibling overloads in the same fileSKEncodedOrigin.xmlP:SkiaSharp.SKCodec.OriginP:SkiaSharp.SKCodec.EncodedOriginSKSurfacePropsFlags.xmlT:SkiaSharp.SKSurfacePropsT:SkiaSharp.SKSurfacePropertiesSKSurfacePropertiesis the type that consumesSKSurfacePropsFlagsGRVkImageInfo.xmlT:SkiaSharp.GrVkYcbcrConversionInfoT:SkiaSharp.GRVkYcbcrConversionInfoGR…)SKPath+Iterator.xmlE:SkiaSharp.SKPathVerb.CloseF:SkiaSharp.SKPathVerb.CloseSKFontStyle.xml(×2)F:SkiaSharp.SKFontStyleWeight/…WidthT:SkiaSharp.SKFontStyleWeight/…WidthSKColorSpace.xmlP:SkiaSharp.SKColorSpaceTransferFn.EmptyF:…Emptyis astatic readonlyfieldSKColorSpace.xml/SKColorSpaceIccProfile.xmlP:SkiaSharp.SKColorSpaceXyz.EmptyF:…SKPathMeasure.xmlP:SkiaSharp.SKMatrix.EmptyF:…F:elsewhere)SKPathMeasure.xml(×2)P:SkiaSharp.SKPoint.EmptyF:…SKMatrix44.xml(×4)M:SkiaSharp.SKMatrix44.SetIdentity/SetRotationAbout/SetRotationAboutDegrees/SetScale<remarks />)SKMatrix44is now immutable, 18 staticCreate*factories, 0Set*in source); no replacement to point at, and thesummary/returnsalready describe each factory. Matches the empty<remarks />already on the siblingCreateScaleoverloadGrVkYcbcrConversionInfo.xmlT:SkiaSharp.GRVkFilter(inChromaFilter<value>)<c>VkFilter</c>(plain text)GRVkFilterexists in the docs orbinding/SkiaSharp/**;ChromaFilteris a rawuintVulkanVkFiltervalue. Mirrors the modernGRVkYcbcrConversionInfostruct, which already documents the field as a raw<c>VkFilter</c>valueFalse positives — verified valid, left unchanged
The originating scan flagged 19 candidates with a loose member-resolution heuristic. After re-validating against the docs' actual DocId targets with exact overload-signature matching, 10 of those resolve correctly and were not touched (mostly nested types, whose DocId uses
.while the filename uses+):T:SkiaSharp.GRVkYcbcrConversionInfo(correct casing)T:SkiaSharp.HarfBuzz.SKShaper.ResultT:SkiaSharp.SKPath.Iterator,T:SkiaSharp.SKPath.OpBuilder,T:SkiaSharp.SKPath.RawIteratorT:SkiaSharp.SKRegion.ClipIterator,T:SkiaSharp.SKRegion.RectIterator,T:SkiaSharp.SKRegion.SpanIteratorT:SkiaSharp.Views.Android.GLTextureView.IRendererT:SkiaSharp.Views.Maui.Controls.GetPropertyValueEventArgs1`Case-collision removal —
GrVkYcbcrConversionInfopage droppedRepointing
GRVkImageInfo.xmlto the correct uppercase casing (above) exposed a latent build break: the live Learn build reportedCross reference not found: 'SkiaSharp.GRVkYcbcrConversionInfo'.Root cause. Two public types differ only by one letter's case — the modern struct
GRVkYcbcrConversionInfoand the legacy[Obsolete("Use GRVkYcbcrConversionInfo instead.")]forwarderGrVkYcbcrConversionInfo(whose only members are the two implicit conversion operators between the two). mdoc documents both soft-obsolete types, so the corpus contains two ECMA-XML files whose names differ only by case:SkiaSharp/GRVkYcbcrConversionInfo.xmlandSkiaSharp/GrVkYcbcrConversionInfo.xml. On the OpenPublishing build's case-insensitive filesystem these collide — one shadows the other — so crefs to the shadowed type can't resolve.Fix — stop publishing the obsolete forwarder's page (it merely forwards to the modern type), removing the collision at its source:
SkiaSharpAPI/SkiaSharp/GrVkYcbcrConversionInfo.xml(T:SkiaSharp.GrVkYcbcrConversionInfo) — removed from the git index by exact path; the modernGRVkYcbcrConversionInfo.xmlblob is left untouched<Type>blockSkiaSharpAPI/FrameworksIndex/skiasharp.xml(Name="SkiaSharp.GrVkYcbcrConversionInfo"+ its 14 members)SkiaSharpAPI/index.xml(<Type Name="GrVkYcbcrConversionInfo" Kind="Structure" />)No surviving file references
T:SkiaSharp.GrVkYcbcrConversionInfo— after PR #152 the only references lived inside the deleted page. The modernGRVkYcbcrConversionInfopage is kept and its DocId target survives, so the previously-failing cref now resolves. A strict whole-repo git-blob re-scan reports 443 files, 0 case-collision pairs (was 1), 0 internal dangling crefs. A companion generator-side exclusion is being added inmono/SkiaSharpscripts/infra/docs/docs.cakeso mdoc won't regenerate the obsolete page on the next stub refresh.External-framework crefs (
System.*,Android.*,Gdk.*,Graphene.*,Microsoft.Maui.*,OpenTK.*,Cairo.*) resolve via docfx's external xref maps and are out of scope.Co-authored-by: Copilot [email protected]