Doxyfy gline.h and gline.c.

[ircu2.10.12-pk.git] / include / gline.h

diff --git a/include/gline.h b/include/gline.h
index f3f88eb172c4be74cfa2afd3116c6345180c1200..7576f07b2694e12bb1502b870a50c99c850975ab 100644 (file)
--- a/include/gline.h
+++ b/include/gline.h
@@ -19,8 +19,10 @@
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * $Id$
+ */
+/* @file
+ * @brief Structures and APIs for G-line manipulation.
+ * @version $Id$
  */
 #ifndef INCLUDED_sys_types_h
 #include <sys/types.h>
@@ -34,48 +36,61 @@
 struct Client;
 struct StatDesc;
 
-#define GLINE_MAX_EXPIRE 604800        /* max expire: 7 days */
+#define GLINE_MAX_EXPIRE 604800        /**< max expire: 7 days */
 
+/** Description of a G-line. */
 struct Gline {
-  struct Gline *gl_next;
-  struct Gline**gl_prev_p;
-  char        *gl_user;
-  char        *gl_host;
-  char        *gl_reason;
-  time_t       gl_expire;
-  time_t       gl_lastmod;
-  struct irc_in_addr gl_addr;  /* We store the IP in binary for ip glines */
-  unsigned char gl_bits;
-  unsigned int gl_flags;
+  struct Gline *gl_next;      /**< Next G-line in linked list. */
+  struct Gline**gl_prev_p;    /**< Previous pointer to this G-line. */
+  char        *gl_user;      /**< Username mask (or channel/realname mask). */
+  char        *gl_host;      /**< Host prtion of mask. */
+  char        *gl_reason;    /**< Reason for G-line. */
+  time_t       gl_expire;    /**< Expiration timestamp. */
+  time_t       gl_lastmod;   /**< Last modification timestamp. */
+  struct irc_in_addr gl_addr; /**< IP address (for IP-based G-lines). */
+  unsigned char gl_bits;      /**< Usable bits in gl_addr. */
+  unsigned int gl_flags;     /**< G-line status flags. */
 };
 
-#define GLINE_ACTIVE   0x0001
-#define GLINE_IPMASK   0x0002
-#define GLINE_BADCHAN  0x0004
-#define GLINE_LOCAL    0x0008
-#define GLINE_ANY      0x0010
-#define GLINE_FORCE    0x0020
-#define GLINE_EXACT    0x0040
-#define GLINE_LDEACT   0x0080  /* locally deactivated */
-#define GLINE_GLOBAL   0x0100  /* find only global glines */
-#define GLINE_LASTMOD  0x0200  /* find only glines with non-zero lastmod */
-#define GLINE_OPERFORCE        0x0400  /* oper forcing gline to be set */
-#define GLINE_REALNAME  0x0800  /* gline matches only the realname field */
+#define GLINE_ACTIVE   0x0001  /**< G-line is active. */
+#define GLINE_IPMASK   0x0002  /**< gl_addr and gl_bits fields are valid. */
+#define GLINE_BADCHAN  0x0004  /**< G-line prohibits users from joining a channel. */
+#define GLINE_LOCAL    0x0008  /**< G-line only applies to this server. */
+#define GLINE_ANY      0x0010  /**< Search flag: Find any G-line. */
+#define GLINE_FORCE    0x0020  /**< Override normal limits on G-lines. */
+#define GLINE_EXACT    0x0040  /**< Exact match only (no wildcards). */
+#define GLINE_LDEACT   0x0080  /**< Locally deactivated. */
+#define GLINE_GLOBAL   0x0100  /**< Find only global G-lines. */
+#define GLINE_LASTMOD  0x0200  /**< Find only G-lines with non-zero lastmod. */
+#define GLINE_OPERFORCE        0x0400  /**< Oper forcing G-line to be set. */
+#define GLINE_REALNAME  0x0800  /**< G-line matches only the realname field. */
 
+/** Controllable flags that can be set on an actual G-line. */
 #define GLINE_MASK     (GLINE_ACTIVE | GLINE_BADCHAN | GLINE_LOCAL | GLINE_REALNAME)
+/** Mask for G-line activity flags. */
 #define GLINE_ACTMASK  (GLINE_ACTIVE | GLINE_LDEACT)
 
+/** Test whether \a g is active. */
 #define GlineIsActive(g)       (((g)->gl_flags & GLINE_ACTMASK) == \
                                 GLINE_ACTIVE)
+/** Test whether \a g is remotely (globally) active. */
 #define GlineIsRemActive(g)    ((g)->gl_flags & GLINE_ACTIVE)
+/** Test whether \a g is an IP-based G-line. */
 #define GlineIsIpMask(g)       ((g)->gl_flags & GLINE_IPMASK)
+/** Test whether \a g is a realname-based G-line. */
 #define GlineIsRealName(g)      ((g)->gl_flags & GLINE_REALNAME)
+/** Test whether \a g is a BADCHAN. */
 #define GlineIsBadChan(g)      ((g)->gl_flags & GLINE_BADCHAN)
+/** Test whether \a g is local to this server. */
 #define GlineIsLocal(g)                ((g)->gl_flags & GLINE_LOCAL)
 
+/** Return user mask of a G-line. */
 #define GlineUser(g)           ((g)->gl_user)
+/** Return host mask of a G-line. */
 #define GlineHost(g)           ((g)->gl_host)
+/** Return reason/message of a G-line. */
 #define GlineReason(g)         ((g)->gl_reason)
+/** Return last modification time of a G-line. */
 #define GlineLastMod(g)                ((g)->gl_lastmod)
 
 extern int gline_propagate(struct Client *cptr, struct Client *sptr,