From 4a0be692b3b0c6cbccb51470e6e8ebf7336c71cf Mon Sep 17 00:00:00 2001 From: Gwen Lg Date: Sun, 14 Dec 2025 18:33:31 +0100 Subject: [PATCH] docs: various fixes in Rust code documentation - add backticks on struct doc comments lint message: unclosed HTML tag `M` - add a blanck line for proper doc formating lint message: doc list item without indentation help: if this is supposed to be its own paragraph, add a blank line help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.92.0/index.html#doc_lazy_continuation - fix hyperlink in doc + one url invalid lint message: this URL is not a hyperlink note: bare URLs are not automatically turned into clickable links - ajust space in doc lint message: doc list item overindented help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.92.0/index.html#doc_overindented_list_items --- src/api/s3/get.rs | 2 +- src/garage/cli/local/convert_db.rs | 2 +- src/garage/main.rs | 2 +- src/net/message.rs | 8 +++++--- src/rpc/system.rs | 2 +- src/table/gc.rs | 9 ++++----- src/util/crdt/crdt.rs | 4 ++-- src/web/web_server.rs | 2 +- 8 files changed, 16 insertions(+), 15 deletions(-) diff --git a/src/api/s3/get.rs b/src/api/s3/get.rs index 3c07bc2f..5854bc80 100644 --- a/src/api/s3/get.rs +++ b/src/api/s3/get.rs @@ -93,7 +93,7 @@ fn object_headers( /// Override headers according to specific query parameters, see /// section "Overriding response header values through the request" in -/// https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html +/// fn getobject_override_headers( overrides: GetObjectOverrides, resp: &mut http::response::Builder, diff --git a/src/garage/cli/local/convert_db.rs b/src/garage/cli/local/convert_db.rs index a40fb61f..6ac34ee0 100644 --- a/src/garage/cli/local/convert_db.rs +++ b/src/garage/cli/local/convert_db.rs @@ -8,7 +8,7 @@ use garage_db::*; #[derive(StructOpt, Debug)] pub struct ConvertDbOpt { /// Input database path (not the same as metadata_dir, see - /// https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/#db-engine-since-v0-8-0) + /// #[structopt(short = "i")] input_path: PathBuf, /// Input database engine (lmdb or sqlite; limited by db engines diff --git a/src/garage/main.rs b/src/garage/main.rs index b3574c49..4c54a251 100644 --- a/src/garage/main.rs +++ b/src/garage/main.rs @@ -44,7 +44,7 @@ use secrets::Secrets; about = "S3-compatible object store for self-hosted geo-distributed deployments" )] struct Opt { - /// Host to connect to for admin operations, in the format: @: + /// Host to connect to for admin operations, in the format: `@:` #[structopt(short = "h", long = "rpc-host", env = "GARAGE_RPC_HOST")] pub rpc_host: Option, diff --git a/src/net/message.rs b/src/net/message.rs index 8d7d612c..3126d144 100644 --- a/src/net/message.rs +++ b/src/net/message.rs @@ -100,9 +100,9 @@ pub trait Message: Serialize + for<'de> Deserialize<'de> + Send + Sync + 'static // ---- -/// The Req is a helper object used to create requests and attach them +/// The `Req` is a helper object used to create requests and attach them /// a stream of data. If the stream is a fixed Bytes and not a ByteStream, -/// Req is cheaply cloneable to allow the request to be sent to different +/// `Req` is cheaply cloneable to allow the request to be sent to different /// peers (Clone will panic if the stream is a ByteStream). pub struct Req { pub(crate) msg: Arc, @@ -260,7 +260,7 @@ where // ---- -/// The Resp represents a full response from a RPC that may have +/// The `Resp` represents a full response from a RPC that may have /// an attached stream. pub struct Resp { pub(crate) _phantom: PhantomData, @@ -458,11 +458,13 @@ impl ReqEnc { } /// Encoding for responses into a ByteStream: +/// /// IF SUCCESS: /// - 0: u8 /// - msg len: u32 /// - msg [u8; ..] /// - the attached stream as the rest of the encoded stream +/// /// IF ERROR: /// - message length + 1: u8 /// - error code: u8 diff --git a/src/rpc/system.rs b/src/rpc/system.rs index d7e0741a..6adb13a1 100644 --- a/src/rpc/system.rs +++ b/src/rpc/system.rs @@ -55,7 +55,7 @@ pub const SYSTEM_RPC_PATH: &str = "garage_rpc/system.rs/SystemRpc"; pub enum SystemRpc { /// Response to successful advertisements Ok, - /// Request to connect to a specific node (in @: format, pubkey = full-length node ID) + /// Request to connect to a specific node (in `@:` format, pubkey = full-length node ID) Connect(String), /// Advertise Garage status. Answered with another AdvertiseStatus. /// Exchanged with every node on a regular basis. diff --git a/src/table/gc.rs b/src/table/gc.rs index 4d775fa9..1ef7d471 100644 --- a/src/table/gc.rs +++ b/src/table/gc.rs @@ -339,12 +339,11 @@ impl Worker for GcWorker { /// such entry in the db /// /// Format of an entry: -/// - key = 8 bytes: timestamp of tombstone -/// (used to implement GC delay) -/// n bytes: key in the main data table +/// - key = 8 bytes: timestamp of tombstone (used to implement GC delay) +/// n bytes: key in the main data table /// - value = hash of the table entry to delete (the tombstone) -/// for verification purpose, because we don't want to delete -/// things that aren't tombstones +/// for verification purpose, because we don't want to delete +/// things that aren't tombstones pub(crate) struct GcTodoEntry { tombstone_timestamp: u64, key: Vec, diff --git a/src/util/crdt/crdt.rs b/src/util/crdt/crdt.rs index fdf63084..f2cfd464 100644 --- a/src/util/crdt/crdt.rs +++ b/src/util/crdt/crdt.rs @@ -26,14 +26,14 @@ pub trait Crdt { fn merge(&mut self, other: &Self); } -/// Option implements Crdt for any type T, even if T doesn't implement CRDT itself: when +/// `Option` implements Crdt for any type T, even if T doesn't implement CRDT itself: when /// different values are detected, they are always merged to None. This can be used for value /// types which shoulnd't be merged, instead of trying to merge things when we know we don't want /// to merge them (which is what the AutoCrdt trait is used for most of the time). This cases /// arises very often, for example with a Lww or a LwwMap: the value type has to be a CRDT so that /// we have a rule for what to do when timestamps aren't enough to disambiguate (in a distributed /// system, anything can happen!), and with AutoCrdt the rule is to make an arbitrary (but -/// deterministic) choice between the two. When using an Option instead with this impl, ambiguity +/// deterministic) choice between the two. When using an `Option` instead with this impl, ambiguity /// cases are explicitly stored as None, which allows us to detect the ambiguity and handle it in /// the way we want. (this can only work if we are happy with losing the value when an ambiguity /// arises) diff --git a/src/web/web_server.rs b/src/web/web_server.rs index 5c2418d9..f50e4ca7 100644 --- a/src/web/web_server.rs +++ b/src/web/web_server.rs @@ -543,7 +543,7 @@ impl RoutingResult { /// When a path ends with "/", we append the index name to match traditional web server behavior /// which is also AWS S3 behavior. /// -/// Check: https://docs.aws.amazon.com/AmazonS3/latest/userguide/IndexDocumentSupport.html +/// Check: fn path_to_keys( path: &str, index: &str,