From 52605f43d0bb132d816b388bc59c396853d29c4e Mon Sep 17 00:00:00 2001 From: Wayland Yang Date: Fri, 29 May 2026 16:54:44 +0800 Subject: [PATCH] fix(docs): clear all rustdoc errors under -D warnings Full-workspace audit (cargo doc --document-private-items + RUSTDOCFLAGS=-D warnings) turned up 16+ unresolved-link / unclosed-HTML-tag errors. None are runtime bugs but they break the published rustdoc: - 2 fresh errors from PR #190's snapshot_vmstate_only doc comment: `[snapshot_to]` / `[snapshot_diff_to]` intra-doc links didn't resolve because rustdoc needs the `Self::` prefix when pointing at sibling methods. Use `Self::snapshot_to`. - 11+ pre-existing errors in crates/forkd-cli/src/main.rs: angle-bracketed CLI placeholders (``, ``, ``, ``, ``, ``) were treated as unclosed HTML tags. Wrap the affected subcommand-listing block in a `text` code fence; individually backtick the remaining placeholders in arg docs (`/tmp/forkd-parent-/`, `~/.local/share/forkd/snapshots//`, etc.). - 1 error: bare `[:ro]` after `HOST_FILE:GUEST_PATH` parsed as an intra-doc link with empty target. Wrap the whole format string in backticks. - 1 error: bare `https://forkd-hub.deeplethe.com.` got flagged "this URL is not a hyperlink". Wrap in angle brackets so rustdoc treats it as an autolink. - 1 error: `[`DESIGN-v0.4.md`]` in the kvm-uffd-wp PoC was a dangling intra-doc link. Switch to plain prose reference. - 1 error: angle brackets in hub.rs MetaJson doc comment for parent_tag. Verified: `cargo doc -D warnings` exit 0, fmt/clippy/test all still pass (85 tests, 0 failures). --- crates/forkd-cli/src/hub.rs | 2 +- crates/forkd-cli/src/main.rs | 17 ++++++++++------- crates/forkd-vmm/src/lib.rs | 6 +++--- experiments/v0.4-kvm-uffd-wp-poc/src/main.rs | 2 +- 4 files changed, 15 insertions(+), 12 deletions(-) diff --git a/crates/forkd-cli/src/hub.rs b/crates/forkd-cli/src/hub.rs index 04226b4..52d2c96 100644 --- a/crates/forkd-cli/src/hub.rs +++ b/crates/forkd-cli/src/hub.rs @@ -44,7 +44,7 @@ pub struct Manifest { pub created_at: String, /// forkd version that wrote this pack. pub forkd_version: String, - /// If set, this is a diff snapshot rooted at . Reserved for M2.1. + /// If set, this is a diff snapshot rooted at ``. Reserved for M2.1. #[serde(default, skip_serializing_if = "Option::is_none")] pub parent_tag: Option, /// Per-file metadata (path inside the pack, size, sha256). diff --git a/crates/forkd-cli/src/main.rs b/crates/forkd-cli/src/main.rs index be5fba5..f020257 100644 --- a/crates/forkd-cli/src/main.rs +++ b/crates/forkd-cli/src/main.rs @@ -1,14 +1,17 @@ //! `forkd` — CLI entrypoint. //! //! Subcommands: +//! +//! ```text //! forkd snapshot --tag --kernel --rootfs //! forkd fork --tag --n //! forkd pack --tag [--out ] (Snapshot Hub) //! forkd unpack [--tag ] (Snapshot Hub) //! forkd pull [--tag ] (Snapshot Hub) //! forkd images (Snapshot Hub) +//! ``` //! -//! Snapshots live under $XDG_DATA_HOME/forkd/snapshots//. +//! Snapshots live under `$XDG_DATA_HOME/forkd/snapshots//`. mod bench; mod doctor; @@ -43,7 +46,7 @@ enum Cmd { /// `--from-sandbox`, snapshot a running child sandbox into a new /// tag via the controller daemon (sandbox branching). Snapshot { - /// Name of the snapshot. Becomes ~/.local/share/forkd/snapshots//. + /// Name of the snapshot. Becomes `~/.local/share/forkd/snapshots//`. /// With `--from-sandbox`, leave unset to let the daemon generate /// `branch--`. #[arg(long)] @@ -97,7 +100,7 @@ enum Cmd { #[arg(long)] keep_workdir: bool, /// Persistent volume to attach to every child of this snapshot. - /// Format: HOST_FILE:GUEST_PATH[:ro]. Repeatable for up to 24 + /// Format: `HOST_FILE:GUEST_PATH[:ro]`. Repeatable for up to 24 /// volumes (vdb..vdy). The host file must be an existing ext4 /// image (create one with `mkfs.ext4 /var/lib/forkd/vol/.img`). /// Use volumes for pip caches, model weights, agent scratch space — @@ -305,7 +308,7 @@ enum Cmd { /// Tag of the local snapshot to pack. #[arg(long)] tag: String, - /// Output file. Default: ./.forkd-snapshot.tar.zst + /// Output file. Default: `./.forkd-snapshot.tar.zst` #[arg(long, short)] out: Option, /// Human description recorded in the manifest. Optional. @@ -343,8 +346,8 @@ enum Cmd { /// Overwrite an existing local snapshot of the same tag. #[arg(long)] force: bool, - /// Hub base URL for short-form targets. Default: env FORKD_HUB_URL - /// or https://forkd-hub.deeplethe.com. + /// Hub base URL for short-form targets. Default: env `FORKD_HUB_URL` + /// or . #[arg(long, env = "FORKD_HUB_URL")] hub: Option, }, @@ -522,7 +525,7 @@ enum ParentAction { Build { /// Docker image (e.g. `python:3.12-slim`, `ubuntu:24.04`). image: String, - /// Output ext4 file (default: ./.ext4). + /// Output ext4 file (default: `./.ext4`). #[arg(long, short)] output: Option, /// Image size in MiB (default 1536). diff --git a/crates/forkd-vmm/src/lib.rs b/crates/forkd-vmm/src/lib.rs index a6e1fb1..cfc72b4 100644 --- a/crates/forkd-vmm/src/lib.rs +++ b/crates/forkd-vmm/src/lib.rs @@ -953,9 +953,9 @@ impl Vm { /// (forkd does this via the `WpBranch` async-copy path on memfd + /// MAP_SHARED). `memory` and `volumes` are NOT written by this call /// — they're attached to the returned [`Snapshot`] so the caller - /// gets the same record shape it would from [`snapshot_to`] / - /// [`snapshot_diff_to`] and can hand it off to the post-pause copy - /// pipeline without reconstructing it. + /// gets the same record shape it would from [`Self::snapshot_to`] / + /// [`Self::snapshot_diff_to`] and can hand it off to the post-pause + /// copy pipeline without reconstructing it. /// /// Requires the vendored Firecracker fork /// (`deeplethe/firecracker:forkd-v0.4-mem-backend-shared-v1.12`); stock diff --git a/experiments/v0.4-kvm-uffd-wp-poc/src/main.rs b/experiments/v0.4-kvm-uffd-wp-poc/src/main.rs index 15b794c..7ebc214 100644 --- a/experiments/v0.4-kvm-uffd-wp-poc/src/main.rs +++ b/experiments/v0.4-kvm-uffd-wp-poc/src/main.rs @@ -1,6 +1,6 @@ //! v0.4 Phase 2 PoC — does UFFD_WP catch KVM guest writes through EPT? //! -//! Answers open question #1 in [`DESIGN-v0.4.md`]: when a guest accesses +//! Answers open question #1 in `DESIGN-v0.4.md` (at the repo root): when a guest accesses //! memory via `KVM_RUN` (and therefore through EPT/NPT, not the host MMU), //! does write-protection armed on the host VMA still produce a userspace //! fault?