Documentate

1 files changed, 27 insertions, 10 deletions

diff --git a/src/proto.rs b/src/proto.rs
index 58c914e..b044280 100644
--- a/src/proto.rs
+++ b/src/proto.rs
@@ -16,19 +16,36 @@ use crate::error::*;
 
 use kuska_handshake::async_std::{BoxStreamRead, BoxStreamWrite, TokioCompat};
 
-const MAX_CHUNK_SIZE: usize = 0x4000;
+/// Priority of a request (click to read more about priorities).
+///
+/// This priority value is used to priorize messages
+/// in the send queue of the client, and their responses in the send queue of the
+/// server. Lower values mean higher priority.
+///
+/// This mechanism is usefull for messages bigger than the maximum chunk size
+/// (set at `0x4000` bytes), such as large file transfers.
+/// In such case, all of the messages in the send queue with the highest priority
+/// will take turns to send individual chunks, in a round-robin fashion.
+/// Once all highest priority messages are sent successfully, the messages with
+/// the next highest priority will begin being sent in the same way.
+///
+/// The same priority value is given to a request and to its associated response.
+pub type RequestPriority = u8;
 
-pub mod prio {
-	pub const HIGH: u8 = 0x20;
-	pub const NORMAL: u8 = 0x40;
-	pub const BACKGROUND: u8 = 0x80;
+/// Priority class: high
+pub const PRIO_HIGH: RequestPriority = 0x20;
+/// Priority class: normal
+pub const PRIO_NORMAL: RequestPriority = 0x40;
+/// Priority class: background
+pub const PRIO_BACKGROUND: RequestPriority = 0x80;
+/// Priority: primary among given class
+pub const PRIO_PRIMARY: RequestPriority = 0x00;
+/// Priority: secondary among given class (ex: `PRIO_HIGH || PRIO_SECONDARY`)
+pub const PRIO_SECONDARY: RequestPriority = 0x01;
 
-	pub const PRIMARY: u8 = 0x00;
-	pub const SECONDARY: u8 = 0x01;
-}
+const MAX_CHUNK_SIZE: usize = 0x4000;
 
-pub type RequestID = u16;
-pub type RequestPriority = u8;
+pub(crate) type RequestID = u16;
 
 struct SendQueueItem {
 	id: RequestID,