docs: keep the mkdocs site to the public API — scrub internal tooling references#10
Merged
Merged
Conversation
The mkdocs site is consumer-facing and should only discuss the public API. Remove internal mechanism names from user-facing pages: - SKIE attributions on index, installation, platforms, recipes, and concepts pages — rephrased to describe the observable Swift surface (exhaustive enums, AsyncSequence bridging, close() name preservation) instead of the tool that produces it - Internal source paths (Reachability+Shared.swift, Reachability.apple.kt) that consumers cannot act on - KMMBridge naming in the SPM roadmap note - CLAUDE.md and sibling-project references in mkdocs.yml comments contributing.md keeps its toolchain mentions — that page documents build prerequisites for contributors, where the toolchain is the subject. mise run docs:build (strict) and docs/check.py pass. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ing names main's SPM distribution rewrote the installation page; resolve by taking the new shipped-SPM content and applying the docs policy from this branch — describe the prebuilt XCFramework and Swift bridging by behavior, without naming the toolchain that produces it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Dokka renders this KDoc into the public API reference on the docs site; describe the Swift bridging by behavior per the docs policy. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
1 participant
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.
What changed
The mkdocs site named internal tooling and files that consumers can't act on. This PR rewrites those passages to describe the behavior of the published API instead of the mechanism behind it:
StateFlow<T>bridges asAsyncSequence<T>,close()keeps its name). The Kotlin floor row no longer claims its upper bound "tracks SKIE".Reachability+Shared.swift,Reachability.apple.kt) alongside the tool naming.Why
The docs are consumer-facing; they should document the public API contract, not the toolchain. Behavior-level phrasing also future-proofs the pages — a change in the Swift-interop toolchain wouldn't invalidate them.
Notes for review
contributing.mddeliberately keeps its toolchain mentions: that page documents build prerequisites for contributors, where the toolchain is the subject. The README is similarly out of scope here.mise run docs:build(strict mode) anddocs/check.py— both pass.🤖 Generated with Claude Code