Fix rustdoc comments for turn (#487)

Author: Subhra264

turn/src/allocation/allocation_manager.rs

@@ -12,13 +12,13 @@ use super::*;
 use crate::error::*;
 use crate::relay::*;
 
-// ManagerConfig a bag of config params for Manager.
+/// `ManagerConfig` a bag of config params for `Manager`.
 pub struct ManagerConfig {
     pub relay_addr_generator: Box<dyn RelayAddressGenerator + Send + Sync>,
     pub alloc_close_notify: Option<mpsc::Sender<AllocationInfo>>,
 }
 
-// Manager is used to hold active allocations
+/// `Manager` is used to hold active allocations.
 pub struct Manager {
     allocations: AllocationMap,
     reservations: Arc<Mutex<HashMap<String, u16>>>,
@@ -27,7 +27,7 @@ pub struct Manager {
 }
 
 impl Manager {
-    // creates a new instance of Manager.
+    /// Creates a new [`Manager`].
     pub fn new(config: ManagerConfig) -> Self {
         Manager {
             allocations: Arc::new(Mutex::new(HashMap::new())),
@@ -37,7 +37,7 @@ impl Manager {
         }
     }
 
-    // Close closes the manager and closes all allocations it manages
+    /// Closes this [`manager`] and closes all [`Allocation`]s it manages.
     pub async fn close(&self) -> Result<()> {
         let allocations = self.allocations.lock().await;
         for a in allocations.values() {
@@ -46,8 +46,8 @@ impl Manager {
         Ok(())
     }
 
-    // Returns the information about the all [`Allocation`]s associated with
-    // the specified [`FiveTuple`]s.
+    /// Returns the information about the all [`Allocation`]s associated with
+    /// the specified [`FiveTuple`]s.
     pub async fn get_allocations_info(
         &self,
         five_tuples: Option<Vec<FiveTuple>>,
@@ -73,13 +73,13 @@ impl Manager {
         infos
     }
 
-    // get_allocation fetches the allocation matching the passed FiveTuple
+    /// Fetches the [`Allocation`] matching the passed [`FiveTuple`].
     pub async fn get_allocation(&self, five_tuple: &FiveTuple) -> Option<Arc<Allocation>> {
         let allocations = self.allocations.lock().await;
         allocations.get(five_tuple).map(Arc::clone)
     }
 
-    // create_allocation creates a new allocation and starts relaying
+    /// Creates a new [`Allocation`] and starts relaying.
     pub async fn create_allocation(
         &self,
         five_tuple: FiveTuple,
@@ -123,7 +123,7 @@ impl Manager {
         Ok(a)
     }
 
-    // delete_allocation removes an allocation
+    /// Removes an [`Allocation`].
     pub async fn delete_allocation(&self, five_tuple: &FiveTuple) {
         let allocation = self.allocations.lock().await.remove(five_tuple);
 
@@ -134,7 +134,7 @@ impl Manager {
         }
     }
 
-    /// Deletes the [`Allocation`]s according to the specified `username`.
+    /// Deletes the [`Allocation`]s according to the specified username `name`.
     pub async fn delete_allocations_by_username(&self, name: &str) {
         let to_delete = {
             let mut allocations = self.allocations.lock().await;
@@ -163,7 +163,7 @@ impl Manager {
         .await;
     }
 
-    // create_reservation stores the reservation for the token+port
+    /// Stores the reservation for the token+port.
     pub async fn create_reservation(&self, reservation_token: String, port: u16) {
         let reservations = Arc::clone(&self.reservations);
         let reservation_token2 = reservation_token.clone();
@@ -183,13 +183,13 @@ impl Manager {
         reservations.insert(reservation_token, port);
     }
 
-    // get_reservation returns the port for a given reservation if it exists
+    /// Returns the port for a given reservation if it exists.
     pub async fn get_reservation(&self, reservation_token: &str) -> Option<u16> {
         let reservations = self.reservations.lock().await;
         reservations.get(reservation_token).copied()
     }
 
-    // get_random_even_port returns a random un-allocated udp4 port
+    /// Returns a random un-allocated udp4 port.
     pub async fn get_random_even_port(&self) -> Result<u16> {
         let (_, addr) = self.relay_addr_generator.allocate_conn(true, 0).await?;
         Ok(addr.port())

turn/src/allocation/channel_bind.rs

@@ -10,8 +10,9 @@ use tokio::time::{Duration, Instant};
 use super::*;
 use crate::proto::channum::*;
 
-// ChannelBind represents a TURN Channel
-// https://tools.ietf.org/html/rfc5766#section-2.5
+/// `ChannelBind` represents a TURN Channel.
+///
+/// https://tools.ietf.org/html/rfc5766#section-2.5.
 #[derive(Clone)]
 pub struct ChannelBind {
     pub(crate) peer: SocketAddr,
@@ -22,7 +23,7 @@ pub struct ChannelBind {
 }
 
 impl ChannelBind {
-    // NewChannelBind creates a new ChannelBind
+    /// Creates a new [`ChannelBind`]
     pub fn new(number: ChannelNumber, peer: SocketAddr) -> Self {
         ChannelBind {
             number,

turn/src/allocation/five_tuple.rs

@@ -6,12 +6,12 @@ use std::net::{Ipv4Addr, SocketAddr};
 
 use crate::proto::*;
 
-// FiveTuple is the combination (client IP address and port, server IP
-// address and port, and transport protocol (currently one of UDP,
-// TCP, or TLS)) used to communicate between the client and the
-// server.  The 5-tuple uniquely identifies this communication
-// stream.  The 5-tuple also uniquely identifies the Allocation on
-// the server.
+/// `FiveTuple` is the combination (client IP address and port, server IP
+/// address and port, and transport protocol (currently one of UDP,
+/// TCP, or TLS)) used to communicate between the client and the
+/// server.  The 5-tuple uniquely identifies this communication
+/// stream.  The 5-tuple also uniquely identifies the Allocation on
+/// the server.
 #[derive(PartialEq, Eq, Clone, Copy, Hash)]
 pub struct FiveTuple {
     pub protocol: Protocol,

turn/src/allocation/mod.rs

@@ -50,7 +50,7 @@ pub struct AllocationInfo {
 }
 
 impl AllocationInfo {
-    // Creates a new `AllocationInfo`
+    /// Creates a new [`AllocationInfo`].
     pub fn new(
         five_tuple: FiveTuple,
         username: String,
@@ -65,8 +65,8 @@ impl AllocationInfo {
     }
 }
 
-// Allocation is tied to a FiveTuple and relays traffic
-// use create_allocation and get_allocation to operate
+/// `Allocation` is tied to a FiveTuple and relays traffic
+/// use create_allocation and get_allocation to operate.
 pub struct Allocation {
     protocol: Protocol,
     turn_socket: Arc<dyn Conn + Send + Sync>,
@@ -90,7 +90,7 @@ fn addr2ipfingerprint(addr: &SocketAddr) -> String {
 }
 
 impl Allocation {
-    // creates a new instance of NewAllocation.
+    /// Creates a new [`Allocation`].
     pub fn new(
         turn_socket: Arc<dyn Conn + Send + Sync>,
         relay_socket: Arc<dyn Conn + Send + Sync>,
@@ -118,13 +118,13 @@ impl Allocation {
         }
     }
 
-    // has_permission gets the Permission from the allocation
+    /// Checks the Permission for the `addr`.
     pub async fn has_permission(&self, addr: &SocketAddr) -> bool {
         let permissions = self.permissions.lock().await;
         permissions.get(&addr2ipfingerprint(addr)).is_some()
     }
 
-    // add_permission adds a new permission to the allocation
+    /// Adds a new [`Permission`] to this [`Allocation`].
     pub async fn add_permission(&self, mut p: Permission) {
         let fingerprint = addr2ipfingerprint(&p.addr);
 
@@ -145,14 +145,14 @@ impl Allocation {
         }
     }
 
-    // remove_permission removes the net.Addr's fingerprint from the allocation's permissions
+    /// Removes the `addr`'s fingerprint from this [`Allocation`]'s permissions.
     pub async fn remove_permission(&self, addr: &SocketAddr) -> bool {
         let mut permissions = self.permissions.lock().await;
         permissions.remove(&addr2ipfingerprint(addr)).is_some()
     }
 
-    // add_channel_bind adds a new ChannelBind to the allocation, it also updates the
-    // permissions needed for this ChannelBind
+    /// Adds a new [`ChannelBind`] to this [`Allocation`], it also updates the
+    /// permissions needed for this [`ChannelBind`].
     pub async fn add_channel_bind(&self, mut c: ChannelBind, lifetime: Duration) -> Result<()> {
         {
             if let Some(addr) = self.get_channel_addr(&c.number).await {
@@ -197,19 +197,19 @@ impl Allocation {
         Ok(())
     }
 
-    // remove_channel_bind removes the ChannelBind from this allocation by id
+    /// Removes the [`ChannelBind`] from this [`Allocation`] by `number`.
     pub async fn remove_channel_bind(&self, number: ChannelNumber) -> bool {
         let mut channel_bindings = self.channel_bindings.lock().await;
         channel_bindings.remove(&number).is_some()
     }
 
-    // get_channel_addr gets the ChannelBind's addr
+    /// Gets the [`ChannelBind`]'s address by `number`.
     pub async fn get_channel_addr(&self, number: &ChannelNumber) -> Option<SocketAddr> {
         let channel_bindings = self.channel_bindings.lock().await;
         channel_bindings.get(number).map(|cb| cb.peer)
     }
 
-    // GetChannelByAddr gets the ChannelBind's number from this allocation by net.Addr
+    /// Gets the [`ChannelBind`]'s number from this [`Allocation`] by `addr`.
     pub async fn get_channel_number(&self, addr: &SocketAddr) -> Option<ChannelNumber> {
         let channel_bindings = self.channel_bindings.lock().await;
         for cb in channel_bindings.values() {
@@ -220,7 +220,7 @@ impl Allocation {
         None
     }
 
-    // Close closes the allocation
+    /// Closes the [`Allocation`].
     pub async fn close(&self) -> Result<()> {
         if self.closed.load(Ordering::Acquire) {
             return Err(Error::ErrClosed);
@@ -305,7 +305,7 @@ impl Allocation {
         reset_tx.is_none() || self.timer_expired.load(Ordering::SeqCst)
     }
 
-    // Refresh updates the allocations lifetime
+    /// Updates the allocations lifetime.
     pub async fn refresh(&self, lifetime: Duration) {
         let reset_tx = self.reset_tx.lock().clone();
         if let Some(tx) = reset_tx {

turn/src/allocation/permission.rs

@@ -8,9 +8,10 @@ use super::*;
 
 pub(crate) const PERMISSION_TIMEOUT: Duration = Duration::from_secs(5 * 60);
 
-// Permission represents a TURN permission. TURN permissions mimic the address-restricted
-// filtering mechanism of NATs that comply with [RFC4787].
-// https://tools.ietf.org/html/rfc5766#section-2.3
+/// `Permission` represents a TURN permission. TURN permissions mimic the address-restricted
+/// filtering mechanism of NATs that comply with [RFC4787].
+///
+/// https://tools.ietf.org/html/rfc5766#section-2.3
 pub struct Permission {
     pub(crate) addr: SocketAddr,
     pub(crate) permissions: Option<Arc<Mutex<HashMap<String, Permission>>>>,
@@ -19,7 +20,7 @@ pub struct Permission {
 }
 
 impl Permission {
-    // NewPermission create a new Permission
+    /// Creates a new [`Permission`].
     pub fn new(addr: SocketAddr) -> Self {
         Permission {
             addr,

turn/src/auth/mod.rs

@@ -15,7 +15,7 @@ pub trait AuthHandler {
     fn auth_handle(&self, username: &str, realm: &str, src_addr: SocketAddr) -> Result<Vec<u8>>;
 }
 
-// generate_long_term_credentials can be used to create credentials valid for [duration] time
+/// `generate_long_term_credentials()` can be used to create credentials valid for `duration` time/
 pub fn generate_long_term_credentials(
     shared_secret: &str,
     duration: Duration,
@@ -35,7 +35,7 @@ fn long_term_credentials(username: &str, shared_secret: &str) -> String {
     BASE64_STANDARD.encode(password)
 }
 
-// generate_auth_key is a convenience function to easily generate keys in the format used by AuthHandler
+/// A convenience function to easily generate keys in the format used by [`AuthHandler`].
 pub fn generate_auth_key(username: &str, realm: &str, password: &str) -> Vec<u8> {
     let s = format!("{username}:{realm}:{password}");
 
@@ -70,7 +70,7 @@ impl AuthHandler for LongTermAuthHandler {
 }
 
 impl LongTermAuthHandler {
-    // https://tools.ietf.org/search/rfc5389#section-10.2
+    /// https://tools.ietf.org/search/rfc5389#section-10.2
     pub fn new(shared_secret: String) -> Self {
         LongTermAuthHandler { shared_secret }
     }

turn/src/client/binding.rs

@@ -48,7 +48,7 @@ impl Binding {
         self.refreshed_at
     }
 }
-// Thread-safe Binding map
+/// Thread-safe Binding map.
 #[derive(Default)]
 pub(crate) struct BindingManager {
     chan_map: HashMap<u16, String>,