doc(socketio): improve doc

examples/chat/src/main.rs

@@ -2,7 +2,7 @@ use std::sync::atomic::AtomicUsize;
 
 use serde::{Deserialize, Serialize};
 use socketioxide::{
-    extract::{Data, Extension, MaybeExtension, SocketRef, State},
+    extract::{Data, Extension, SocketRef, State},
     SocketIo,
 };
 use tower::ServiceBuilder;
@@ -104,15 +104,13 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         );
 
         s.on_disconnect(
-            |s: SocketRef, user_cnt: State<UserCnt>, MaybeExtension::<Username>(username)| {
-                if let Some(username) = username {
-                    let num_users = user_cnt.remove_user();
-                    let res = Res::UserEvent {
-                        num_users,
-                        username,
-                    };
-                    s.broadcast().emit("user left", res).ok();
-                }
+            |s: SocketRef, user_cnt: State<UserCnt>, Extension::<Username>(username)| {
+                let num_users = user_cnt.remove_user();
+                let res = Res::UserEvent {
+                    num_users,
+                    username,
+                };
+                s.broadcast().emit("user left", res).ok();
             },
         );
     });

socketioxide/src/extensions.rs

@@ -6,6 +6,9 @@
 //! to allow concurrent access. Moreover, any value extracted from the map is cloned before being returned.
 //!
 //! This is necessary because [`Extensions`] are shared between all the threads that handle the same socket.
+//!
+//! You can use the [`Extension`](crate::extract::Extension) or
+//! [`MaybeExtension`](crate::extract::MaybeExtension) extractor to extract an extension of the given type.
 
 use std::collections::HashMap;
 use std::fmt;
@@ -50,6 +53,9 @@ impl Hasher for IdHasher {
 /// The main difference is that the inner Map is wrapped with an `RwLock` to allow concurrent access.
 ///
 /// This is necessary because `Extensions` are shared between all the threads that handle the same socket.
+///
+/// You can use the [`Extension`](crate::extract::Extension) or
+/// [`MaybeExtension`](crate::extract::MaybeExtension) extractor to extract an extension of the given type.
 #[derive(Default)]
 pub struct Extensions {
     /// The underlying map

socketioxide/src/extract/extensions.rs

@@ -10,7 +10,7 @@ use bytes::Bytes;
 #[cfg_attr(docsrs, doc(cfg(feature = "extensions")))]
 pub use extensions_extract::*;
 
-/// It was impossible to find the given extension
+/// It was impossible to find the given extension.
 pub struct ExtensionNotFound<T>(std::marker::PhantomData<T>);
 
 impl<T> std::fmt::Display for ExtensionNotFound<T> {
@@ -120,9 +120,11 @@ mod extensions_extract {
     /// An Extractor that returns the extension of the given type.
     /// If the extension is not found,
     /// the handler won't be called and an error log will be print if the `tracing` feature is enabled.
+    ///
+    /// You can use [`MaybeExtension`] if the extensions you are requesting _may_ not exists.
     pub struct Extension<T>(pub T);
 
-    /// An Extractor that returns the extension of the given type if it exists or `None` otherwise.
+    /// An Extractor that returns the extension of the given type T if it exists or [`None`] otherwise.
     pub struct MaybeExtension<T>(pub Option<T>);
 
     impl<A: Adapter, T: Clone + Send + Sync + 'static> FromConnectParts<A> for Extension<T> {
@@ -180,4 +182,6 @@ mod extensions_extract {
             Ok(MaybeExtension(extract_extension(s).ok()))
         }
     }
+    super::super::__impl_deref!(Extension);
+    super::super::__impl_deref!(MaybeExtension<T>: Option<T>);
 }

socketioxide/src/extract/mod.rs

@@ -17,11 +17,11 @@
 //! * [`TransportType`](crate::TransportType): extracts the transport type
 //! * [`DisconnectReason`](crate::socket::DisconnectReason): extracts the reason of the disconnection
 //! * [`State`]: extracts a reference to a state previously set with [`SocketIoBuilder::with_state`](crate::io::SocketIoBuilder).
-//! * [`Extension`]: extracts an extension of the given type
-//! * [`MaybeExtension`]: extracts an extension of the given type if it exists or `None` otherwise
+//! * [`Extension`]: extracts an extension of the given type stored on the called socket by cloning it.
+//! * [`MaybeExtension`]: extracts an extension of the given type if it exists or [`None`] otherwise
 //! * [`HttpExtension`]: extracts an http extension of the given type coming from the request.
 //! (Similar to axum's [`extract::Extension`](https://docs.rs/axum/latest/axum/struct.Extension.html)
-//! * [`MaybeHttpExtension`]: extracts an http extension of the given type if it exists or `None` otherwise.
+//! * [`MaybeHttpExtension`]: extracts an http extension of the given type if it exists or [`None`] otherwise.
 //!
 //! ### You can also implement your own Extractor with the [`FromConnectParts`], [`FromMessageParts`] and [`FromDisconnectParts`] traits
 //! When implementing these traits, if you clone the [`Arc<Socket>`](crate::socket::Socket) make sure that it is dropped at least when the socket is disconnected.

socketioxide/src/lib.rs

@@ -188,6 +188,7 @@
 //!     Because the socket is not yet connected to the namespace,
 //!     you can't send messages to it from the middleware.
 //! </div>
+//!
 //! See the [`handler::connect`](handler::connect#middleware) module doc for more details on middlewares and examples.
 //!
 //! ## [Emiting data](#emiting-data)