[channels] Add doc strings

3 files changed, 41 insertions, 9 deletions

diff --git a/src/client.rs b/src/client.rs
index 8a1eee5..6416395 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -301,6 +301,13 @@ impl Connection {
         }
     }
 
+    /// Opens a channel of the requested [ChannelType] and returns its [ChannelId].
+    ///
+    /// By default, when starting a [Connection]], Quinnet creates 1 channel instance of each [ChannelType], each with their own [ChannelId]. Among those, there is a `default` channel which will be used when you don't specify the channel. At startup, this default channel is a [ChannelType::OrderedReliable] channel.
+    ///
+    /// If no channels were previously opened, the opened channel will be the new default channel.
+    ///
+    /// Can fail if the Connection is closed.
     pub fn open_channel(&mut self, channel_type: ChannelType) -> Result<ChannelId, QuinnetError> {
         let channel_id = get_channel_id_from_type(channel_type, || {
             self.last_gen_id += 1;
@@ -312,10 +319,11 @@ impl Connection {
         }
     }
 
-    /// Immediately prevents new messages from being sent on the channel and signal the channel to closes all its background tasks.
-    /// Before trully closing, the channel will wait for all buffered messages to be properly sent according to the channel type.
+    /// Closes the channel with the corresponding [ChannelId].
+    ///
+    /// No new messages will be able to be sent on this channel, however, the channel will properly try to send all the messages that were previously pushed to it, according to its [ChannelType], before fully closing.
     ///
-    /// If called on the default channel, set default channel to None.
+    /// If the closed channel is the current default channel, the default channel gets set to `None`.
     ///
     /// Can fail if the [ChannelId] is unknown, or if the channel is already closed.
     pub fn close_channel(&mut self, channel_id: ChannelId) -> Result<(), QuinnetError> {
diff --git a/src/server.rs b/src/server.rs
index 50568f9..7b94eac 100644
--- a/src/server.rs
+++ b/src/server.rs
@@ -438,6 +438,7 @@ impl Endpoint {
         }
     }
 
+    /// Same as disconnect_client but errors are logged instead of returned
     pub fn try_disconnect_client(&mut self, client_id: ClientId) {
         match self.disconnect_client(client_id) {
             Ok(_) => (),
@@ -455,6 +456,13 @@ impl Endpoint {
         Ok(())
     }
 
+    /// Opens a channel of the requested [ChannelType] and returns its [ChannelId].
+    ///
+    /// By default, when starting an [Endpoint], Quinnet creates 1 channel instance of each [ChannelType], each with their own [ChannelId]. Among those, there is a `default` channel which will be used when you don't specify the channel. At startup, this default channel is a [ChannelType::OrderedReliable] channel.
+    ///
+    /// If no channels were previously opened, the opened channel will be the new default channel.
+    ///
+    /// Can fail if the Endpoint is closed.
     pub fn open_channel(&mut self, channel_type: ChannelType) -> Result<ChannelId, QuinnetError> {
         let channel_id = get_channel_id_from_type(channel_type, || {
             self.last_gen_id += 1;
@@ -466,6 +474,13 @@ impl Endpoint {
         }
     }
 
+    /// Closes the channel with the corresponding [ChannelId].
+    ///
+    /// No new messages will be able to be sent on this channel, however, the channel will properly try to send all the messages that were previously pushed to it, according to its [ChannelType], before fully closing.
+    ///
+    /// If the closed channel is the current default channel, the default channel gets set to `None`.
+    ///
+    /// Can fail if the [ChannelId] is unknown, or if the channel is already closed.
     pub fn close_channel(&mut self, channel_id: ChannelId) -> Result<(), QuinnetError> {
         match self.channels.remove(&channel_id) {
             true => {
@@ -481,12 +496,12 @@ impl Endpoint {
         }
     }
 
-    /// Set the default channel
+    /// Set the default channel via its [ChannelId]
     pub fn set_default_channel(&mut self, channel_id: ChannelId) {
         self.default_channel = Some(channel_id);
     }
 
-    /// Get the default Channel Id
+    /// Get the default [ChannelId]
     pub fn get_default_channel(&self) -> Option<ChannelId> {
         self.default_channel
     }
diff --git a/src/shared/channel.rs b/src/shared/channel.rs
index 4860b49..7b62d17 100644
--- a/src/shared/channel.rs
+++ b/src/shared/channel.rs
@@ -14,20 +14,29 @@ pub(crate) type MultiChannelId = u64;
 
 #[derive(Debug, Copy, Clone)]
 pub enum ChannelType {
+    /// An OrderedReliable channel ensures that messages sent are delivered, and are processed by the receiving end in the same order as they were sent.
     OrderedReliable,
+    /// An UnorderedReliable channel ensures that messages sent are delivered, but they may be delivered out of order.
     UnorderedReliable,
+    /// Channel which transmits messages as unreliable and unordered datagrams (may be lost or delivered out of order).
+    ///
+    /// The maximum allowed size of a datagram may change over the lifetime of a connection according to variation in the path MTU estimate. This is guaranteed to be a little over a kilobyte at minimum.
     Unreliable,
 }
 
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
 pub enum ChannelId {
-    /// An OrderedReliable channel ensures that messages sent are delivered, and are processed by the receiving end in the same order as they were sent.
+    /// There may be more than one OrderedReliable channel instance. This may be useful to avoid some Head of line blocking (<https://en.wikipedia.org/wiki/Head-of-line_blocking>) issues.
+    ///
+    /// See [ChannelType::OrderedReliable] for more information.
     OrderedReliable(MultiChannelId),
-    /// An UnorderedReliable channel ensures that messages sent are delivered, but they may be delivered out of order.
+    /// One `UnorderedReliable` channel instance is enough since messages are not ordered on those, in fact even if you tried to create more, Quinnet would just reuse the existing one. This is why you can directly use this [ChannelId::UnorderedReliable] when sending messages.
+    ///
+    /// See [ChannelType::UnorderedReliable] for more information.
     UnorderedReliable,
-    /// Channel which transmits messages as unreliable and unordered datagrams (may be lost or delivered out of order).
+    /// One `Unreliable` channel instance is enough since messages are not ordered on those, in fact even if you tried to create more, Quinnet would just reuse the existing one. This is why you can directly use this [ChannelId::Unreliable] when sending messages.
     ///
-    /// The maximum allowed size of a datagram may change over the lifetime of a connection according to variation in the path MTU estimate. This is guaranteed to be a little over a kilobyte at minimum.
+    /// See [ChannelType::Unreliable] for more information.
     Unreliable,
 }