deny missing documentation and implement missing docs

Author: ystreet

stun-proto/src/lib.rs

@@ -7,6 +7,7 @@
 // except according to those terms.
 
 #![deny(missing_debug_implementations)]
+#![deny(missing_docs)]
 
 //! # stun-proto
 //!

stun-types/src/attribute/address.rs

@@ -150,7 +150,9 @@ impl std::fmt::Display for MappedSocketAddr {
 /// [`Attribute`](crate::attribute::Attribute) after an XOR operation with the [`TransactionId`]
 /// of a [`Message`](crate::message::Message).
 #[derive(Debug, Clone, PartialEq, Eq)]
+#[repr(transparent)]
 pub struct XorSocketAddr {
+    /// The parent [`MappedSocketAddr`]
     pub addr: MappedSocketAddr,
 }
 
@@ -178,6 +180,7 @@ impl XorSocketAddr {
         Ok(Self { addr })
     }
 
+    /// Returns the XOR of the `addr` with the `transaction` and the hardcoded XOR constant.
     pub fn xor_addr(addr: SocketAddr, transaction: TransactionId) -> SocketAddr {
         match addr {
             SocketAddr::V4(addr) => {

stun-types/src/attribute/error.rs

@@ -119,20 +119,37 @@ impl<'reason> ErrorCodeBuilder<'reason> {
 }
 
 impl ErrorCode {
+    /// Try an alternate server.  The [`AlternateServer`] or [`AlternateDomain`] contains the
+    /// location of where to forward this request.
     pub const TRY_ALTERNATE: u16 = 301;
+    /// The request was malformed and could not be processed.
     pub const BAD_REQUEST: u16 = 400;
+    /// The required credentials were not found or did not match.
     pub const UNAUTHORIZED: u16 = 401;
+    /// Not allowed to access this resource.
     pub const FORBIDDEN: u16 = 403;
+    /// An unknown comprehension required attribute was present.  The [`UnknownAttributes`]
+    /// contains the specific attribute/s.
     pub const UNKNOWN_ATTRIBUTE: u16 = 420;
+    /// The allocation already exists on this server.
     pub const ALLOCATION_MISMATCH: u16 = 437;
+    /// The nonce is no longer valid.
     pub const STALE_NONCE: u16 = 438;
+    /// The address family (IPv4, IPv6) is not supported.
     pub const ADDRESS_FAMILY_NOT_SUPPORTED: u16 = 440;
+    /// Incorrect credentials provided.
     pub const WRONG_CREDENTIALS: u16 = 441;
+    /// The transport protocol (UDP, TCP) is not supported.
     pub const UNSUPPORTED_TRANSPORT_PROTOCOL: u16 = 442;
+    /// The peer address family does not match the TURN allocation.
     pub const PEER_ADDRESS_FAMILY_MISMATCH: u16 = 443;
+    /// This username has reached its limit of allocations currently allowed.
     pub const ALLOCATION_QUOTA_REACHED: u16 = 486;
+    /// Requestor must switch ICE roles.
     pub const ROLE_CONFLICT: u16 = 487;
+    /// An unspecificed error has occurred.
     pub const SERVER_ERROR: u16 = 500;
+    /// The server does not have capacity to handle this request.
     pub const INSUFFICIENT_CAPACITY: u16 = 508;
 
     /// Create a builder for creating a new [`ErrorCode`] [`Attribute`]

stun-types/src/attribute/mod.rs

@@ -292,6 +292,7 @@ impl TryFrom<&[u8]> for AttributeHeader {
 
 /// A static type for an [`Attribute`]
 pub trait AttributeStaticType {
+    /// The [`AttributeType`]
     const TYPE: AttributeType;
 }
 
@@ -351,6 +352,7 @@ fn padded_attr_len(len: usize) -> usize {
     }
 }
 
+/// Automatically implemented trait providing some helper functions.
 pub trait AttributeExt {
     /// The length in bytes of an attribute as stored in a [`Message`](crate::message::Message)
     /// including any padding and the attribute header.
@@ -363,14 +365,30 @@ impl<A: Attribute + ?Sized> AttributeExt for A {
     }
 }
 
+/// Trait required when implementing writing an [`Attribute`] to a sequence of bytes
 pub trait AttributeWrite: Attribute {
+    /// Write the 4 byte attribute header into the provided destination buffer returning the
+    /// number of bytes written.
+    ///
+    /// Panics if the destination buffer is not large enough
     fn write_into_unchecked(&self, dest: &mut [u8]);
+    /// Produce a [`RawAttribute`] from this [`Attribute`]
     fn to_raw(&self) -> RawAttribute;
 }
 
+/// Automatically implemented trait providing helper functionality for writing an [`Attribute`] to
+/// a sequence of bytes.
 pub trait AttributeWriteExt: AttributeWrite {
+    /// Write the 4 byte attribute header into the provided destination buffer returning the
+    /// number of bytes written.
+    ///
+    /// Panics if the destination cannot hold at least 4 bytes of data.
     fn write_header_unchecked(&self, dest: &mut [u8]) -> usize;
+    /// Write the 4 byte attribute header into the provided destination buffer returning the
+    /// number of bytes written, or an error.
     fn write_header(&self, dest: &mut [u8]) -> Result<usize, StunWriteError>;
+    /// Write this attribute into the provided destination buffer returning the number of bytes
+    /// written, or an error.
     fn write_into(&self, dest: &mut [u8]) -> Result<usize, StunWriteError>;
 }
 

stun-types/src/attribute/password_algorithm.rs

@@ -20,7 +20,9 @@ use super::{
 /// The hashing algorithm for the password
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PasswordAlgorithmValue {
+    /// The MD-5 hashing algorithm.
     MD5,
+    /// The SHA-256 hashing algorithm.
     SHA256,
 }
 

stun-types/src/data.rs

@@ -80,7 +80,9 @@ impl From<Box<[u8]>> for DataOwned {
 /// An owned or borrowed piece of data
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum Data<'a> {
+    /// Borrowed data.
     Borrowed(DataSlice<'a>),
+    /// Owned data.
     Owned(DataOwned),
 }
 

stun-types/src/lib.rs

@@ -7,6 +7,7 @@
 // except according to those terms.
 
 #![deny(missing_debug_implementations)]
+#![deny(missing_docs)]
 
 //! # stun-types
 //!
@@ -72,6 +73,7 @@ impl std::fmt::Display for TransportType {
     }
 }
 
+/// Prelude module for traits
 pub mod prelude {
     pub use crate::attribute::{
         Attribute, AttributeExt, AttributeFromRaw, AttributeStaticType, AttributeWrite,

stun-types/src/message.rs

@@ -91,6 +91,7 @@ pub const MAGIC_COOKIE: u32 = 0x2112A442;
 /// message.
 pub const BINDING: u16 = 0x0001;
 
+/// Possible errors when parsing a STUN message.
 #[derive(Debug, thiserror::Error)]
 pub enum StunParseError {
     /// Not a STUN message.
@@ -263,7 +264,9 @@ impl ShortTermCredentials {
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
 pub enum MessageIntegrityCredentials {
+    /// Short term integrity credentials.
     ShortTerm(ShortTermCredentials),
+    /// Long term integrity credentials.
     LongTerm(LongTermCredentials),
 }
 
@@ -311,9 +314,13 @@ impl MessageIntegrityCredentials {
 ///  - [Error][`MessageClass::Error`] class indicates that an error was produced.
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum MessageClass {
+    /// A request that is expecting a response of either Success, or Error.
     Request,
+    /// A request that does not expect a response.
     Indication,
+    /// A success response to a previous Request.
     Success,
+    /// An error response to a previous Request.
     Error,
 }
 
@@ -614,7 +621,9 @@ impl<'a> std::fmt::Display for Message<'a> {
 /// The supported hashing algorithms for ensuring integrity of a [`Message`]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum IntegrityAlgorithm {
+    /// SHA-1 algorithm
     Sha1,
+    /// SHA-256 algorithm
     Sha256,
 }
 
@@ -1475,6 +1484,8 @@ impl<'a> MessageBuilder<'a> {
         ret
     }
 
+    /// Write this builder into the provided destination buffer returning the length in bytes that
+    /// has been written, or an error.
     #[tracing::instrument(
         name = "message_build",
         level = "trace",
@@ -1503,6 +1514,8 @@ impl<'a> MessageBuilder<'a> {
         Ok(offset)
     }
 
+    /// The length in bytes this [`MessageBuilder`] would require to successfully construct
+    /// a message.
     pub fn byte_len(&self) -> usize {
         MessageHeader::LENGTH
             + self