docs: add missing backticks in documentation

this improve readability of documentation.
enable associated clippy lint `doc_markdown`

src/model/admin_token_table.rs

@@ -73,7 +73,7 @@ impl Crdt for AdminApiTokenScope {
 
 impl AdminApiToken {
 	/// Create a new admin API token.
-	/// Returns the AdminApiToken object, which contains the hashed bearer token,
+	/// Returns the `AdminApiToken` object, which contains the hashed bearer token,
 	/// as well as the plaintext bearer token.
 	pub fn new(name: &str) -> (Self, String) {
 		use argon2::{

src/model/bucket_table.rs

@@ -35,7 +35,7 @@ mod v08 {
 		/// Map of aliases that are or have been given to this bucket
 		/// in the global namespace
 		/// (not authoritative: this is just used as an indication to
-		/// map back to aliases when doing ListBuckets)
+		/// map back to aliases when doing `ListBuckets`)
 		pub aliases: crdt::LwwMap<String, bool>,
 		/// Map of aliases that are or have been given to this bucket
 		/// in namespaces local to keys
@@ -148,7 +148,7 @@ mod v2 {
 		/// Map of aliases that are or have been given to this bucket
 		/// in the global namespace
 		/// (not authoritative: this is just used as an indication to
-		/// map back to aliases when doing ListBuckets)
+		/// map back to aliases when doing `ListBuckets`)
 		pub aliases: crdt::LwwMap<String, bool>,
 		/// Map of aliases that are or have been given to this bucket
 		/// in namespaces local to keys
@@ -241,7 +241,7 @@ impl AutoCrdt for BucketQuotas {
 }
 
 impl BucketParams {
-	/// Create an empty BucketParams with no authorized keys and no website access
+	/// Create an empty `BucketParams` with no authorized keys and no website access
 	fn new() -> Self {
 		BucketParams {
 			creation_date: now_msec(),

src/model/helper/bucket.rs

@@ -79,7 +79,7 @@ impl<'a> BucketHelper<'a> {
 	/// aliases directly using the data provided in the `api_key` parameter.
 	/// As a consequence, it does not provide read-after-write guarantees.
 	///
-	/// In case no such bucket is found, this function returns a NoSuchBucket error.
+	/// In case no such bucket is found, this function returns a `NoSuchBucket` error.
 	#[allow(clippy::ptr_arg)]
 	pub fn resolve_bucket_fast(
 		&self,
@@ -147,7 +147,7 @@ impl<'a> BucketHelper<'a> {
 	///
 	/// - this function does quorum reads to ensure consistency.
 	/// - this function fetches the Key entry from the key table to ensure up-to-date data
-	/// - this function returns None if the bucket is not found, instead of HelperError::NoSuchBucket
+	/// - this function returns None if the bucket is not found, instead of `HelperError::NoSuchBucket`
 	#[allow(clippy::ptr_arg)]
 	pub async fn resolve_bucket(
 		&self,

src/model/helper/locked.rs

@@ -17,13 +17,13 @@ use crate::helper::key::KeyHelper;
 use crate::key_table::*;
 use crate::permission::BucketKeyPerm;
 
-/// A LockedHelper is the mandatory struct to hold when doing operations
+/// A `LockedHelper` is the mandatory struct to hold when doing operations
 /// that modify access keys or bucket aliases. This structure takes
 /// a lock to a unit value that is in the globally-shared Garage struct.
 ///
 /// This avoid several concurrent requests to modify the list of buckets
 /// and aliases at the same time, ending up in inconsistent states.
-/// This DOES NOT FIX THE FUNDAMENTAL ISSUE as CreateBucket requests handled
+/// This DOES NOT FIX THE FUNDAMENTAL ISSUE as `CreateBucket` requests handled
 /// by different API nodes can still break the cluster, but it is a first
 /// fix that allows consistency to be maintained if all such requests are
 /// directed to a single node, which is doable for many deployments.
@@ -167,7 +167,7 @@ impl<'a> LockedHelper<'a> {
 	}
 
 	/// Ensures a bucket does not have a certain global alias.
-	/// Contrarily to unset_global_bucket_alias, this does not
+	/// Contrarily to `unset_global_bucket_alias`, this does not
 	/// fail on any condition other than:
 	/// - bucket cannot be found (its fine if it is in deleted state)
 	/// - alias cannot be found (its fine if it points to nothing or
@@ -335,7 +335,7 @@ impl<'a> LockedHelper<'a> {
 	}
 
 	/// Ensures a bucket does not have a certain local alias.
-	/// Contrarily to unset_local_bucket_alias, this does not
+	/// Contrarily to `unset_local_bucket_alias`, this does not
 	/// fail on any condition other than:
 	/// - bucket cannot be found (its fine if it is in deleted state)
 	/// - key cannot be found (its fine if alias in key points to nothing

src/model/k2v/causality.rs

@@ -1,9 +1,9 @@
-//! Implements a CausalContext, which is a set of timestamps for each
+//! Implements a `CausalContext`, which is a set of timestamps for each
 //! node -- a vector clock --, indicating that the versions with
 //! timestamps <= these numbers have been seen and can be
 //! overwritten by a subsequent write.
 //!
-//! The textual representation of a CausalContext, which we call a
+//! The textual representation of a `CausalContext`, which we call a
 //! "causality token", is used in the API and must be sent along with
 //! each write or delete operation to indicate the previously seen
 //! versions that we want to overwrite or delete.

src/model/k2v/item_table.rs

@@ -56,7 +56,7 @@ mod v08 {
 pub use v08::*;
 
 impl K2VItem {
-	/// Creates a new K2VItem when no previous entry existed in the db
+	/// Creates a new `K2VItem` when no previous entry existed in the db
 	pub fn new(bucket_id: Uuid, partition_key: String, sort_key: String) -> Self {
 		Self {
 			partition: K2VItemPartition {
@@ -67,7 +67,7 @@ impl K2VItem {
 			items: BTreeMap::new(),
 		}
 	}
-	/// Updates a K2VItem with a new value or a deletion event
+	/// Updates a `K2VItem` with a new value or a deletion event
 	pub fn update(
 		&mut self,
 		this_node: Uuid,

src/model/k2v/seen.rs

@@ -1,4 +1,4 @@
-//! Implements a RangeSeenMarker, a data type used in the PollRange API
+//! Implements a `RangeSeenMarker`, a data type used in the `PollRange` API
 //! to indicate which items in the range have already been seen
 //! and which have not been seen yet.
 //!

src/model/key_table.rs

@@ -27,7 +27,7 @@ mod v08 {
 	/// Configuration for a key
 	#[derive(PartialEq, Eq, Clone, Debug, Serialize, Deserialize)]
 	pub struct KeyParams {
-		/// The secret_key associated (immutable)
+		/// The `secret_key` associated (immutable)
 		pub secret_key: String,
 
 		/// Name for the key
@@ -73,7 +73,7 @@ mod v2 {
 		/// Key's creation date, if known (older versions of Garage didn't keep track
 		/// of this information)
 		pub created: Option<u64>,
-		/// The secret_key associated (immutable)
+		/// The `secret_key` associated (immutable)
 		pub secret_key: String,
 
 		/// Name for the key

src/model/s3/mpu_table.rs

@@ -31,12 +31,12 @@ mod v09 {
 		/// The timestamp at which the multipart upload was created
 		pub timestamp: u64,
 		/// Is this multipart upload deleted
-		/// The MultipartUpload is marked as deleted as soon as the
+		/// The `MultipartUpload` is marked as deleted as soon as the
 		/// multipart upload is either completed or aborted
 		pub deleted: crdt::Bool,
 		/// List of uploaded parts, key = (part number, timestamp)
 		/// In case of retries, all versions for each part are kept
-		/// Everything is cleaned up only once the MultipartUpload is marked deleted
+		/// Everything is cleaned up only once the `MultipartUpload` is marked deleted
 		pub parts: crdt::Map<MpuPartKey, MpuPart>,
 
 		// Back link to bucket+key so that we can find the object this mpu
@@ -58,9 +58,9 @@ mod v09 {
 	/// The version of an uploaded part
 	#[derive(PartialEq, Eq, Clone, Debug, Serialize, Deserialize)]
 	pub struct MpuPart {
-		/// Links to a Version in VersionTable
+		/// Links to a Version in `VersionTable`
 		pub version: Uuid,
-		/// ETag of the content of this part (known only once done uploading)
+		/// `ETag` of the content of this part (known only once done uploading)
 		pub etag: Option<String>,
 		/// Checksum requested by x-amz-checksum-algorithm
 		#[serde(default)]

src/model/s3/object_table.rs

@@ -249,7 +249,7 @@ mod v010 {
 	#[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, Serialize, Deserialize)]
 	pub enum ObjectVersionEncryption {
 		SseC {
-			/// Encrypted serialized ObjectVersionInner struct.
+			/// Encrypted serialized `ObjectVersionInner` struct.
 			/// This is never compressed, just encrypted using AES256-GCM.
 			#[serde(with = "serde_bytes")]
 			inner: Vec<u8>,
@@ -460,7 +460,7 @@ mod v2 {
 	#[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, Serialize, Deserialize)]
 	pub enum ObjectVersionEncryption {
 		SseC {
-			/// Encrypted serialized ObjectVersionInner struct.
+			/// Encrypted serialized `ObjectVersionInner` struct.
 			/// This is never compressed, just encrypted using AES256-GCM.
 			#[serde(with = "serde_bytes")]
 			inner: Vec<u8>,
@@ -480,7 +480,7 @@ mod v2 {
 	}
 
 	/// Vector of headers, as tuples of the format (header name, header value)
-	/// Note: checksum can be Some(_) with checksum_type = None for objects that
+	/// Note: checksum can be Some(_) with `checksum_type` = None for objects that
 	/// have been migrated from Garage version before v2.0, as the distinction between
 	/// full-object and composite checksums was not implemented yet.
 	#[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, Serialize, Deserialize)]
@@ -665,9 +665,9 @@ impl ObjectVersion {
 
 	/// Is the object version currently being uploaded
 	///
-	/// matches only multipart uploads if check_multipart is Some(true)
-	/// matches only non-multipart uploads if check_multipart is Some(false)
-	/// matches both if check_multipart is None
+	/// matches only multipart uploads if `check_multipart` is Some(true)
+	/// matches only non-multipart uploads if `check_multipart` is Some(false)
+	/// matches both if `check_multipart` is None
 	pub fn is_uploading(&self, check_multipart: Option<bool>) -> bool {
 		match &self.state {
 			ObjectVersionState::Uploading { multipart, .. } => {
@@ -763,9 +763,9 @@ pub enum ObjectFilter {
 	IsData,
 	/// Is the object version currently being uploaded
 	///
-	/// matches only multipart uploads if check_multipart is Some(true)
-	/// matches only non-multipart uploads if check_multipart is Some(false)
-	/// matches both if check_multipart is None
+	/// matches only multipart uploads if `check_multipart` is Some(true)
+	/// matches only non-multipart uploads if `check_multipart` is Some(false)
+	/// matches both if `check_multipart` is None
 	IsUploading { check_multipart: Option<bool> },
 }
 

src/model/snapshot.rs

@@ -20,7 +20,7 @@ static SNAPSHOT_MUTEX: Mutex<()> = Mutex::new(());
 
 // ================ snapshotting logic =====================
 
-/// Run snapshot_metadata in a blocking thread and async await on it
+/// Run `snapshot_metadata` in a blocking thread and async await on it
 pub async fn async_snapshot_metadata(garage: &Arc<Garage>) -> Result<(), Error> {
 	let garage = garage.clone();
 	let worker = tokio::task::spawn_blocking(move || snapshot_metadata(&garage));