From dc9a56857ca4c15737ac90b9d029192981706c0c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maxime=20=E2=80=9Cpep=E2=80=9D=20Buquet?= <pep@bouah.net>
Date: Fri, 30 Sep 2022 18:39:00 +0200
Subject: [PATCH] room/Occupant: Add docstrings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>
---
 src/room.rs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/room.rs b/src/room.rs
index b8f880e..0fd41f4 100644
--- a/src/room.rs
+++ b/src/room.rs
@@ -320,7 +320,7 @@ impl Room {
         Ok(())
     }
 
-    /// Looks for the occupant associated with the provided nick and ensure the session is part of
+    /// Fetch the occupant associated with the provided nick and ensure the session is part of
     /// it.
     pub fn get_occupant(&self, realjid: &Session, nick: &Nick) -> Result<&Occupant, Error> {
         if let Some(occupant) = self.occupants.get(nick) {
@@ -339,16 +339,18 @@ impl Room {
     }
 }
 
+/// An occupant in a room. May contain multiple sessions (Multi-Session Nicks)
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Occupant {
     /// Public Jid for the Occupant
     pub real: BareJid,
     pub participant: FullJid,
     pub nick: Nick,
-    pub sessions: Vec<FullJid>,
+    pub sessions: Vec<Presence>,
 }
 
 impl Occupant {
+    /// New occupant
     pub fn new(room: &Room, real: FullJid, nick: Nick) -> Occupant {
         Occupant {
             real: BareJid::from(real.clone()),
@@ -358,6 +360,7 @@ impl Occupant {
         }
     }
 
+    /// Add a new session to the occupant
     pub fn add_session(&mut self, real: FullJid) -> Result<(), Error> {
         if BareJid::from(real.clone()) != self.real {
             return Err(Error::MismatchJids(
@@ -376,6 +379,7 @@ impl Occupant {
         Ok(())
     }
 
+    /// Remove a session from the occupant
     pub fn remove_session(&mut self, real: FullJid) -> Result<(), Error> {
         if BareJid::from(real.clone()) != self.real {
             return Err(Error::MismatchJids(
@@ -395,6 +399,8 @@ impl Occupant {
         }
     }
 
+    /// Return whether a Jid matches the occupant. If FullJid, compare with each session, otherwise
+    /// see if the BareJid matches.
     pub fn contains<J: Into<Jid>>(&self, _jid: &J) -> bool {
         true
     }