docs: add some docs

src/codec/frame.rs

@@ -12,6 +12,28 @@ use super::AsyncSocket;
 use crate::packet::connected::{FramesMut, FramesRef};
 use crate::packet::{unconnected, Packet};
 
+/// `Framed` is a base structure for socket communication.
+/// In this project, it wraps an asynchronous UDP socket and implements the
+/// [`Stream`](futures::stream::Stream) and [`Sink`](futures::sink::Sink) traits.
+/// This allows for reading and writing RakNet frames over the socket.
+/// It supports receiving both unconnected and connected packets, but can only send unconnected
+/// packets. This design separates the offline and online packet handlers.
+///
+/// Properties:
+///
+/// * `socket`: The underlying socket that is being wrapped.
+/// * `max_mtu`: [maximum transmission unit](https://en.wikipedia.org/wiki/Maximum_transmission_unit),
+/// used to pre-allocate the capacity for both the `rd` and `wr` byte buffers
+/// * `rd`: a buffer for storing incoming data read from the socket.
+/// * `wr`: a buffer for writing bytes
+/// * `out_addr`: The socket address to which the data will be sent
+/// * `flushed`: a boolean flag that indicates whether the data has been sent to the peer, and the
+///   `wr` buffer has been cleared
+/// * `is_readable`: a boolean flag indicates whether data has been read from the peer and written
+///   into the `rd` buffer. When `true`, it signifies that the data is ready for frame packet
+///   decoding and will be passed to the upper layer for further processing.
+/// * `current_addr`: the address of the current peer
+/// * `decode_span`, `read_span`: two spans for tracking encoding and decoding.
 pub(crate) struct Framed<T> {
     socket: T,
     max_mtu: usize,

src/lib.rs

@@ -58,6 +58,9 @@ use std::net::SocketAddr;
 
 use bytes::Bytes;
 
+/// The `Role` enum is used to identify the `Client` and `Server`, and it stores their GUID.
+/// The GUID is a globally unique identifier that is not affected by changes to IP address or port.
+/// It is application-defined and ensures unique identification.
 #[derive(Debug, Clone, Copy)]
 enum Role {
     Client { guid: u64 },

src/link.rs

@@ -17,7 +17,26 @@ use crate::{Peer, Role};
 /// Shared link between stream and sink
 pub(crate) type SharedLink = Arc<TransferLink>;
 
-/// Transfer data and task between stream and sink.
+/// The `TransferLink` is an visitor structure that temporarily holds various types of transfer
+/// link data, such as received `AckOrNack`, sequences of pending response sequence numbers, and
+/// packets ready to send like `unconnected::Packet` and `FrameBody`.
+/// It provides methods for compressing sequence numbers into `AckOrNack` as well as access to other
+/// data within the link.
+///
+/// Properties:
+///
+/// * `incoming_ack`: the received ACK packet.
+/// * `incoming_nack`:  the received NACK packet.
+/// * `forward_waking`: the flag is set to `true` when the `OutgoingGuard` is closed,
+/// and there are still reliable packets awaiting ACK (needing resend).
+/// In this state, the close operation will sleep until an ACK is received to wake it,
+/// after which the flag will be reset to `false`.
+/// * `outgoing_ack`: Pending ACK packets to be sent.
+/// * `outgoing_nack`: Pending NACK packets to be sent.
+/// * `unconnected`: data related to unconnected packets awaiting processing.
+/// * `frame_body`: data for the frame body that is yet to be handled.
+/// * `role`: [`Role`]
+/// * `peer`: [`Peer`]
 pub(crate) struct TransferLink {
     // incoming ack with receive timestamp
     incoming_ack: ConcurrentQueue<(AckOrNack, Instant)>,
@@ -173,7 +192,16 @@ impl TransferLink {
     }
 }
 
-/// A route for incoming packets
+/// `Route` is an intermediary structure that wraps a `TransferLink`, providing the functionality to
+/// `deliver` different types of data frames.
+///
+/// Properties:
+///
+/// * `router_tx`: `Route` create an asynchronous channel, splitting it into a sender and a
+///   receiver, with the receiver being returned in the `new` method. This is the sender part of the
+///   asynchronous channel.
+/// * `link`: be wrapped [`TransferLink`]
+/// * `seq_read`:the next expected sequence number for incoming frames on this route
 pub(crate) struct Route {
     router_tx: Sender<FrameSet<FramesMut>>,
     link: SharedLink,

src/packet/connected/ack.rs

@@ -30,7 +30,12 @@ impl std::fmt::Debug for AckOrNack {
 }
 
 impl AckOrNack {
-    /// Extend a packet from a sorted sequence numbers iterator based on mtu.
+    /// This function implements **Sequence Number Compression** on an `Iterator<u24>`. Consecutive
+    /// sequence numbers are grouped into `Record::Range`, while non-consecutive sequence
+    /// numbers are stored as `Record::Single`. This approach reduces the data payload size.
+    ///
+    /// - A `Record::Range` consumes 7 bytes.
+    /// - A `Record::Single` consumes 4 bytes.
     pub(crate) fn extend_from<I: Iterator<Item = u24>>(
         mut sorted_seq_nums: I,
         mut mtu: u16,

src/server/handler/offline.rs

@@ -27,14 +27,43 @@ pub(crate) struct Config {
     pub(crate) max_pending: usize,
 }
 
+/// Implements a simple `OfflineHandler` state machine to process sink requests.
+/// - When in the `Listening` state, no additional processing is done.
+/// - When in the `SendingPrepare` state, the enum holds the packet to be sent and the target address.
+///   It will call the underlying `Framed::poll_ready` and `Framed::start_send` to prepare and send the data.
+///   After that, the state is set to `SendingFlush`.
+/// - When in the `SendingFlush` state, it calls the underlying `Framed::poll_flush` to flush the data 
+///   and then resets the state back to `Listening`.
 enum OfflineState {
     Listening,
     SendingPrepare(Option<(unconnected::Packet, SocketAddr)>),
     SendingFlush,
 }
 
 pin_project! {
-    /// OfflineHandler takes the codec frame and perform offline handshake.
+    /// `OfflineHandler` is a server handler that implements the RakNet offline handshake protocol.
+    /// It acts as an upper layer processor for [`Framed`](crate::codec::frame::Framed).
+    /// `OfflineHandler` implements the [`Stream`](futures::stream::Stream) interface and handles the responses
+    /// for data packets such as `UnconnectedPing`, `OpenConnectionRequest1`, and
+    /// `OpenConnectionRequest2`. For the specific protocol sequence, please refer to
+    /// [RakNet Protocol Documentation](https://github.com/vp817/RakNetProtocolDoc?tab=readme-ov-file#server).
+    ///
+    /// Properties:
+    ///
+    /// * `frame`: [`Framed`](crate::codec::frame::Framed) is responsible for decoding raw data
+    /// from the UDP socket into RakNet frames.
+    /// * `config`: stores various transmission configurations, specifically refer in [`Config`].
+    /// * `pending`: A half-connected queue implemented using [`lru::LruCache`].
+    /// At this point, the connection is in the OpenConnectionRequest1 stage,
+    /// and it will be popped out during the OpenConnectionRequest2
+    /// or when the connection is disconnected.
+    /// * `connected`: A `HashMap<SocketAddr, Peer>` that caches connections 
+    /// in the OpenConnectionRequest2 stage and is cleaned up on disconnection. 
+    /// The `connected` map is used to check if a `Peer` has completed the connection 
+    /// from the socket.
+    /// * `state`: [`OfflineState`]
+    /// * `role`: [`Role`]
+    /// * `read_span`: A trace span.
     pub(crate) struct OfflineHandler<F> {
         #[pin]
         frame: F,