Add more documentation

Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>

xmpp/ChangeLog

@@ -38,6 +38,7 @@ XXXX-YY-ZZ [ RELEASER <admin@localhost> ]
       - New 'escape-hatch' feature: Allow sending tokio_xmpp::Stanza directly
         instead of having to go through xmpp-rs' API when it's lacking. This
         is meant to stay behind a feature.
+      - Added documentation on `Event` enum.
     * Fixes:
       - Use tokio::sync::RwLock not std::sync::RwLock (!432)
       - The default caps node has been shortened to https://xmpp.rs since we

xmpp/src/event.rs

@@ -11,14 +11,38 @@ use tokio_xmpp::parsers::roster::Item as RosterItem;
 
 use crate::{delay::StanzaTimeInfo, Error, MessageId, RoomNick};
 
+/// An Event notifying the client something has happened that may require attention.
+///
+/// This can be an XMPP event received from the server, or existing state communicated by the server to the client, like when receiving the contact list.
 #[derive(Debug)]
 pub enum Event {
+    /// Client connected.
     Online,
+    /// Client disconnected; if reconnect is disabled, no more event will be received.
     Disconnected(Error),
+    /// Contact received from contact list (roster).
+    ///
+    /// This happens when:
+    ///
+    /// - it was added recently to the contact list
+    /// - or when the client just came online and is receiving the existing contact list
     ContactAdded(RosterItem),
+    /// Contact removed from contact list (roster).
     ContactRemoved(RosterItem),
+    /// Contact changed in contact list (roster).
+    ///
+    /// This happens when (non-exhaustive):
+    ///
+    /// - the contact's nickname changed
+    /// - the contact's subscription status changed (eg. they accepted a friend request)
+    /// - the contact has been added to or removed from a contact group
     ContactChanged(RosterItem),
     #[cfg(feature = "avatars")]
+    /// Avatar received for a certain JID, with sender JID / avatar path
+    ///
+    /// The avatar path is relative file path to the avatar data.
+    ///
+    /// NOTE: For now, it's not possible to configure where the avatars are stored, see [issue 112](https://gitlab.com/xmpp-rs/xmpp-rs/-/issues/112) for more information.
     AvatarRetrieved(Jid, String),
     /// A chat message was received. It may have been delayed on the network.
     /// - The [`MessageId`] is a unique identifier for this message.
@@ -32,8 +56,16 @@ pub enum Event {
     /// - The [`String`] is the new body of the message, to replace the old one.
     /// - The [`StanzaTimeInfo`] is the time the message correction was sent/received
     ChatMessageCorrection(MessageId, BareJid, String, StanzaTimeInfo),
+    /// Room joined; client may receive and send messages from/to this BareJid.
     RoomJoined(BareJid),
+    /// Room left; client may not receive and send messages from/to this BareJid
     RoomLeft(BareJid),
+    /// Room message received with:
+    /// - An optional [`MessageId`] for the message.
+    /// - The [`BareJid`] of the room the message was sent from.
+    /// - The [`RoomNick`] of the sender.
+    /// - A [`String`] containing the actual message.
+    /// - The [`StanzaTimeInfo`] containing time related information for the message.
     RoomMessage(Option<MessageId>, BareJid, RoomNick, String, StanzaTimeInfo),
     /// A message in a MUC was corrected/edited.
     /// - The [`MessageId`] is the ID of the message that was corrected.
@@ -43,12 +75,16 @@ pub enum Event {
     /// - The [`StanzaTimeInfo`] is the time the message correction was sent/received
     RoomMessageCorrection(MessageId, BareJid, RoomNick, String, StanzaTimeInfo),
     /// The subject of a room was received.
-    /// - The BareJid is the room's address.
-    /// - The RoomNick is the nickname of the room member who set the subject.
-    /// - The String is the new subject.
+    /// - The [`BareJid`] is the room's address.
+    /// - The [`RoomNick`] is the nickname of the room member who set the subject.
+    /// - The [`String`] is the new subject.
     RoomSubject(BareJid, Option<RoomNick>, String, StanzaTimeInfo),
-    /// A private message received from a room, containing the message ID, the room's BareJid,
-    /// the sender's nickname, and the message body.
+    /// A private message received from a room, containing:
+    /// - An optional [`MessageId`] for the message.
+    /// - The room's [`BareJid`].
+    /// - The sender's [`RoomNick`].
+    /// - A [`String`] containing the actual message.
+    /// - The [`StanzaTimeInfo`] containing time related information for the message.
     RoomPrivateMessage(Option<MessageId>, BareJid, RoomNick, String, StanzaTimeInfo),
     /// A private message in a MUC was corrected/edited.
     /// - The [`MessageId`] is the ID of the message that was corrected.
@@ -57,6 +93,12 @@ pub enum Event {
     /// - The [`String`] is the new body of the message, to replace the old one.
     /// - The [`StanzaTimeInfo`] is the time the message correction was sent/received
     RoomPrivateMessageCorrection(MessageId, BareJid, RoomNick, String, StanzaTimeInfo),
+    /// Service message (eg. server notification) received, with:
+    /// - An optional [`MessageId`] for the message.
+    /// - The [`BareJid`] of the entity that sent it.
+    /// - A [`String`] containing the actual message.
+    /// - The [`StanzaTimeInfo`] containing time related information for the message.
     ServiceMessage(Option<MessageId>, BareJid, String, StanzaTimeInfo),
+    /// A file has been uploaded over HTTP; contains the URL of the file.
     HttpUploadedFile(String),
 }