rustdocs: Doc strings for libdonet protocol definition

Preparing for #![deny(missing_docs)] crate attribute which I will
enforce for the libdonet crate once I have the rest of the documentation
down for what has been devloped so far.

libdonet/src/byte_order.rs

@@ -15,12 +15,18 @@
 // along with this program; if not, write to the Free Software Foundation,
 // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-// Detect system endianness (byte order)
+//! Utils for swapping little-endian bytes to the compiling
+//! processor's native endianness (byte order).
+
+/// Swaps 2 bytes in little endian byte order to big endian.
+/// Returns the input if the processor is little endian.
 #[cfg(target_endian = "big")]
 pub fn swap_le_16(v: u16) -> u16 {
     return (v & 0x00ff) << 8 | (v & 0xff00) >> 8;
 }
 
+/// Swaps 4 bytes in little endian byte order to big endian.
+/// Returns the input if the processor is little endian.
 #[rustfmt::skip]
 #[cfg(target_endian = "big")]
 pub fn swap_le_32(v: u32) -> u32 {
@@ -30,7 +36,10 @@ pub fn swap_le_32(v: u32) -> u32 {
         | (v & 0xff000000) >> 24;
 }
 
+/// Swaps 8 bytes in little endian byte order to big endian.
+/// Returns the input if the processor is little endian.
 #[cfg(target_endian = "big")]
+#[rustdoc::doc(hidden)]
 pub fn swap_le_64(v: u64) -> u64 {
     return (v & 0x00000000000000ff) << 56
         | (v & 0x000000000000ff00) << 40
@@ -42,16 +51,22 @@ pub fn swap_le_64(v: u64) -> u64 {
         | (v & 0xff00000000000000) >> 56;
 }
 
+/// Swaps 2 bytes in little endian byte order to big endian.
+/// Returns the input if the processor is little endian.
 #[cfg(target_endian = "little")]
 pub fn swap_le_16(v: u16) -> u16 {
     v // no need to swap bytes
 }
 
+/// Swaps 4 bytes in little endian byte order to big endian.
+/// Returns the input if the processor is little endian.
 #[cfg(target_endian = "little")]
 pub fn swap_le_32(v: u32) -> u32 {
     v
 }
 
+/// Swaps 8 bytes in little endian byte order to big endian.
+/// Returns the input if the processor is little endian.
 #[cfg(target_endian = "little")]
 pub fn swap_le_64(v: u64) -> u64 {
     v

libdonet/src/globals.rs

@@ -15,6 +15,9 @@
 // along with this program; if not, write to the Free Software Foundation,
 // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+//! Includes definitions of type aliases for Donet concepts,
+//! and the full definition of the network protocol message types.
+
 #[cfg(feature = "dcfile")]
 use crate::dcfile;
 #[cfg(feature = "dcfile")]
@@ -24,7 +27,8 @@ use std::mem;
 use std::result::Result;
 use strum_macros::EnumIter;
 
-// Type Definitions
+// ---------- Type Definitions --------- //
+
 pub type MsgType = u16;
 pub type DgSizeTag = u16;
 pub type Channel = u64;
@@ -34,17 +38,17 @@ pub type DClassId = u16;
 pub type FieldId = u16;
 pub type DCFileHash = u32; // 32-bit hash
 
-// Type Limits
+// ---------- Type Limits ---------- //
+
 pub const DG_SIZE_MAX: DgSizeTag = u16::MAX;
 pub const CHANNEL_MAX: Channel = u64::MAX;
 pub const DOID_MAX: DoId = u32::MAX;
 pub const ZONE_MAX: Zone = u32::MAX;
 pub const ZONE_BITS: usize = 8 * mem::size_of::<Zone>();
 
-// DoId Constants
-pub const INVALID_DOID: DoId = 0;
+// ---------- Constants ---------- //
 
-// Channel Constants
+pub const INVALID_DOID: DoId = 0;
 pub const INVALID_CHANNEL: Channel = 0;
 pub const CONTROL_CHANNEL: Channel = 1;
 pub const BCHAN_CLIENTS: Channel = 10;
@@ -100,20 +104,129 @@ cfg_if! {
 
 // ---------- Network Protocol ---------- //
 
-// Utility for converting protocol enumerator to u16 (MsgType)
+/// Utility for converting protocol enumerator to u16 (MsgType)
 pub fn msg_type(proto_enum: Protocol) -> MsgType {
     proto_enum as MsgType
 }
 
+/// Enumerator for every message type in the Donet network protocol.
+///
+/// The Donet network protocol is made up of **two** separate, yet
+/// similar protocols: The Client and the Internal protocol.
+///
+/// Every message type defined has a certain 16-bit number identifier.
+/// Message type number IDs are organized in ranges, each range designated
+/// to a certain Donet service.
+///
+/// # Client Protocol
+///
+/// All message types in the client protocol are under the <1000 range.
+///
+/// - **`0-99`**: Basic client messages for the initial handshake
+/// with the Client Agent and maintaining the connection.
+/// - **`100-199`**: Distributed Object generates and field updates.
+/// - **`200-999`**: Client Interest controls.
+///
+/// # Internal Protocol
+///
+/// - ### **`1000-1999`** - Client Agent
+///     - **`1000-1099`** - Client State and Session controls
+///     - **`1100-1199`** - Channel Controls
+///     - **`1200-1999`** - Interest Controls
+///
+/// - ### **`2000-2999`** - State Server / DBSS
+///     - **`2000-2009`** - Object Create / Delete
+///     - **`2010-2039`** - Object Fields
+///     - **`2040-2049`** - Object Location
+///     - **`2050-2059`** - Object Designated AI
+///     - **`2060-2099`** - Object Ownership
+///     - **`2100-2199`** - Zone Controls
+///
+///     ### **Database State Server**
+///     - **`2200-2229`** - DBSS Object Activation
+///     - **`2230-2239`** - Object Data on Disk
+///
+/// - ### **`3000-3999`** - Database Server
+///     - **`3000-3009`** - Object Create
+///     - **`3010-3019`** - Object Get Fields
+///     - **`3020-3029`** - Object Set Fields
+///     - **`3030-3039`** - Object Delete Fields
+///
+/// - ### **`9000-9999`** - Message Director
+///     - **`9000-9009`** - Channels and Channel Ranges
+///     - **`9010-9019`** - Post Removes
+///
 #[repr(u16)] // 16-bit alignment
 #[derive(Debug, Copy, Clone, PartialEq, EnumIter)]
 pub enum Protocol {
+    /// ```md
+    /// args(dc_hash: u32, version: &str)
+    /// ```
+    /// This is the first message a client may send. The `dc_hash` is a
+    /// **32-bit** hash value calculated from all fields/classes listed in
+    /// the client's DC file. The version is an app/game-specific string
+    /// that developers should change whenever they release a new client
+    /// build. Both values are compared to the Client Agent's DC file
+    /// hash and configured version string to ensure that the client is
+    /// fully up-to-date. If the client is not up-to-date, it will be
+    /// disconnected with a `ClientEject`. If the client is up-to-date,
+    /// the gameserver will send a `ClientHelloResp` to inform the
+    /// client that it may proceed with its normal logic flow.
+    ///
+    /// *Excerpt taken from the [Astron](https://github.com/Astron/Astron)
+    /// project, licensed under the
+    /// [BSD-3-Clause](https://raw.githubusercontent.com/Astron/Astron/master/LICENSE.md)
+    /// license.*
+    ///
+    /// Copyright &copy; 2013 Sam "CFSworks" Edwards <br>
+    /// Copyright &copy; 2013 Kevin "Kestred" Stenerson <br>
     ClientHello = 1,
+
+    /// This is sent by the Client Agent to the client when the client's
+    /// `ClientHello` is accepted. This message contains no arguments.
+    ///
+    /// *Excerpt taken from the [Astron](https://github.com/Astron/Astron)
+    /// project, licensed under the
+    /// [BSD-3-Clause](https://raw.githubusercontent.com/Astron/Astron/master/LICENSE.md)
+    /// license.*
+    ///
+    /// Copyright &copy; 2013 Sam "CFSworks" Edwards <br>
+    /// Copyright &copy; 2013 Kevin "Kestred" Stenerson <br>
     ClientHelloResp = 2,
-    // Sent by the client when it's leaving.
+
+    /// Sent by the client when it's closing the connection.
+    /// This message contains no arguments.
     ClientDisconnect = 3,
-    // Sent by the server when it decides to force drop the client.
+
+    /// ```md
+    /// args(error_code: u16, reason: &str)
+    /// ```
+    /// This is sent by the Client Agent to the client when the client is being
+    /// disconnected. The `error_code` and `reason` arguments provide some
+    /// explanation as to why the client is being dropped from the game.
+    ///
+    /// *Excerpt taken from the [Astron](https://github.com/Astron/Astron)
+    /// project, licensed under the
+    /// [BSD-3-Clause](https://raw.githubusercontent.com/Astron/Astron/master/LICENSE.md)
+    /// license.*
+    ///
+    /// Copyright &copy; 2013 Sam "CFSworks" Edwards <br>
+    /// Copyright &copy; 2013 Kevin "Kestred" Stenerson <br>
     ClientEject = 4,
+
+    /// The client should send this message on a regular interval.
+    /// If the Client Agent does not receive a `ClientHeartbeat` for a
+    /// certain (configurable) amount of time, it will assume that the
+    /// client has crashed and disconnect the client.
+    /// This message contains no arguments.
+    ///
+    /// *Excerpt taken from the [Astron](https://github.com/Astron/Astron)
+    /// project, licensed under the
+    /// [BSD-3-Clause](https://raw.githubusercontent.com/Astron/Astron/master/LICENSE.md)
+    /// license.*
+    ///
+    /// Copyright &copy; 2013 Sam "CFSworks" Edwards <br>
+    /// Copyright &copy; 2013 Kevin "Kestred" Stenerson <br>
     ClientHeartbeat = 5,
 
     ClientObjectSetField = 120,
@@ -132,7 +245,6 @@ pub enum Protocol {
     ClientRemoveInterest = 203,
     ClientObjectLocation = 140,
 
-    // ---------- Internal Messages ---------- //
     // Client Agent
     CASetState = 1000,
     CASetClientID = 1001,

libdonet/src/lib.rs

@@ -42,7 +42,8 @@
 //! - **`dcfile`**: Includes the DC file lexer, parser, and DC element structures.
 
 #![doc(html_logo_url = "https://raw.githubusercontent.com/donet-server/donet/master/logo/donet_logo_v3.png")]
-#![warn(unused_extern_crates)]
+//#![warn(missing_docs)]
+#![deny(unused_extern_crates)]
 
 pub mod globals;