Skip to content

Resolve all docbuild warnings and gate them in CI - #2

Merged
MaximBazarov merged 3 commits into
mainfrom
docc-warnings-fix
Sep 5, 2026
Merged

MaximBazarov merged 3 commits into
mainfrom
docc-warnings-fix

Conversation

@MaximBazarov

Copy link
Copy Markdown
Owner

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-missing valueDescription parameter on start(...) and the sync withSpan(...) overload.
  • TestingSupport/StateReader: the two cross-module references to EnvironmentService are plain module-qualified backticks, not resolved links — xcodebuild docbuild registers no external resolver between sibling SPM library targets in this setup (confirmed by inspecting the actual docc convert invocations). See the "Open" section of ADR 0027 in the hub repo, recorded in MaximBazarov/SSM-Development#70.
  • New docs job in ci.yml: fails the build on any warning: line in the docbuild output, 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-Package is warning-free, swift build succeeds, and all 270 tests pass.

Maxim Bazarov 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.
@MaximBazarov
MaximBazarov merged commit fd2cf02 into main Sep 5, 2026
3 checks passed
@MaximBazarov
MaximBazarov deleted the docc-warnings-fix branch September 5, 2026 06:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant