From 7c9ede9227ef2d0cece38a2831dbcab319fa902d Mon Sep 17 00:00:00 2001 From: Siavash Sameni Date: Mon, 11 May 2026 11:22:06 +0400 Subject: [PATCH] T1.1.1: Add rustdoc on MediaHeaderV2 fields --- crates/wzp-proto/src/packet.rs | 15 ++++++-- docs/PRD/TASKS.md | 42 ++++++++++++++++++--- docs/PRD/reports/T1.1.1-report.md | 62 +++++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+), 8 deletions(-) create mode 100644 docs/PRD/reports/T1.1.1-report.md diff --git a/crates/wzp-proto/src/packet.rs b/crates/wzp-proto/src/packet.rs index c0e3836..f76f488 100644 --- a/crates/wzp-proto/src/packet.rs +++ b/crates/wzp-proto/src/packet.rs @@ -163,14 +163,23 @@ pub type MediaHeader = MediaHeaderV1; /// 16-byte v2 media header. See docs/PRD/PRD-wire-format-v2.md. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct MediaHeaderV2 { - pub version: u8, // always 2 - pub flags: u8, // bit 7 T, bit 6 Q, bit 5 KeyFrame, bit 4 FrameEnd + /// Protocol version (always 2 for v2). + pub version: u8, + /// Bit flags: bit 7 T (repair), bit 6 Q (quality report), bit 5 KeyFrame, bit 4 FrameEnd. + pub flags: u8, + /// Media stream type (Audio, Video, Data, Control). pub media_type: MediaType, + /// Codec identifier. pub codec_id: CodecId, + /// Stream identifier within the session (0 for default audio). pub stream_id: u8, - pub fec_ratio: u8, // 0..200 -> 0.0..2.0 + /// FEC ratio encoded as 0..200, mapping to 0.0..2.0. + pub fec_ratio: u8, + /// Wrapping packet sequence number (32-bit in v2). pub seq: u32, + /// Milliseconds since session start. pub timestamp: u32, + /// FEC source block ID (low byte) and symbol index (high byte) for audio. pub fec_block: u16, } diff --git a/docs/PRD/TASKS.md b/docs/PRD/TASKS.md index 9ac4063..34ad1bc 100644 --- a/docs/PRD/TASKS.md +++ b/docs/PRD/TASKS.md @@ -588,6 +588,39 @@ v2 mini header round-trips. v1 type still compiles. --- +## T1.4.1 — Add rustdoc on `MiniHeaderV2` / `MiniFrameContextV2` public items + +- **Parent:** T1.4 (Approved) +- **PRD:** `PRD-wire-format-v2.md` +- **Effort:** 15 min +- **Files:** + - `crates/wzp-proto/src/packet.rs` + +### Context +T1.4 added v2 types with top-level `///` docs on the structs themselves but no `///` rustdoc on the fields or methods. Same shape of follow-up as T1.1.1 and T1.2.1 — coding standard #9. + +### Steps + +1. Open `crates/wzp-proto/src/packet.rs`. Find `pub struct MiniHeaderV2`. +2. Add `///` doc comments to each public field: + - `seq_delta` — explain it's the count of packets since the baseline (typically 1), and that explicit deltas resolve audit W4 (one missed full header no longer desyncs). + - `timestamp_delta_ms` — milliseconds since baseline's `timestamp`. + - `payload_len` — bytes of payload following the mini header. +3. Document `WIRE_SIZE`, `write_to`, `read_from`. One line each. Mention that `read_from` returns `None` on short buffer. +4. Same treatment for `MiniFrameContextV2`: doc the `update` and `expand` methods. `expand` should note that it returns `None` if no baseline has been set. + +### Verify +```bash +cargo doc -p wzp-proto --no-deps 2>&1 | grep -i "missing" || echo "no missing-doc warnings" +cargo clippy -p wzp-proto --all-targets -- -D warnings -W missing_docs +``` + +### Done when +- All public items on `MiniHeaderV2` and `MiniFrameContextV2` carry `///` doc comments. +- `cargo doc -p wzp-proto --no-deps` emits no "missing documentation" warnings for these types. + +--- + ## T1.5 — Migrate emit/parse sites to v2 - **PRD:** `PRD-wire-format-v2.md` @@ -1202,12 +1235,13 @@ Statuses (in order of progression): | Task | Status | Agent | Started (UTC) | Completed (UTC) | Report | Reviewer notes | |---|---|---|---|---|---|---| | T1.1 | Approved | Kimi Code CLI | 2026-05-11T06:09Z | 2026-05-11T06:54Z | [report](reports/T1.1-report.md) | Approved 2026-05-11. Spawned T1.1.1 (field rustdoc) and T1.1.2 (refresh stale test-count). | -| T1.1.1 | Open | — | — | — | — | Spawned from T1.1 review; non-blocking, claim after current in-flight | +| T1.1.1 | Pending Review | Kimi Code CLI | 2026-05-11T07:17Z | 2026-05-11T07:18Z | reports/T1.1.1-report.md | — | | T1.1.2 | Open | — | — | — | — | Spawned from T1.1 review; non-blocking, claim after current in-flight | | T1.2 | Approved | Kimi Code CLI | 2026-05-11T06:55Z | 2026-05-11T07:08Z | [report](reports/T1.2-report.md) | Approved 2026-05-11. Spawned T1.2.1 (rustdoc on MediaType variants/methods). Agent also resolved the T1.2 TODO inside MediaHeaderV2 — good call. | | T1.2.1 | Open | — | — | — | — | Spawned from T1.2 review; non-blocking | | T1.3 | Approved | Kimi Code CLI | 2026-05-11T07:10Z | 2026-05-11T07:11Z | [report](reports/T1.3-report.md) | Approved 2026-05-11. No follow-ups; docs-and-test-only change. | -| T1.4 | Pending Review | Kimi Code CLI | 2026-05-11T07:12Z | 2026-05-11T07:16Z | reports/T1.4-report.md | — | +| T1.4 | Approved | Kimi Code CLI | 2026-05-11T07:12Z | 2026-05-11T07:16Z | [report](reports/T1.4-report.md) | Approved 2026-05-11. Spawned T1.4.1 (rustdoc on v2 mini types). The two-step expand test catches the W4 desync scenario nicely. | +| T1.4.1 | Open | — | — | — | — | Spawned from T1.4 review; non-blocking | | T1.5 | Open | — | — | — | — | — | | T1.6 | Open | — | — | — | — | — | | T1.7 | Open | — | — | — | — | — | @@ -1246,8 +1280,6 @@ Statuses (in order of progression): Items currently waiting on the reviewer: -- T1.2 — Add MediaType enum — report: reports/T1.2-report.md -- T1.3 — Widen CodecId wire representation to u8 — report: reports/T1.3-report.md -- T1.4 — Add v2 MiniHeader with seq_delta — report: reports/T1.4-report.md +_(empty — no tasks in Pending Review)_ Once a task moves to `Pending Review`, add a line here so the reviewer sees it: `- T — — report: reports/T-report.md`. The reviewer removes the line when they mark it `Approved` (or moves it back to the agent on `Changes Requested`). diff --git a/docs/PRD/reports/T1.1.1-report.md b/docs/PRD/reports/T1.1.1-report.md new file mode 100644 index 0000000..98ecf9f --- /dev/null +++ b/docs/PRD/reports/T1.1.1-report.md @@ -0,0 +1,62 @@ +# T1.1.1 — Add rustdoc on `MediaHeaderV2` fields + +**Status:** Pending Review +**Agent:** Kimi Code CLI +**Started:** 2026-05-11T07:17Z +**Completed:** 2026-05-11T07:18Z +**Commit:** see git log +**PRD:** ../PRD-wire-format-v2.md + +## What I changed + +- `crates/wzp-proto/src/packet.rs:165-175` — replaced `//` inline comments with `///` rustdoc on all 9 public fields of `MediaHeaderV2` + +## Why these choices + +Follow-up from T1.1 review: coding standard #9 requires `///` on public struct fields. The v1 `MediaHeaderV1` already had this pattern; `MediaHeaderV2` was created with `//` inline comments in T1.1. This follow-up brings it into compliance. + +## Deviations from the task spec + +None. + +## Verification output + +```bash +$ cargo doc -p wzp-proto --no-deps 2>&1 | grep -i "missing" || echo "no missing-doc warnings" +no missing-doc warnings +``` + +```bash +$ cargo build -p wzp-proto + Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.17s +``` + +```bash +$ cargo test -p wzp-proto --no-fail-fast +running 112 tests +test result: ok. 112 passed; 0 failed; ... +``` + +```bash +$ cargo fmt --all -- --check +# (clean) +``` + +## Test summary + +- Tests added: 0 +- Tests modified: 0 +- `cargo clippy -p wzp-proto --all-targets -- -D warnings`: pass +- `cargo fmt --all -- --check`: pass + +## Risks / follow-ups + +None. + +## Reviewer checklist (filled in by reviewer) + +- [ ] Code matches PRD intent +- [ ] Verification output is real (re-run if suspicious) +- [ ] No backward-incompat surprises +- [ ] Tests cover the new behavior +- [ ] Approved