docs: Minor docs improvements & fixing doc linting errors

Author: artrixdotdev

crates/libtortillas/src/engine/mod.rs

@@ -27,7 +27,7 @@ use crate::{
 
 pub(crate) enum EngineMessage {
    #[allow(dead_code)]
-   /// Creates a new [Torrent](crate::torrent::Torrent) actor.
+   /// Creates a new [Torrent] actor.
    Torrent(Box<MetaInfo>),
    /// Handles an incoming peer connection. The peer has been neither handshaked
    /// nor verified at this point.
@@ -57,7 +57,7 @@ pub struct Engine {
    torrents: Arc<DashMap<InfoHash, ActorRef<Torrent>>>,
    /// Our peer ID, used for the following actors "below" the engine.
    ///
-   /// - [Torrent](crate::torrent::Torrent)
+   /// - [Torrent]
    /// - [PeerActor](crate::peer::PeerActor)
    /// - [TrackerActor](crate::tracker::TrackerActor)
    ///

crates/libtortillas/src/torrent/mod.rs

@@ -79,11 +79,17 @@ impl Torrent {
       }
    }
 
-   /// Utility function that will create the peer actor and add it to the
-   /// torrent.
+   /// Spawns a new [`PeerActor`] for the given [`Peer`] and adds it to the
+   /// torrent's peer set.
    ///
-   /// This function calls [Self::handshake_peer] if no stream is provided to
-   /// retrieve the peer id
+   /// - If a [`PeerStream`] is provided, a handshake is sent immediately.
+   /// - If no stream is provided, this function attempts to connect to the peer
+   ///   and performs the handshake sequence inline.
+   ///
+   /// The peer is ignored if:
+   /// - The handshake fails,
+   /// - The peer ID matches our own, or
+   /// - The peer already exists in the peer set.
    #[instrument(skip(self, peer, stream), fields(%self, peer = ?peer.socket_addr()))]
    fn append_peer(&self, mut peer: Peer, stream: Option<PeerStream>) {
       let info_hash = Arc::new(self.info_hash());

crates/libtortillas/src/tracker/mod.rs

@@ -203,7 +203,7 @@ impl Actor for TrackerActor {
    type Args = (Tracker, PeerId, UdpServer, SocketAddr, ActorRef<Torrent>);
    type Error = TrackerActorError;
 
-   /// Unlike the [`PeerActor`](crate::protocol::PeerActor), there are no
+   /// Unlike the [`PeerActor`](crate::peer::PeerActor), there are no
    /// prerequisites to calling this function. In other words, the tracker is
    /// not expected to be connected when this function is called.
    async fn on_start(state: Self::Args, _: ActorRef<Self>) -> Result<Self, Self::Error> {
@@ -285,7 +285,7 @@ pub(crate) enum TrackerMessage {
    /// requests are made on an interval.
    Announce,
    /// Gets the statistics of the tracker via
-   /// [`tracker.stats()`](TrackerEnum::stats)
+   /// [`tracker.stats()`](TrackerInstance::stats)
    GetStats,
 }
 

crates/libtortillas/src/tracker/udp.rs

@@ -710,8 +710,8 @@ impl UdpTracker {
       }
    }
 
-   /// Uses [send_message](UdpServer::send_message) to send a message and
-   /// [recv_retry][UdpTracker::recv_retry] to receive the message.
+   /// Uses [`UdpServer::send_message`] to send a message and
+   /// [`UdpTracker::to_retry_error`] to receive the message.
    #[instrument(skip(self, message), fields(
         tracker_uri = %self.uri,
         connection_id = ?self.get_connection_id()