docs: add missing backticks in documentation

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

src/net/bytes_buf.rs

@@ -17,7 +17,7 @@ pub struct BytesBuf {
 }
 
 impl BytesBuf {
-	/// Creates a new empty BytesBuf
+	/// Creates a new empty `BytesBuf`
 	pub fn new() -> Self {
 		Self {
 			buf: VecDeque::new(),
@@ -25,13 +25,13 @@ impl BytesBuf {
 		}
 	}
 
-	/// Returns the number of bytes stored in the BytesBuf
+	/// Returns the number of bytes stored in the `BytesBuf`
 	#[inline]
 	pub fn len(&self) -> usize {
 		self.buf_len
 	}
 
-	/// Returns true iff the BytesBuf contains zero bytes
+	/// Returns true iff the `BytesBuf` contains zero bytes
 	#[inline]
 	pub fn is_empty(&self) -> bool {
 		self.buf_len == 0
@@ -63,7 +63,7 @@ impl BytesBuf {
 		}
 	}
 
-	/// Takes at most max_len bytes from the left of the buffer
+	/// Takes at most `max_len` bytes from the left of the buffer
 	pub fn take_max(&mut self, max_len: usize) -> Bytes {
 		if self.buf_len <= max_len {
 			self.take_all()
@@ -73,7 +73,7 @@ impl BytesBuf {
 	}
 
 	/// Take exactly len bytes from the left of the buffer, returns None if
-	/// the BytesBuf doesn't contain enough data
+	/// the `BytesBuf` doesn't contain enough data
 	pub fn take_exact(&mut self, len: usize) -> Option<Bytes> {
 		if self.buf_len < len {
 			None

src/net/message.rs

@@ -101,9 +101,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
-/// a stream of data. If the stream is a fixed Bytes and not a ByteStream,
+/// 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
-/// peers (Clone will panic if the stream is a ByteStream).
+/// peers (Clone will panic if the stream is a `ByteStream`).
 pub struct Req<M: Message> {
 	pub(crate) msg: Arc<M>,
 	pub(crate) msg_ser: Option<Bytes>,
@@ -382,7 +382,7 @@ impl AttachedStream {
 
 // ---- ----
 
-/// Encoding for requests into a ByteStream:
+/// Encoding for requests into a `ByteStream`:
 /// - priority: u8
 /// - path length: u8
 /// - path: [u8; path length]
@@ -457,7 +457,7 @@ impl ReqEnc {
 	}
 }
 
-/// Encoding for responses into a ByteStream:
+/// Encoding for responses into a `ByteStream`:
 ///
 /// IF SUCCESS:
 /// - 0: u8
@@ -468,7 +468,7 @@ impl ReqEnc {
 /// IF ERROR:
 /// - message length + 1: u8
 /// - error code: u8
-/// - message: [u8; message_length]
+/// - message: [u8; `message_length`]
 pub(crate) struct RespEnc {
 	msg: Bytes,
 	stream: Option<ByteStream>,

src/net/netapp.rs

@@ -34,12 +34,12 @@ pub type NetworkKey = sodiumoxide::crypto::auth::Key;
 /// composed of 8 bytes for Netapp version and 8 bytes for client version
 pub(crate) type VersionTag = [u8; 16];
 
-/// Value of garage_net version used in the version tag
-/// We are no longer using prefix `netapp` as garage_net is forked from the netapp crate.
-/// Since Garage v1.0, we have replaced the prefix by `grgnet` (shorthand for garage_net).
+/// Value of `garage_net` version used in the version tag
+/// We are no longer using prefix `netapp` as `garage_net` is forked from the netapp crate.
+/// Since Garage v1.0, we have replaced the prefix by `grgnet` (shorthand for `garage_net`).
 pub(crate) const NETAPP_VERSION_TAG: u64 = 0x6772676e65740010; // grgnet 0x0010 (1.0)
 
-/// HelloMessage is sent by the client on a Netapp connection to indicate
+/// `HelloMessage` is sent by the client on a Netapp connection to indicate
 /// that they are also a server and ready to receive incoming connections
 /// at the specified address and port. If the client doesn't know their
 /// public address, they don't need to specify it and we look at the
@@ -57,9 +57,9 @@ impl Message for HelloMessage {
 type OnConnectHandler = Box<dyn Fn(NodeID, SocketAddr, bool) + Send + Sync>;
 type OnDisconnectHandler = Box<dyn Fn(NodeID, bool) + Send + Sync>;
 
-/// NetApp is the main class that handles incoming and outgoing connections.
+/// `NetApp` is the main class that handles incoming and outgoing connections.
 ///
-/// NetApp can be used in a stand-alone fashion or together with a peering strategy.
+/// `NetApp` can be used in a stand-alone fashion or together with a peering strategy.
 /// If using it alone, you will want to set `on_connect` and `on_disconnect` events
 /// in order to manage information about the current peer list.
 pub struct NetApp {
@@ -91,7 +91,7 @@ struct ListenParams {
 }
 
 impl NetApp {
-	/// Creates a new instance of NetApp, which can serve either as a full p2p node,
+	/// Creates a new instance of `NetApp`, which can serve either as a full p2p node,
 	/// or just as a passive client. To upgrade to a full p2p node, spawn a listener
 	/// using `.listen()`
 	///
@@ -186,7 +186,7 @@ impl NetApp {
 
 	/// Main listening process for our app. This future runs during the whole
 	/// run time of our application.
-	/// If this is not called, the NetApp instance remains a passive client.
+	/// If this is not called, the `NetApp` instance remains a passive client.
 	pub async fn listen(
 		self: Arc<Self>,
 		listen_addr: SocketAddr,

src/net/peering.rs

@@ -119,7 +119,7 @@ impl PeerInfo {
 	}
 }
 
-/// PeerConnState: possible states for our tentative connections to given peer
+/// `PeerConnState`: possible states for our tentative connections to given peer
 /// This structure is only interested in recording connection info for outgoing
 /// TCP connections
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]

src/net/recv.rs

@@ -42,8 +42,8 @@ impl Drop for Sender {
 	}
 }
 
-/// The RecvLoop trait, which is implemented both by the client and the server
-/// connection objects (ServerConn and ClientConn) adds a method `.recv_loop()`
+/// The `RecvLoop` trait, which is implemented both by the client and the server
+/// connection objects (`ServerConn` and `ClientConn`) adds a method `.recv_loop()`
 /// and a prototype of a handler for received messages `.recv_handler()` that
 /// must be filled by implementors. `.recv_loop()` receives messages in a loop
 /// according to the protocol defined above: chunks of message in progress of being

src/net/send.rs

@@ -264,8 +264,8 @@ impl DataFrame {
 	}
 }
 
-/// The SendLoop trait, which is implemented both by the client and the server
-/// connection objects (ServerConna and ClientConn) adds a method `.send_loop()`
+/// The `SendLoop` trait, which is implemented both by the client and the server
+/// connection objects (`ServerConna` and `ClientConn`) adds a method `.send_loop()`
 /// that takes a channel of messages to send and an asynchronous writer,
 /// and sends messages from the channel to the async writer, putting them in a queue
 /// before being sent and doing the round-robin sending strategy.

src/net/stream.rs

@@ -14,18 +14,18 @@ use crate::bytes_buf::BytesBuf;
 /// When sent through Netapp, the Vec may be split in smaller chunk in such a way
 /// consecutive Vec may get merged, but Vec and error code may not be reordered
 ///
-/// Items sent in the ByteStream may be errors of type `std::io::Error`.
-/// An error indicates the end of the ByteStream: a reader should no longer read
+/// Items sent in the `ByteStream` may be errors of type `std::io::Error`.
+/// An error indicates the end of the `ByteStream`: a reader should no longer read
 /// after receiving an error, and a writer should stop writing after sending an error.
 pub type ByteStream = Pin<Box<dyn Stream<Item = Packet> + Send + Sync>>;
 
-/// A packet sent in a ByteStream, which may contain either
+/// A packet sent in a `ByteStream`, which may contain either
 /// a Bytes object or an error
 pub type Packet = Result<Bytes, std::io::Error>;
 
 // ----
 
-/// A helper struct to read defined lengths of data from a BytesStream
+/// A helper struct to read defined lengths of data from a `BytesStream`
 pub struct ByteStreamReader {
 	stream: ByteStream,
 	buf: BytesBuf,
@@ -201,7 +201,7 @@ pub fn stream_asyncread(stream: ByteStream) -> impl AsyncRead + Send + Sync + 's
 	tokio_util::io::StreamReader::new(stream)
 }
 
-/// Reads all of the content of a `ByteStream` into a BytesBuf
+/// Reads all of the content of a `ByteStream` into a `BytesBuf`
 /// that contains everything
 pub async fn read_stream_to_end(mut stream: ByteStream) -> Result<BytesBuf, std::io::Error> {
 	let mut buf = BytesBuf::new();

src/net/util.rs

@@ -7,7 +7,7 @@ use tokio::sync::watch;
 
 use crate::netapp::*;
 
-/// Utility function: encodes any serializable value in MessagePack binary format
+/// Utility function: encodes any serializable value in `MessagePack` binary format
 /// using the RMP library.
 ///
 /// Field names and variant names are included in the serialization.
@@ -80,7 +80,7 @@ pub fn parse_and_resolve_peer_addr(peer: &str) -> Option<(NodeID, Vec<SocketAddr
 	Some((pubkey, hosts))
 }
 
-/// async version of parse_and_resolve_peer_addr
+/// async version of `parse_and_resolve_peer_addr`
 pub async fn parse_and_resolve_peer_addr_async(peer: &str) -> Option<(NodeID, Vec<SocketAddr>)> {
 	let delim = peer.find('@')?;
 	let (key, host) = peer.split_at(delim);