docs: full documentation audit (rustdoc + mdBook)#28
Merged
Merged
Conversation
Header, HEADER_SIZE/MAGIC/VERSION, all FLAG_* constants, HeaderError, SackRange, and the encode/decode/encode_sack/decode_sack functions had zero rustdoc despite Header and the flag constants being on VISIBILITY_POLICY.md's reference-ecosystem-pins list (must-stay-pub API). Adds a module-level //! overview plus accurate /// docs for every item, describing the real wire layout, little-endian encoding, ACK semantics, and SACK half-open range semantics. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Fixes 8 cargo-doc warnings: - hyperdht.rs:1168 broken link to connect_with_nodes -> Self::connect_with_nodes - relay_service.rs module docs: 6 broken links (HyperDhtHandle, ServerEvent, BlindRelaySession, BlindRelayServer, UdxStream::relay_to, Io) fixed with fully-qualified paths - io.rs:829 public doc on reply_to linked to a private item (Self::send_reply_deferred) -> reworded to prose/code-span, no longer a broken link Expands module-level docs, previously thin/stale relative to the rapid recent feature work: - blind_relay.rs: explains the pairing/session model, idle-session-timeout hardening (peeroxide-only, no Node precedent), and stream teardown on unpair/session-close (1:1 Node precedent). Corrects a misleading claim that the relay is "unthrottled like Node" - peeroxide does impose its own configurable (generous-by-default) limits. - relay_service.rs: documents the self-announce mechanism (announces hash(pubkey) to the DHT at startup plus a ~10min refresh so Node.js clients can discover the relay via findPeer), periodic idle-session and pairing sweep, and stream-teardown lifecycle. - lib.rs: adds relay_service to the crate-level module overview table. Documentation only, no behavior changes. cargo doc/clippy/test all clean. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
spawn()'s doc comment read like a basic direct/holepunched-only launcher and didn't mention that a swarm can be configured to pair through a blind-relay server via SwarmConfig::relay_through/relay_address. Crate- level lib.rs docs updated similarly. Documentation only, no behavior changes. cargo doc/clippy/test all clean. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…pdate README Fixes 5 pre-existing cargo-doc warnings: - chat/display.rs:87-88 [`render_to`] -> [`Self::render_to`] - chat/tui/mod.rs:76 [`install_global`] -> [`super::install_global_notice_sink`] - deaddrop/v2/keys.rs:6,8 array-index-style [i]/[0] misparsed as intra-doc links -> wrapped in code spans Fixes a real, user-facing inaccuracy found while cross-checking a new mdBook chapter against live --help output: `--idle-session-timeout` / `--relay-idle-session-timeout` help text still claimed idle-session sweeping was "not yet enforced" -- true when the flags were first added, but stale since idle-session-timeout enforcement actually shipped in peeroxide-dht 1.7.0 (sweep_idle_sessions is wired into run_relay_server's periodic sweep task). Corrected in both relay.rs and node.rs. README.md: adds the relay command to the command table (previously omitted entirely), corrects the manpage count from 9 to 10 (verified by actually running `peeroxide init --man-pages`), and clarifies that dd v2 is the current default protocol (--v1 opts into the legacy path). Documentation only, no behavior changes. cargo doc/build/clippy all clean. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ntent Closes the biggest gap found in a full documentation audit: the peeroxide node command and the entire blind-relay feature (peeroxide relay, node --relay) had zero mdBook coverage anywhere, despite being the focus of the last several development sessions. Adds: - docs/src/node/overview.md -- the peeroxide node command: what it does, basic/private-mesh/--relay usage, bootstrap resolution, flags. - docs/src/relay/overview.md -- blind relay: what "blind" means, the two ways to run one (dedicated `relay` vs courtesy `node --relay`), all configurable limits/timeouts with real defaults, how clients opt in (SwarmConfig::relay_through/relay_address, PEEROXIDE_FORCE_RELAY for cp), and a security-notes section on what a relay can/cannot observe. - docs/src/relay/architecture.md -- internals: token-pairing model, the Protomux "blind-relay" control channel, blind UDX-layer forwarding via relay_to, teardown/idle-timeout behavior (noting which parts have Node precedent and which are peeroxide-only hardening), and the relay self-announce mechanism for DHT discoverability. - SUMMARY.md/introduction.md: wired both new chapters into navigation, corrected the primary-command count (eight -> nine). Fixes: - appendices/tracing.md: the relay row said logging was "(none currently)" -- stale, relay logging is now extensive. Replaced with the real tracing targets/events across relay.rs, node.rs, relay_service.rs, and blind_relay.rs. - docs/src/node/overview.md's own idle-session-timeout flag description initially copied a stale "not yet enforced" claim from the CLI help text being fixed in the same pass -- corrected to match actual current behavior. - docs/AGENTS.md: added node/ (and the general new-command-chapter convention covering relay/) to the structure notes; verified mdbook-mermaid is still genuinely needed (real diagram usage found in several existing chapters), left that instruction as-is. mdbook build docs/ succeeds cleanly with no warnings. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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.
Summary
Full documentation audit across all 4 workspace crates (rustdoc) plus the mdBook
docs/site, following up on the recently-merged blind-relay feature (#27). Documentation only — no behavior changes.Audited via 5 parallel read-only review passes, then fixed via 9 parallel implementation passes; every change independently spot-checked afterward (doc-link fixes verified against
cargo doc, README manpage count verified against a realpeeroxide init --man-pagesrun, etc.).What changed, by commit
libudx: documented the entirenative/header.rswire-format module (Header, flag constants,SackRange, encode/decode) — previously had zero doc comments despite being onVISIBILITY_POLICY.md's "must stay pub" reference-ecosystem-pins list.peeroxide-dht: fixed all 8cargo docwarnings (7 broken intra-doc links + 1 public-doc-linking-to-private-item leak). Rewroteblind_relay.rs/relay_service.rsmodule docs to cover the pairing/session model, idle-session-timeout, stream teardown, and the relay self-announce mechanism. Corrected a misleading "unthrottled like Node" claim.peeroxide: documented relay-client support (SwarmConfig::relay_through/relay_address) inswarm.rs::spawn()and crate-level docs.peeroxide-cli: fixed 5 pre-existing broken doc links. UpdatedREADME.md(added therelaycommand to the table, fixed the manpage count 9→10, clarifiedddv2-is-default). Also fixed a real stale-help-text bug:--idle-session-timeout/--relay-idle-session-timeouthelp text still claimed idle-session sweeping was "not yet enforced" — stale since that feature actually shipped inpeeroxide-dht1.7.0.docs/): the biggest gap — added brand-newdocs/src/node/overview.mdanddocs/src/relay/{overview,architecture}.mdchapters, since thenodeandrelaycommands (including the entire blind-relay feature) had zero user-facing documentation. Fixed a staleappendices/tracing.mdclaim that relay had no logging. Wired new chapters intoSUMMARY.md/introduction.mdnavigation. Updateddocs/AGENTS.md.Testing
cargo test --workspace --lib --bins— 900 tests passingcargo clippy --workspace --all-targets -- -D warnings— cleancargo doc --workspace --no-deps— clean (only the pre-existing, unrelated bin/lib name-collision warning remains)mdbook build docs/— clean, no errorsVersions
No version bumps — pure documentation/help-text fixes, no public API or behavior changes.
Checklist
-D warnings)peeroxide-cli— the help-text correction)