Merge pull request #10 from noctisynth/docs/doctest

docs: add doctest for server and rewrite doctest for generator

src/models/server.rs

@@ -19,6 +19,7 @@ use super::packet::{OED, OSC};
 use super::router::Router;
 use super::session::Session;
 
+#[inline]
 async fn _handle(router: &Router, stream: TcpStream, peer: SocketAddr) -> Result<()> {
     #[cfg(feature = "perf")]
     let now = std::time::Instant::now();
@@ -147,7 +148,39 @@ pub async fn handle(router: Arc<Router>, stream: TcpStream, peer: SocketAddr) {
     );
 }
 
-/// Server Core Struct
+/// Oblivion Server
+///
+/// Oblivion uses the `tokio` library to handle TCP connections. The `Server` struct
+/// is responsible for creating and managing the TCP listener and handling incoming
+/// connections. The `handle` function is called for each incoming connection,
+/// which creates a new `Session` and handles the incoming data. The `Router`
+/// is used to determine which handler function to call based on the incoming
+/// request.
+///
+/// # Example
+///
+/// ```rust
+/// # use oblivion::models::server::Server;
+/// # use oblivion::models::router::Router;
+/// # use anyhow::Result;
+/// # async fn runner() -> Result<()> {
+/// let router = Router::new(); // Create an empty router
+/// // Create an oblivion server and bind it to 127.0.0.1:8080
+/// let server = Server::new("127.0.0.1", 0, router);
+/// server.run().await;
+/// # Ok(())
+/// # }
+///
+/// # #[tokio::main]
+/// # async fn main() {
+/// #     let future = tokio::spawn(async {
+/// #         if let Err(error) = runner().await {
+/// #             panic!("An error occurred: {}", error);
+/// #         }
+/// #     });
+/// #     future.abort();
+/// # }
+/// ```
 pub struct Server {
     host: String,
     port: i32,

src/models/session.rs

@@ -19,6 +19,10 @@ use super::client::Response;
 use super::packet::{OED, OKE, OSC};
 use super::render::BaseResponse;
 
+/// Oblivion Full Duplex Session
+///
+/// This struct represents a full duplex session between the client and the server.
+/// It contains all the necessary information to handle the communication between the two.
 pub struct Session {
     pub header: String,
     #[cfg(feature = "unsafe")]

src/utils/generator.rs

@@ -22,10 +22,11 @@ use crate::exceptions::Exception;
 /// Create an ECC key
 ///
 /// `generate_key_pair` will create an ECC key and return a (private key, public key) pair of `(EphemeralSecret, PublicKey)`.
+/// 
+/// We use `X25519` curve for ECC operations.
 ///
 /// ```rust
-/// use oblivion::utils::generator::generate_key_pair;
-///
+/// # use oblivion::utils::generator::generate_key_pair;
 /// let (private_key, public_key) = generate_key_pair();
 /// ```
 #[cfg(not(feature = "unsafe"))]
@@ -43,33 +44,51 @@ pub fn generate_key_pair() -> Result<(EphemeralSecret, PublicKey), Exception> {
     Ok((private_key, public_key))
 }
 
-/// Create an ECDH Shared Key
+/// Generate a Shared Key
 ///
-/// ```rust
-/// use oblivion::utils::generator::{generate_key_pair, generate_random_salt, SharedKey};
-/// use ring::agreement::{UnparsedPublicKey, X25519};
+/// `SharedKey` is a struct that can generate a shared key using HKDF or Scrypt.
+///
+/// The shared key is generated using the private key and the public key of the other party.
 ///
+/// # Examples
+///
+/// ```rust
+/// # use oblivion::utils::generator::{generate_key_pair, generate_random_salt, SharedKey};
+/// # use ring::agreement::{UnparsedPublicKey, X25519};
+/// # #[cfg(not(feature = "unsafe"))]
+/// # {
 /// let salt = generate_random_salt();
-/// #[cfg(feature = "unsafe")]
-/// let (private_key, public_key) = generate_key_pair().unwrap();
-/// #[cfg(not(feature = "unsafe"))]
+///
 /// let (private_key, public_key) = generate_key_pair();
 ///
-/// #[cfg(not(feature = "unsafe"))]
 /// let public_key: UnparsedPublicKey<Vec<u8>> = {
+///     // Convert the public key to UnparsedPublicKey
 ///     let public_key_bytes = public_key.as_ref().to_vec();
 ///     UnparsedPublicKey::new(&X25519, public_key_bytes)
 /// };
 ///
-/// #[cfg(feature = "unsafe")]
+/// let mut shared_key = SharedKey::new(private_key, &public_key).unwrap();
+///
+/// shared_key.hkdf(&salt); // Generate a shared key using HKDF
+/// shared_key.scrypt(&salt).unwrap(); // Generate a shared key using Scrypt
+/// # }
+/// ```
+///
+/// Now oblivion uses `ring` instead of `p256` for ECC operations. The `SharedKey` struct is updated to use `ring` instead of `p256`.
+///
+/// If you still want to use a deprecated version of the library, you can use the following code:
+///
+/// ```rust
+/// # use oblivion::utils::generator::{generate_key_pair, generate_random_salt, SharedKey};
+/// # use ring::agreement::{UnparsedPublicKey, X25519};
+/// # #[cfg(feature = "unsafe")]
+/// # {
+/// let (private_key, public_key) = generate_key_pair().unwrap();
 /// let mut shared_key = SharedKey::new(&private_key, &public_key);
-/// #[cfg(not(feature = "unsafe"))]
-/// let mut shared_key = SharedKey::new(private_key, &public_key);
 ///
-/// #[cfg(feature = "unsafe")]
-/// shared_key.hkdf(&salt);
-/// #[cfg(feature = "unsafe")]
-/// shared_key.scrypt(&salt);
+/// shared_key.hkdf(&salt); // Generate a shared key using HKDF
+/// shared_key.scrypt(&salt).unwrap(); // Generate a shared key using Scrypt
+/// # }
 /// ```
 pub struct SharedKey {
     shared_key: Vec<u8>,
@@ -119,9 +138,14 @@ impl SharedKey {
 }
 
 /// Generate a Randomized Salt
-/// ```rust
-/// use oblivion::utils::generator::generate_random_salt;
 ///
+/// `generate_random_salt` will generate a random salt using the `ring` library.
+///
+/// The length of the salt is 16 bytes, which is the length of the key used for AES-GCM encryption.
+///
+/// # Example
+/// ```rust
+/// # use oblivion::utils::generator::generate_random_salt;
 /// let salt = generate_random_salt();
 /// ```
 pub fn generate_random_salt() -> Vec<u8> {