Repository navigation
Resolve all docbuild warnings and gate them in CI - #2
Merged
Merged
Conversation
added 3 commits
September 1, 2026 19:56
Fixes the 17 unresolved/ambiguous DocC symbol links and undocumented parameters current at HEAD, per the 2026-09-01 re-audit on #61: - AsyncStrategy: bare onRead/onWrite/onDrop refs carry full signatures. - AsyncStrategyEnvironment, SharedEnvironment+Seeding: perform refs that can only disambiguate via an opaque hash drop to a plain unlinked backtick instead of embedding the hash. - Watch, SMPublished, Write, SeedOperationsBuilder: refs to symbols that don't resolve (a generic-effect protocol requirement, or a type not in this catalog) drop to plain backtick or a fully-qualified module name. - AsyncState: designated-init doc links carry DocC's own suggested type-tuple disambiguator. - TraceContext: document the valueDescription parameter on start(...) and the sync withSpan(...) overload. - TestingSupport/StateReader: cross-module refs to EnvironmentService. Plain module-qualified backtick, not a resolved link -- xcodebuild docbuild registers no external resolver between sibling SPM library targets, confirmed by inspecting the docc convert invocations. See docs/adr/0027-Warning-Free-Docbuild-Gate.md in the hub repo. Adds a docs CI job that fails the build on any docbuild warning, on the same triggers as the existing test matrix. Documents the hash-vs-backtick convention in CONTRIBUTING.md's Code style section. Verified: xcodebuild clean docbuild -scheme StateManagement-Package is warning-free, swift build succeeds, and all 270 tests pass.
A Computed's Address is also spelled \C.$name, so scoping $ to the AsyncStrategy seam made the glossary forbid a case its own Value entry allows. $ Address now names the wrapper rather than the Value it wraps, whichever wrapper that is.
…rtial derivation. A Computed always runs, so the framework has no fact it knows may be missing and adds no Optional. An author whose derivation is genuinely partial declares Computed<Key, Output?> and answers nil for a key it declines, which nothing in the suite exercised. Two probes now hold that claim: the derivation caches and invalidates a nil per key like any other output, and a Watch binds the Optional Output as-is rather than wrapping it a second time.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes the 17 unresolved/ambiguous DocC symbol links and undocumented parameters current on
main, per MaximBazarov/SSM-Development#61 (re-audited 2026-09-01).AsyncStrategy,AsyncStrategyEnvironment,SharedEnvironment+Seeding,Watch,SMPublished,Write,SeedOperationsBuilder,AsyncState: every bare/ambiguous/unresolvable symbol reference now either carries a full signature, a DocC-suggested disambiguator, or drops to a plain unlinked backtick where no link can resolve (never an opaque hash suffix).TraceContext: documents the previously-missingvalueDescriptionparameter onstart(...)and the syncwithSpan(...)overload.TestingSupport/StateReader: the two cross-module references toEnvironmentServiceare plain module-qualified backticks, not resolved links —xcodebuild docbuildregisters no external resolver between sibling SPM library targets in this setup (confirmed by inspecting the actualdocc convertinvocations). See the "Open" section of ADR 0027 in the hub repo, recorded in MaximBazarov/SSM-Development#70.docsjob inci.yml: fails the build on anywarning:line in thedocbuildoutput, same triggers as the existing test matrix.CONTRIBUTING.md: documents the hash-vs-backtick convention for linking overloaded symbols.Verified:
xcodebuild clean docbuild -scheme StateManagement-Packageis warning-free,swift buildsucceeds, and all 270 tests pass.