From 577ebb9f46c0e545f9fb28148065c216da82d3fa Mon Sep 17 00:00:00 2001 From: Ofer Chen Date: Wed, 20 May 2026 18:54:20 +0300 Subject: [PATCH] docs(protocol): drop restatement comments and apply rustdoc to public items Strip a handful of restating comments inside test bodies that echo the next line of code (e.g., "Write file size", "Read it back", "Verify roundtrip", "Verify all data was written", "Read back", "Test with all three bytes", trailing "// Same time"/"// Same UID" tags). Upstream rsync citations, varint/MSG_*/multiplex-frame WHY notes, the multiplex::helpers SAFETY comment, and all rustdoc on public items are preserved unchanged. Files touched: 7. Lines removed: 16. Lines added: 0 (one restatement was collapsed into a one-line note about NDX delta state). No semantic changes; no new #[allow(...)] attributes; the crate already enforces #![deny(missing_docs)] so no additional rustdoc was required. --- crates/protocol/src/codec/mod.rs | 7 +------ crates/protocol/src/flist/flags.rs | 1 - crates/protocol/src/flist/write/tests/compression.rs | 8 +++----- crates/protocol/src/flist/write/tests/hardlink.rs | 1 - crates/protocol/src/wire/compressed_token/lz4_codec.rs | 3 --- crates/protocol/src/wire/compressed_token/zstd_codec.rs | 2 -- crates/protocol/src/wire/vectored.rs | 2 -- 7 files changed, 4 insertions(+), 20 deletions(-) diff --git a/crates/protocol/src/codec/mod.rs b/crates/protocol/src/codec/mod.rs index 9f1ef50e2..89197a1ca 100644 --- a/crates/protocol/src/codec/mod.rs +++ b/crates/protocol/src/codec/mod.rs @@ -218,10 +218,8 @@ mod tests { let codecs = ProtocolCodecs::for_version(32); let mut buf = Vec::new(); - // Write file size codecs.wire.write_file_size(&mut buf, 12345).unwrap(); - // Read it back let mut cursor = Cursor::new(&buf); let value = codecs.wire.read_file_size(&mut cursor).unwrap(); assert_eq!(value, 12345); @@ -234,12 +232,11 @@ mod tests { let mut codecs = ProtocolCodecs::for_version(32); let mut buf = Vec::new(); - // Write NDX values codecs.ndx.write_ndx(&mut buf, 0).unwrap(); codecs.ndx.write_ndx(&mut buf, 1).unwrap(); codecs.ndx.write_ndx(&mut buf, 5).unwrap(); - // Read them back with fresh codec state + // Fresh codec state on the reader side: NDX deltas are stateful. let mut read_codecs = ProtocolCodecs::for_version(32); let mut cursor = Cursor::new(&buf); assert_eq!(read_codecs.ndx.read_ndx(&mut cursor).unwrap(), 0); @@ -254,13 +251,11 @@ mod tests { let mut codecs = ProtocolCodecs::for_version(30); let mut buf = Vec::new(); - // Mix wire and NDX operations codecs.wire.write_file_size(&mut buf, 1000).unwrap(); codecs.ndx.write_ndx(&mut buf, 0).unwrap(); codecs.wire.write_mtime(&mut buf, 1700000000).unwrap(); codecs.ndx.write_ndx(&mut buf, 1).unwrap(); - // Read them back let mut read_codecs = ProtocolCodecs::for_version(30); let mut cursor = Cursor::new(&buf); diff --git a/crates/protocol/src/flist/flags.rs b/crates/protocol/src/flist/flags.rs index f228087ef..b36fd3d5d 100644 --- a/crates/protocol/src/flist/flags.rs +++ b/crates/protocol/src/flist/flags.rs @@ -592,7 +592,6 @@ mod tests { #[test] fn flags_from_u32() { - // Test with all three bytes let value: u32 = 0x020103; // extended16=0x02, extended=0x01, primary=0x03 let flags = FileFlags::from_u32(value); assert_eq!(flags.primary, 0x03); diff --git a/crates/protocol/src/flist/write/tests/compression.rs b/crates/protocol/src/flist/write/tests/compression.rs index 6287066c4..ff8fdc02f 100644 --- a/crates/protocol/src/flist/write/tests/compression.rs +++ b/crates/protocol/src/flist/write/tests/compression.rs @@ -20,17 +20,15 @@ fn zero_flags_varint_uses_xmit_extended_flags() { .update(b"prefix/", 0o100644, 1700000000, 1000, 1000); let mut entry = FileEntry::new_file("prefix/file.txt".into(), 100, 0o644); - entry.set_mtime(1700000000, 0); // Same time - entry.set_uid(1000); // Same UID - entry.set_gid(1000); // Same GID + entry.set_mtime(1700000000, 0); + entry.set_uid(1000); + entry.set_gid(1000); let mut buf = Vec::new(); writer.write_entry(&mut buf, &entry).unwrap(); - // Decode the first varint to check the flags value let (flags_value, _) = decode_varint(&buf).unwrap(); - // Should NOT be 0 (end marker), should be XMIT_EXTENDED_FLAGS (0x04) assert_ne!(flags_value, 0, "flags should not be zero (end marker)"); assert!( (flags_value as u32) & (XMIT_EXTENDED_FLAGS as u32) != 0 diff --git a/crates/protocol/src/flist/write/tests/hardlink.rs b/crates/protocol/src/flist/write/tests/hardlink.rs index 7196cbd4d..69810e997 100644 --- a/crates/protocol/src/flist/write/tests/hardlink.rs +++ b/crates/protocol/src/flist/write/tests/hardlink.rs @@ -411,7 +411,6 @@ fn hardlink_round_trip_with_interspersed_directories() { writer.write_entry(&mut buf, &follower).unwrap(); writer.write_end(&mut buf, None).unwrap(); - // Read back let mut cursor = Cursor::new(&buf[..]); let mut reader = FileListReader::new(protocol).with_preserve_hard_links(true); diff --git a/crates/protocol/src/wire/compressed_token/lz4_codec.rs b/crates/protocol/src/wire/compressed_token/lz4_codec.rs index ee88341e6..605de7d40 100644 --- a/crates/protocol/src/wire/compressed_token/lz4_codec.rs +++ b/crates/protocol/src/wire/compressed_token/lz4_codec.rs @@ -619,7 +619,6 @@ mod tests { block_sizes.iter().sum::(), ); - // Verify roundtrip let mut decoder = Lz4TokenDecoder::new(); let mut read_cursor = Cursor::new(&encoded); let mut result = Vec::new(); @@ -688,7 +687,6 @@ mod tests { "block match without literals should not produce DEFLATED_DATA" ); - // Verify roundtrip let mut decoder = Lz4TokenDecoder::new(); let mut cursor = Cursor::new(&encoded); let mut blocks = Vec::new(); @@ -928,7 +926,6 @@ mod tests { encoder.finish(&mut encoded).unwrap(); - // Verify roundtrip let expected: Vec = vec![b'X'; 65536 * 4]; let mut decoder = Lz4TokenDecoder::new(); let mut cursor = Cursor::new(&encoded); diff --git a/crates/protocol/src/wire/compressed_token/zstd_codec.rs b/crates/protocol/src/wire/compressed_token/zstd_codec.rs index 634179b31..f848e1c39 100644 --- a/crates/protocol/src/wire/compressed_token/zstd_codec.rs +++ b/crates/protocol/src/wire/compressed_token/zstd_codec.rs @@ -794,7 +794,6 @@ mod tests { block_sizes.iter().sum::(), ); - // Verify roundtrip let mut decoder = ZstdTokenDecoder::new().unwrap(); let mut read_cursor = Cursor::new(&encoded); let mut result = Vec::new(); @@ -870,7 +869,6 @@ mod tests { "block match without literals should not produce DEFLATED_DATA" ); - // Verify roundtrip let mut decoder = ZstdTokenDecoder::new().unwrap(); let mut cursor = Cursor::new(&encoded); let mut blocks = Vec::new(); diff --git a/crates/protocol/src/wire/vectored.rs b/crates/protocol/src/wire/vectored.rs index 678d215c4..f03f378ab 100644 --- a/crates/protocol/src/wire/vectored.rs +++ b/crates/protocol/src/wire/vectored.rs @@ -160,7 +160,6 @@ mod tests { let written = write_vectored_all(&mut writer, &buffer_refs).expect("large write succeeds"); - // Verify all data was written let mut expected = Vec::new(); for d in &data { expected.extend_from_slice(d); @@ -337,7 +336,6 @@ mod tests { let written = write_vectored_all(&mut writer, &buffer_refs).expect("large IOV write succeeds"); - // Verify all data was written let mut expected = Vec::new(); for d in &data { expected.extend_from_slice(d);