Document the Membership and the Invitation class

diff --git a/include/membership.h b/include/membership.h
index 44eaf1eb6c2d39f404b8c144b6b047ec40c7c722..e2c13c7e4ff4dfbb158ea6aa2b542d95c3913d54 100644 (file)
--- a/include/membership.h
+++ b/include/membership.h
@@ -20,18 +20,50 @@
 
 #pragma once
 
+/**
+ * Represents a member of a channel.
+ * A Membership object is created when a user joins a channel, and destroyed when a user leaves
+ * (via kick, part or quit) a channel.
+ * All prefix modes a member has is tracked by this object. Moreover, Memberships are Extensibles
+ * meaning modules can add arbitrary data to them using extensions (see m_delaymsg for an example).
+ */
 class CoreExport Membership : public Extensible, public intrusive_list_node<Membership>
 {
  public:
+       /** User on the channel
+        */
        User* const user;
+
+       /** Channel the user is on
+        */
        Channel* const chan;
-       // mode list, sorted by prefix rank, higest first
+
+       /** List of prefix mode letters this member has,
+        * sorted by prefix rank, highest first
+        */
        std::string modes;
+
+       /** Constructor, sets the user and chan fields to the parameters, does NOT update any bookkeeping
+        * information in the User or the Channel.
+        * Call Channel::JoinUser() or ForceJoin() to make a user join a channel instead of constructing
+        * Membership objects directly.
+        */
        Membership(User* u, Channel* c) : user(u), chan(c) {}
+
+       /** Returns true if this member has a given prefix mode set
+        * @param m The prefix mode letter to check
+        * @return True if the member has the prefix mode set, false otherwise
+        */
        inline bool hasMode(char m) const
        {
                return modes.find(m) != std::string::npos;
        }
+
+       /** Returns the rank of this member.
+        * The rank of a member is defined as the rank given by the 'strongest' prefix mode a
+        * member has. See the PrefixMode class description for more info.
+        * @return The rank of the member
+        */
        unsigned int getRank();
 
        /** Add a prefix character to a user.
@@ -65,25 +97,68 @@ template <typename T>
 class InviteBase
 {
  protected:
+       /** List of pending Invitations
+        */
        intrusive_list<Invitation, T> invites;
 
  public:
+       /** Remove and destruct all pending invitations this user or channel has.
+        * Must be called before the object is destroyed, also called when the TS of the channel is lowered.
+        */
        void ClearInvites();
 
        friend class Invitation;
 };
 
+/**
+ * The Invitation class contains all data about a pending invitation.
+ * Invitation objects are referenced from the user and the channel they belong to.
+ */
 class CoreExport Invitation : public intrusive_list_node<Invitation, Channel>, public intrusive_list_node<Invitation, LocalUser>
 {
+       /** Constructs an Invitation, only called by Create()
+        * @param c Channel the user is invited to
+        * @param u User being invited
+        * @param timeout Expiration time for this Invitation
+        */
        Invitation(Channel* c, LocalUser* u, time_t timeout) : user(u), chan(c), expiry(timeout) {}
 
  public:
+       /** User the invitation is for
+        */
        LocalUser* const user;
+
+       /** Channel where the user is invited to
+        */
        Channel* const chan;
+
+       /** Timestamp when this Invitation expires or 0 if it doesn't expire.
+        * Invitation::Create() can update this field; see that for more info.
+        */
        time_t expiry;
 
+       /** Destructor
+        * Removes references to this Invitation from the associated user and channel.
+        */
        ~Invitation();
+
+       /** Create or extend an Invitation.
+        * When a user is invited to join a channel either a new Invitation object is created or
+        * or the expiration timestamp is updated if there is already a pending Invitation for
+        * the given (user, channel) pair and the new expiration time is further than the current.
+        * @param c Target channel
+        * @param u Target user
+        * @param timeout Timestamp when the invite should expire, 0 for no expiration
+        */
        static void Create(Channel* c, LocalUser* u, time_t timeout);
+
+       /** Finds the Invitation object for the given channel/user pair.
+        * @param c Target channel, can be NULL to remove expired entries
+        * @param u Target user, cannot be NULL
+        * @param check_expired Pass true to remove all expired invites found while searching, false
+        * to return with an Invitation even if it's expired
+        * @return Invitation object for the given (channel, user) pair if it exists, NULL otherwise
+        */
        static Invitation* Find(Channel* c, LocalUser* u, bool check_expired = true);
 };
 
@@ -95,6 +170,7 @@ inline void InviteBase<T>::ClearInvites()
        for (typename intrusive_list<Invitation, T>::iterator i = invites.begin(); i != invites.end(); )
        {
                Invitation* inv = *i;
+               // Destructing the Invitation invalidates the iterator, so move it now
                ++i;
                delete inv;
        }