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

@@ -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
+/// <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>
 fn getobject_override_headers(
 	overrides: GetObjectOverrides,
 	resp: &mut http::response::Builder,

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)
+	/// <https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/#db_engine>
 	#[structopt(short = "i")]
 	input_path: PathBuf,
 	/// Input database engine (lmdb or sqlite; limited by db engines

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: <full-node-id>@<ip>:<port>
+	/// Host to connect to for admin operations, in the format: `<full-node-id>@<ip>:<port>`
 	#[structopt(short = "h", long = "rpc-host", env = "GARAGE_RPC_HOST")]
 	pub rpc_host: Option<String>,
 

src/net/message.rs

@@ -100,9 +100,9 @@ pub trait Message: Serialize + for<'de> Deserialize<'de> + Send + Sync + 'static
 
 // ----
 
-/// The Req<M> is a helper object used to create requests and attach them
+/// The `Req<M>` 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<M> is cheaply cloneable to allow the request to be sent to different
+/// `Req<M>` 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<M: Message> {
 	pub(crate) msg: Arc<M>,
@@ -260,7 +260,7 @@ where
 
 // ----
 
-/// The Resp<M> represents a full response from a RPC that may have
+/// The `Resp<M>` represents a full response from a RPC that may have
 /// an attached stream.
 pub struct Resp<M: Message> {
 	pub(crate) _phantom: PhantomData<M>,
@@ -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

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 <pubkey>@<host>:<port> format, pubkey = full-length node ID)
+	/// Request to connect to a specific node (in `<pubkey>@<host>:<port>` format, pubkey = full-length node ID)
 	Connect(String),
 	/// Advertise Garage status. Answered with another AdvertiseStatus.
 	/// Exchanged with every node on a regular basis.

src/table/gc.rs

@@ -339,12 +339,11 @@ impl<F: TableSchema, R: TableReplication> Worker for GcWorker<F, R> {
 /// such entry in the db
 ///
 /// Format of an entry:
-/// - key =    8 bytes: timestamp of tombstone
+/// - key =    8 bytes: timestamp of tombstone (used to implement GC delay)
-///                     (used to implement GC delay)
+///   n bytes: key in the main data table
-///            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
+///   for verification purpose, because we don't want to delete
-///            things that aren't tombstones
+///   things that aren't tombstones
 pub(crate) struct GcTodoEntry {
 	tombstone_timestamp: u64,
 	key: Vec<u8>,

src/util/crdt/crdt.rs

@@ -26,14 +26,14 @@ pub trait Crdt {
 	fn merge(&mut self, other: &Self);
 }
 
-/// Option<T> implements Crdt for any type T, even if T doesn't implement CRDT itself: when
+/// `Option<T>` 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<T> instead with this impl, ambiguity
+/// deterministic) choice between the two.  When using an `Option<T>` 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)

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: <https://docs.aws.amazon.com/AmazonS3/latest/userguide/IndexDocumentSupport.html>
 fn path_to_keys(
 	path: &str,
 	index: &str,