docs: expand README (requirements, installation, API reference) - #5
Conversation
The README already covered the v2 async/observable API at a high level; this fills the gaps for someone adopting the package: - Add a Requirements section (Swift 6 / Xcode 16, supported platforms, the minimum Pico AI Homelab version). - Expand Installation with concrete SwiftPM steps (Xcode "Add Package Dependencies" and a Package.swift snippet) and note the single re-exporting import; fold the former "Xcode Settings" into a "Configure your Xcode project" subsection and mention the iOS multicast entitlement. - Add a Usage section with a quick-start, a BonjourPico API table, a BonjourEndpoint field table, an endpointStream() async-sequence example, notes on automatic retry / the `state` property, advanced configuration, and the BonjourPicoError surface. - Add a table of contents and document the incomplete-advertisement filtering and the stable `id` (ServerIdentifier) contract. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011r15hkWqTdtMV4TeAgrqn8
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly expands the README.md documentation for the BonjourPico package, adding detailed sections on requirements, installation, Xcode configuration, API references, and usage examples. The review feedback suggests making the API signatures in the reference table more precise and idiomatic, and adjusting the async stream example to obtain the stream before starting the scan to prevent missing initial discovery events.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| | `startScanning()` | `async throws` | Starts a scan. Idempotent while already scanning. Throws `BonjourPicoError` if the browser can't start. | | ||
| | `stopScanning()` | `async` | Stops scanning and clears `endpoints`. | | ||
| | `endpointStream()` | `async -> AsyncThrowingStream<[BonjourEndpoint], Error>` | An async-sequence alternative to the observable `endpoints` (see below). | | ||
| | `wake(_:)` | `async throws` | Sends a Wake-on-LAN magic packet to an endpoint (see [Wake-on-LAN](#wake-on-lan)). | | ||
| | `init(configuration:)` | — | Creates the facade, optionally with a custom discovery configuration (see [Advanced configuration](#advanced-configuration)). | |
There was a problem hiding this comment.
The signatures in the BonjourPico API table can be made more precise and idiomatic to Swift by including the parameter types and explicit return types where applicable. This helps developers understand the API contract at a glance.
There was a problem hiding this comment.
Fixed in cab85a0. The API table now lists full idiomatic declarations — func startScanning() async throws, func wake(_ endpoint: BonjourEndpoint) async throws, func endpointStream() async -> AsyncThrowingStream<[BonjourEndpoint], Error>, private(set) var endpoints: [BonjourEndpoint], init(configuration: BonjourDiscoveryActor.Configuration = .init()), etc. — instead of bare type fragments, so the contract (and the read-only/observable nature of the properties) is clear at a glance.
Generated by Claude Code
| try await bonjourPico.startScanning() | ||
|
|
||
| let stream = await bonjourPico.endpointStream() | ||
| for try await endpoints in stream { | ||
| print("Discovered \(endpoints.count) server(s)") | ||
| } |
There was a problem hiding this comment.
To ensure that no initial discovery events are missed, it is more robust to obtain the async stream before calling startScanning(). Although the underlying implementation replays the current state upon subscription, setting up the stream first is a safer and more standard pattern for working with asynchronous streams.
| try await bonjourPico.startScanning() | |
| let stream = await bonjourPico.endpointStream() | |
| for try await endpoints in stream { | |
| print("Discovered \(endpoints.count) server(s)") | |
| } | |
| let stream = await bonjourPico.endpointStream() | |
| try await bonjourPico.startScanning() | |
| for try await endpoints in stream { | |
| print("Discovered \(endpoints.count) server(s)") | |
| } |
There was a problem hiding this comment.
Fixed in cab85a0 — adopted the suggestion. The example now obtains the stream before startScanning(). As you noted, the actor replays the current snapshot on subscribe (and yields full snapshots, not deltas, so nothing is actually missed either way), but subscribing first is the safer, more standard pattern and makes the example a good template for streams in general. Added a one-line comment explaining the ordering.
Generated by Claude Code
- BonjourPico API table now shows full idiomatic declarations (func/var/init with parameter names, types, and explicit return types) instead of bare type fragments. - endpointStream() example now obtains the stream before startScanning(), the safer/standard async-sequence pattern. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011r15hkWqTdtMV4TeAgrqn8
|
@codex review Docs-only PR (README expansion) — CI is green on Generated by Claude Code |
|
Codex Review: Didn't find any major issues. 🎉 Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
2 participants
Summary
Docs-only. The README already described the v2 async/observable API at a high level; this fills the gaps for someone adopting the package. No source changes — every API reference was checked against the merged
mainsource.What changed
Package.swiftsnippet), a note thatimport BonjourPicore-exports the core discovery types, and the version-pinning caveat (see below). The former "Xcode Settings" is folded into a Configure your Xcode project subsection (now also mentions the iOS multicast entitlement).BonjourPicoAPI table, aBonjourEndpointfield table, anendpointStream()async-sequence example, notes on automatic retry / the observablestate, advancedConfiguration, and theBonjourPicoErrorsurface.id(ServerIdentifier) contract.Note on versioning
The repo's only tag is
0.0.1(pre-v2), so the install instructions depend on themainbranch. Since v2 is breaking, cutting a2.0.0release would let consumers pin a version — happy to help with that separately.Testing
Documentation only; no build/behavior impact.
🤖 Generated with Claude Code
https://claude.ai/code/session_011r15hkWqTdtMV4TeAgrqn8
Generated by Claude Code