docs: documented a lot of structs and modules

Signed-off-by: Jad K. Haddad <jadkhaddad@gmail.com>

Author: JadKHaddad

src/close_code.rs

@@ -1,4 +1,8 @@
+/// A WebSocket Close code.
+///
+/// Indicate why an endpoint is closing the WebSocket connection.
 #[repr(u16)]
+#[non_exhaustive]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum CloseCode {
     /// Indicates a normal closure, meaning that the purpose for
@@ -59,10 +63,15 @@ pub enum CloseCode {
     /// to a different IP (when multiple targets exist), or reconnect to the same IP
     /// when a user has performed an action.
     Again = 1013,
+    #[doc(hidden)]
     Tls = 1015,
+    #[doc(hidden)]
     Reserved(u16),
+    #[doc(hidden)]
     Iana(u16),
+    #[doc(hidden)]
     Library(u16),
+    #[doc(hidden)]
     Bad(u16),
 }
 

src/close_frame.rs

@@ -1,5 +1,6 @@
 use crate::CloseCode;
 
+/// A WebSocket Close frame.
 #[derive(Debug)]
 pub struct CloseFrame<'a> {
     /// The reason as a code.

src/error.rs

@@ -1,34 +1,56 @@
+//! Crate's error module.
+//!
+//! Contains all error types used throughout the crate.
+
 use core::convert::Infallible;
 
+/// Error decoding a WebSocket frame.
 #[derive(Debug, thiserror::Error)]
 pub enum FrameDecodeError {
+    /// Reserved bits are not zero.
     #[error("Reserved bits must be zero")]
     ReservedBitsNotZero,
+    /// Unmasked frame received from client.
+    ///
     /// The server must close the connection when an unmasked frame is received.
     #[error("Received an unmasked frame from client")]
     UnmaskedFrameFromClient,
+    /// Masked frame received from server.
+    ///
     /// The client must close the connection when a masked frame is received.
     #[error("Received a masked frame from server")]
     MaskedFrameFromServer,
+    /// Invalid opcode.
     #[error("Invalid opcode")]
     InvalidOpCode,
-    // The payload length comes as a u64, converting it to usize might fail on 32-bit systems
+    /// Payload length is too large.
+    // XXX: The payload length comes as a u64, converting it to usize might fail on 32-bit systems
     #[error("Payload too large")]
     PayloadTooLarge,
+    /// Control frame fragmented.
+    ///
+    /// Control frames must not be fragmented.
     #[error("Control frame fragmented")]
     ControlFrameFragmented,
+    /// Control frame too large.
+    ///
+    /// Control frames must have a payload length of 125 bytes or less.
     #[error("Control frame too large")]
     ControlFrameTooLarge,
 }
 
+/// Error encoding a WebSocket frame.
 #[derive(Debug, thiserror::Error)]
 pub enum FrameEncodeError {
+    /// Write buffer is too small to hold the encoded frame.
     #[error("Buffer too small")]
     BufferTooSmall,
 }
 
+/// Error decoding an HTTP request/response.
 #[derive(Debug, thiserror::Error)]
 pub enum HttpDecodeError {
+    /// Error parsing the HTTP request/response.
     #[error("Parse error: {0}")]
     Parse(httparse::Error),
 }
@@ -39,63 +61,83 @@ impl From<httparse::Error> for HttpDecodeError {
     }
 }
 
+/// Error encoding an HTTP request/response.
 #[derive(Debug, thiserror::Error)]
 pub enum HttpEncodeError {
+    /// Write buffer is too small to hold the encoded HTTP request/response.
     #[error("Buffer too small")]
     BufferTooSmall,
 }
 
+/// Protocol specific errors/violations.
 #[derive(Debug, thiserror::Error)]
 pub enum ProtocolError {
+    /// Close frame is invalid.
     #[error("Invalid close frame")]
     InvalidCloseFrame,
+    /// Close code is invalid.
     #[error("Invalid close code")]
     InvalidCloseCode,
+    /// Text message contains invalid UTF-8.
     #[error("Invalid UTF-8")]
     InvalidUTF8,
+    /// Fragment is invalid.
+    ///
+    /// This happens when a final fragment is received without any prior fragments.
     #[error("Invalid fragment")]
     InvalidFragment,
+    /// Continuation frame is invalid.
+    ///
+    /// This happens when a continuation frame is received without an ongoing fragmented message.
     #[error("Invalid continuation frame")]
     InvalidContinuationFrame,
 }
 
+/// Error reading from a WebSocket connection.
 #[derive(Debug, thiserror::Error)]
 pub enum ReadError<I> {
+    /// Error reading a WebSocket frame from the underlying I/O.
     #[error("Read frame error: {0}")]
     ReadFrame(
         #[source]
         #[from]
         framez::ReadError<I, FrameDecodeError>,
     ),
+    /// Error reading an HTTP request/response from the underlying I/O.
     #[error("Read http error: {0}")]
     ReadHttp(
         #[source]
         #[from]
         framez::ReadError<I, HttpDecodeError>,
     ),
+    /// Protocol error.
     #[error("Protocol error: {0}")]
     Protocol(
         #[source]
         #[from]
         ProtocolError,
     ),
+    /// Fragments buffer is too small to read a frame.
     #[error("Fragments buffer too small to read a frame")]
     FragmentsBufferTooSmall,
 }
 
+/// Error writing to a WebSocket connection.
 #[derive(Debug, thiserror::Error)]
 pub enum WriteError<I> {
     /// Websocket connection is closed.
     ///
-    /// To close the TCP connection, you should drop the [`WebSocket`](crate::WebSocket) instance.
+    /// To close the TCP connection, you should drop/close the underlying I/O instance.
     #[error("Connection closed")]
     ConnectionClosed,
+    /// Error writing a WebSocket frame to the underlying I/O.
     #[error("Write frame error: {0}")]
     WriteFrame(
         #[source]
         #[from]
         framez::WriteError<I, FrameEncodeError>,
     ),
+    /// Error writing an HTTP request/response to the underlying I/O.
     #[error("Write http error: {0}")]
     WriteHttp(
         #[source]
@@ -104,6 +146,11 @@ pub enum WriteError<I> {
     ),
 }
 
+/// Error establishing a WebSocket handshake.
+///
+/// # Generic Parameter
+///
+/// `E`: User-defined error type for custom errors during the handshake.
 #[derive(Debug, thiserror::Error)]
 pub enum HandshakeError<E = Infallible> {
     /// Use of the wrong HTTP method (the WebSocket protocol requires the GET method to be used).
@@ -112,52 +159,72 @@ pub enum HandshakeError<E = Infallible> {
     /// Wrong HTTP version used (the WebSocket protocol requires version 1.1 or higher).
     #[error("HTTP version must be 1.1 or higher")]
     WrongHttpVersion,
+    /// Connection was closed during the handshake.
     #[error("Connection closed during handshake")]
     ConnectionClosed,
+    /// Invalid status code. (Should be 101 for switching protocols.)
     #[error("Invalid status code")]
     InvalidStatusCode,
+    /// Missing or invalid (`Upgrade`: `websocket`) header.
     #[error("Missing or invalid upgrade header")]
     MissingOrInvalidUpgrade,
+    /// Missing or invalid (`Connection`: `upgrade`) header.
     #[error("Missing or invalid connection header")]
     MissingOrInvalidConnection,
+    /// Missing or invalid (`Sec-WebSocket-Accept`) header.
     #[error("Missing or invalid sec websocket accept header")]
     MissingOrInvalidAccept,
+    /// Missing or invalid (`Sec-WebSocket-Version`) header.
     #[error("Missing or invalid sec websocket version header")]
     MissingOrInvalidSecVersion,
+    /// Missing (`Sec-WebSocket-Key`) header.
     #[error("Missing sec websocket key header")]
     MissingSecKey,
+    /// Other error.
+    ///
+    /// User-defined error type.
     #[error("Other: {0}")]
     Other(E),
 }
 
+/// Fragmentation error.
 #[derive(Debug, thiserror::Error)]
 pub enum FragmentationError {
+    /// Fragment size is zero.
     #[error("Fragment size must be greater than 0")]
     InvalidFragmentSize,
+    /// Error indicating that a message type that cannot be fragmented was attempted to be fragmented.
+    ///
+    /// Only text and binary messages can be fragmented.
     #[error("Only text and binary messages can be fragmented")]
     CanNotBeFragmented,
 }
 
+/// General WebSocket error type.
 #[derive(Debug, thiserror::Error)]
 pub enum Error<I, E = Infallible> {
+    /// Error reading from the WebSocket connection.
     #[error("Read error: {0}")]
     Read(
         #[from]
         #[source]
         ReadError<I>,
     ),
+    /// Error writing to the WebSocket connection.
     #[error("Write error: {0}")]
     Write(
         #[from]
         #[source]
         WriteError<I>,
     ),
+    /// Handshake error.
     #[error("Handshake error: {0}")]
     Handshake(
         #[from]
         #[source]
         HandshakeError<E>,
     ),
+    /// Fragmentation error.
     #[error("Fragment error: {0}")]
     Fragmentation(
         #[from]

src/http.rs

@@ -1,3 +1,7 @@
+//! HTTP request and response types.
+//!
+//! The [`Header`] type is re-exported from the [`httparse`] crate.
+
 use framez::{decode::Decoder, encode::Encoder};
 pub use httparse::Header;
 use httparse::Status;
@@ -95,6 +99,7 @@ impl Encoder<OutResponse<'_, '_>> for OutResponseCodec {
     }
 }
 
+/// An HTTP response.
 #[derive(Debug)]
 pub struct Response<'buf, const N: usize> {
     /// The response minor version, such as `1` for `HTTP/1.1`.
@@ -110,6 +115,7 @@ pub struct Response<'buf, const N: usize> {
 }
 
 impl<'buf, const N: usize> Response<'buf, N> {
+    /// Creates a new [`Response`].
     pub const fn new(
         version: u8,
         code: u16,
@@ -124,18 +130,22 @@ impl<'buf, const N: usize> Response<'buf, N> {
         }
     }
 
+    /// Returns the HTTP version.
     pub const fn version(&self) -> u8 {
         self.version
     }
 
+    /// Returns the response code.
     pub const fn code(&self) -> u16 {
         self.code
     }
 
+    /// Returns the reason-phrase.
     pub const fn reason(&self) -> &'buf str {
         self.reason
     }
 
+    /// Returns the headers.
     pub const fn headers(&self) -> &[Header<'buf>] {
         &self.headers
     }
@@ -252,6 +262,7 @@ impl Encoder<OutRequest<'_, '_>> for OutRequestCodec {
     }
 }
 
+/// An HTTP request.
 #[derive(Debug)]
 pub struct Request<'buf, const N: usize> {
     /// The request method, such as `GET`.
@@ -265,6 +276,7 @@ pub struct Request<'buf, const N: usize> {
 }
 
 impl<'buf, const N: usize> Request<'buf, N> {
+    /// Creates a new [`Request`].
     pub const fn new(
         method: &'buf str,
         path: &'buf str,
@@ -279,18 +291,22 @@ impl<'buf, const N: usize> Request<'buf, N> {
         }
     }
 
+    /// Returns the request method.
     pub const fn method(&self) -> &'buf str {
         self.method
     }
 
+    /// Returns the request path.
     pub const fn path(&self) -> &'buf str {
         self.path
     }
 
+    /// Returns the HTTP version.
     pub const fn version(&self) -> u8 {
         self.version
     }
 
+    /// Returns the headers.
     pub const fn headers(&self) -> &[Header<'buf>] {
         &self.headers
     }

src/lib.rs

@@ -1,8 +1,10 @@
 //! `zerocopy`, `async`, `no_std` and [`autobahn`](https://github.com/crossbario/autobahn-testsuite) compliant `websockets` implementation.
 
+// TODO: examples
+
 #![no_std]
 #![deny(missing_debug_implementations)]
-// #![deny(missing_docs)]
+#![deny(missing_docs)]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 
 mod close_code;

src/macros.rs

@@ -1,3 +1,8 @@
+// TODO: Add documentation for this macro and examples and why to use it.
+
+// TODO: remove this after adding docs.
+#![allow(missing_docs)]
+
 #[macro_export]
 macro_rules! next {
     ($websocketz:expr) => {{

src/message.rs

@@ -1,7 +1,9 @@
 use crate::{CloseFrame, Frame, OpCode, error::FragmentationError, fragments::FragmentsIterator};
 
+/// A WebSocket message.
 #[derive(Debug)]
 pub enum Message<'a> {
+    /// A text WebSocket message
     Text(&'a str),
     /// A binary WebSocket message
     Binary(&'a [u8]),