From 16b929147580fda3267977f30eeb8f8cf3fc55b0 Mon Sep 17 00:00:00 2001 From: Emmanuel Gil Peyrot Date: Wed, 8 Aug 2018 20:22:37 +0200 Subject: [PATCH] muc: Document these modules. --- src/muc/mod.rs | 5 +-- src/muc/muc.rs | 12 +++++++ src/muc/user.rs | 94 +++++++++++++++++++++++++++++++++++++++---------- 3 files changed, 91 insertions(+), 20 deletions(-) diff --git a/src/muc/mod.rs b/src/muc/mod.rs index 77b59aded8500356994f2b11a252af3f768a4323..a12bd565f8ee2fd77201a77325d71a298df84747 100644 --- a/src/muc/mod.rs +++ b/src/muc/mod.rs @@ -4,9 +4,10 @@ // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. -#![allow(missing_docs)] - +/// The http://jabber.org/protocol/muc protocol. pub mod muc; + +/// The http://jabber.org/protocol/muc#user protocol. pub mod user; pub use self::muc::Muc; diff --git a/src/muc/muc.rs b/src/muc/muc.rs index 27c22d91c115ff955f929d82c6d0cf58ef02f44f..4d81b85c2a57776b741f7524769df4942b8e1f34 100644 --- a/src/muc/muc.rs +++ b/src/muc/muc.rs @@ -8,18 +8,30 @@ use date::DateTime; generate_element!( + /// Represents the query for messages before our join. History, "history", MUC, attributes: [ + /// How many characters of history to send, in XML characters. maxchars: Option = "maxchars" => optional, + + /// How many messages to send. maxstanzas: Option = "maxstanzas" => optional, + + /// Only send messages received in these last seconds. seconds: Option = "seconds" => optional, + + /// Only send messages after this date. since: Option = "since" => optional, ] ); generate_element!( + /// Represents a room join request. Muc, "x", MUC, children: [ + /// Password to use when the room is protected by a password. password: Option = ("password", MUC) => String, + + /// Controls how much and how old we want to receive history on join. history: Option = ("history", MUC) => History ] ); diff --git a/src/muc/user.rs b/src/muc/user.rs index bffcbcd9681b964dd45f08d5c3f1b8a8f3cacf4e..bf0fb3080625282a5d0a0aab474d9c0b1772e246 100644 --- a/src/muc/user.rs +++ b/src/muc/user.rs @@ -85,7 +85,10 @@ Status, "status", MUC_USER, "code", { /// JID or to a roomnick. -- CHANGELOG 1.25 (2012-02-08) #[derive(Debug, Clone, PartialEq)] pub enum Actor { + /// The full JID associated with this user. Jid(Jid), + + /// The nickname of this user. Nick(String), } @@ -120,42 +123,93 @@ impl From for Element { } } -generate_element!(Continue, "continue", MUC_USER, -attributes: [ - thread: Option = "thread" => optional, -]); +generate_element!( + /// Used to continue a one-to-one discussion in a room, with more than one + /// participant. + Continue, "continue", MUC_USER, + attributes: [ + /// The thread to continue in this room. + thread: Option = "thread" => optional, + ] +); + +generate_elem_id!( + /// A reason for inviting, declining, etc. a request. + Reason, "reason", MUC_USER +); + +generate_attribute!( + /// The affiliation of an entity with a room, which isn’t tied to its + /// presence in it. + Affiliation, "affiliation", { + /// The user who created the room, or who got appointed by its creator + /// to be their equal. + Owner => "owner", + + /// A user who has been empowered by an owner to do administrative + /// operations. + Admin => "admin", + + /// A user who is whitelisted to speak in moderated rooms, or to join a + /// member-only room. + Member => "member", + + /// A user who has been banned from this room. + Outcast => "outcast", -generate_elem_id!(Reason, "reason", MUC_USER); + /// A normal participant. + None => "none", + }, Default = None +); + +generate_attribute!( + /// The current role of an entity in a room, it can be changed by an owner + /// or an administrator but will be lost once they leave the room. + Role, "role", { + /// This user can kick other participants, as well as grant and revoke + /// them voice. + Moderator => "moderator", -generate_attribute!(Affiliation, "affiliation", { - Owner => "owner", - Admin => "admin", - Member => "member", - Outcast => "outcast", - None => "none", -}, Default = None); + /// A user who can speak in this room. + Participant => "participant", -generate_attribute!(Role, "role", { - Moderator => "moderator", - Participant => "participant", - Visitor => "visitor", - None => "none", -}, Default = None); + /// A user who cannot speak in this room, and must request voice before + /// doing so. + Visitor => "visitor", + + /// A user who is absent from the room. + None => "none", + }, Default = None +); generate_element!( + /// An item representing a user in a room. Item, "item", MUC_USER, attributes: [ + /// The affiliation of this user with the room. affiliation: Affiliation = "affiliation" => required, + + /// The real JID of this user, if you are allowed to see it. jid: Option = "jid" => optional, + + /// The current nickname of this user. nick: Option = "nick" => optional, + + /// The current role of this user. role: Role = "role" => required ], children: [ + /// The actor affected by this item. actor: Option = ("actor", MUC_USER) => Actor, + + /// Whether this continues a one-to-one discussion. continue_: Option = ("continue", MUC_USER) => Continue, + + /// A reason for this item. reason: Option = ("reason", MUC_USER) => Reason ] ); impl Item { + /// Creates a new item with the given affiliation and role. pub fn new(affiliation: Affiliation, role: Role) -> Item { Item { affiliation, @@ -170,8 +224,12 @@ impl Item { } generate_element!( + /// The main muc#user element. MucUser, "x", MUC_USER, children: [ + /// List of statuses applying to this item. status: Vec = ("status", MUC_USER) => Status, + + /// List of items. items: Vec = ("item", MUC_USER) => Item ] );