doc(socketio/socket): Document emit variable arguments fn (#240) (#241)

* doc: document `emit` fn
* chore(deps): bump version to 0.10.1

Cargo.toml

@@ -27,7 +27,7 @@ salvo = { version = "0.65.0", features = ["tower-compat"] }
 rust_socketio = { version = "0.4.2", features = ["async"] }
 
 [workspace.package]
-version = "0.10.0"
+version = "0.10.1"
 edition = "2021"
 rust-version = "1.67.0"
 authors = ["Théodore Prévot <"]

socketioxide/Cargo.toml

@@ -14,7 +14,7 @@ readme = "../README.md"
 
 
 [dependencies]
-engineioxide = { path = "../engineioxide", version = "0.10" }
+engineioxide = { path = "../engineioxide", version = "0.10.1" }
 futures.workspace = true
 tokio = { workspace = true, features = ["rt", "time"] }
 serde.workspace = true

socketioxide/src/lib.rs

@@ -183,6 +183,10 @@
 //!
 //! Moreover the [`io`](SocketIo) handle can emit to any namespace while the [`SocketRef`](extract::SocketRef) can only emit to the namespace of the socket.
 //!
+//! When using any `emit` fn, if you provide array-like data (tuple, vec, arrays), it will be considered as multiple arguments.
+//! Therefore if you want to send an array as the _first_ argument of the payload,
+//! you need to wrap it in an array or a tuple.
+//!
 //! #### Emit errors
 //! If the data can't be serialized to json, an [`serde_json::Error`] will be returned.
 //! If the socket is disconnected or the internal channel is full, a tracing log will be emitted if the `tracing` feature is enabled and the message will be dropped.

socketioxide/src/operators.rs

@@ -279,6 +279,21 @@ impl<A: Adapter> Operators<A> {
     }
 
     /// Emits a message to all sockets selected with the previous operators.
+    ///
+    /// If you provide array-like data (tuple, vec, arrays), it will be considered as multiple arguments.
+    /// Therefore if you want to send an array as the _first_ argument of the payload,
+    /// you need to wrap it in an array or a tuple.
+    ///
+    /// ## Errors
+    /// * When encoding the data into JSON a [`BroadcastError::Serialize`] may be returned.
+    /// * If the underlying engine.io connection is closed for a given socket a [`BroadcastError::Socket(SocketError::Closed)`]
+    /// will be returned.
+    /// * If the packet buffer is full for a given socket, a [`BroadcastError::Socket(SocketError::InternalChannelFull)`]
+    /// will be retured.
+    /// See [`SocketIoBuilder::max_buffer_size`] option for more infos on internal buffer config
+    ///
+    /// [`SocketIoBuilder::max_buffer_size`]: crate::SocketIoBuilder#method.max_buffer_size
+    ///
     /// #### Example
     /// ```
     /// # use socketioxide::{SocketIo, extract::*};
@@ -288,6 +303,13 @@ impl<A: Adapter> Operators<A> {
     ///     socket.on("test", |socket: SocketRef, Data::<Value>(data), Bin(bin)| async move {
     ///         // Emit a test message in the room1 and room3 rooms, except for the room2 room with the binary payload received
     ///         socket.to("room1").to("room3").except("room2").bin(bin).emit("test", data);
+    ///
+    ///         // Emit a test message with multiple arguments to the client
+    ///         socket.to("room1").emit("test", ("world", "hello", 1)).ok();
+    ///
+    ///         // Emit a test message with an array as the first argument
+    ///         let arr = [1, 2, 3, 4];
+    ///         socket.to("room2").emit("test", [arr]).ok();
     ///     });
     /// });
     pub fn emit(

socketioxide/src/socket.rs

@@ -242,10 +242,17 @@ impl<A: Adapter> Socket<A> {
     }
 
     /// Emits a message to the client
+    ///
+    /// If you provide array-like data (tuple, vec, arrays), it will be considered as multiple arguments.
+    /// Therefore if you want to send an array as the _first_ argument of the payload,
+    /// you need to wrap it in an array or a tuple.
+    ///
     /// ## Errors
     /// * When encoding the data into JSON a [`SendError::Serialize`] may be returned.
-    /// * If the underlying engine.io connection is closed a [`SendError::Socket(SocketError::Closed)`].
-    /// * If the packet buffer is full, a [`SendError::Socket(SocketError::InternalChannelFull)`].
+    /// * If the underlying engine.io connection is closed a [`SendError::Socket(SocketError::Closed)`]
+    /// will be returned.
+    /// * If the packet buffer is full, a [`SendError::Socket(SocketError::InternalChannelFull)`]
+    /// will be returned.
     /// See [`SocketIoBuilder::max_buffer_size`] option for more infos on internal buffer config
     ///
     /// [`SocketIoBuilder::max_buffer_size`]: crate::SocketIoBuilder#method.max_buffer_size
@@ -259,6 +266,13 @@ impl<A: Adapter> Socket<A> {
     ///     socket.on("test", |socket: SocketRef, Data::<Value>(data)| async move {
     ///         // Emit a test message to the client
     ///         socket.emit("test", data).ok();
+    ///
+    ///         // Emit a test message with multiple arguments to the client
+    ///         socket.emit("test", ("world", "hello", 1)).ok();
+    ///
+    ///         // Emit a test message with an array as the first argument
+    ///         let arr = [1, 2, 3, 4];
+    ///         socket.emit("test", [arr]).ok();
     ///     });
     /// });
     /// ```