Doxyfy jupe.h and jupe.c.

git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1208 c9e4aea6-c8fd-4c43-8297-357d70d61c8c

diff --git a/include/jupe.h b/include/jupe.h
index 795d33b9cd0893b5ceecbe7d176e1fd1952e0980..47da2ed7b1ddc6e706371bfa44788dfd1802a138 100644 (file)
--- a/include/jupe.h
+++ b/include/jupe.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  Interface and declarations for juped server handling.
+ * @version $Id$
  */
 #ifndef INCLUDED_sys_types_h
 #include <sys/types.h>
@@ -30,31 +32,40 @@
 
 struct Client;
 
-#define JUPE_MAX_EXPIRE        604800  /* max expire: 7 days */
+#define JUPE_MAX_EXPIRE        604800  /**< Maximum jupe expiration time (7 days). */
 
+/** Describes a juped server.
+ * A hub will not accept new connections from a juped server.
+ */
 struct Jupe {
-  struct Jupe*   ju_next;
-  struct Jupe**  ju_prev_p;
-  char*          ju_server;
-  char*          ju_reason;
-  time_t         ju_expire;
-  time_t         ju_lastmod;
-  unsigned int   ju_flags;
+  struct Jupe*   ju_next;    /**< Pointer to next Jupe. */
+  struct Jupe**  ju_prev_p;  /**< Pointer to previous next pointer. */
+  char*          ju_server;  /**< Name of server to jupe. */
+  char*          ju_reason;  /**< Reason for the jupe. */
+  time_t         ju_expire;  /**< Expiration time of the jupe. */
+  time_t         ju_lastmod; /**< Last modification time (if any) for the jupe. */
+  unsigned int   ju_flags;   /**< Status flags for the jupe. */
 };
 
-#define JUPE_ACTIVE    0x0001
-#define JUPE_LOCAL     0x0002
-#define JUPE_LDEACT    0x0004  /* locally deactivated */
+#define JUPE_ACTIVE    0x0001  /**< Jupe is globally active. */
+#define JUPE_LOCAL     0x0002  /**< Jupe only applies to this server. */
+#define JUPE_LDEACT    0x0004  /**< Jupe is locally deactivated */
 
 #define JUPE_MASK      (JUPE_ACTIVE | JUPE_LOCAL)
 #define JUPE_ACTMASK   (JUPE_ACTIVE | JUPE_LDEACT)
 
+/** Test whether \a j is active. */
 #define JupeIsActive(j)                (((j)->ju_flags & JUPE_ACTMASK) == JUPE_ACTIVE)
+/** Test whether \a j is globally (remotely) active. */
 #define JupeIsRemActive(j)     ((j)->ju_flags & JUPE_ACTIVE)
+/** Test whether \a j is local. */
 #define JupeIsLocal(j)         ((j)->ju_flags & JUPE_LOCAL)
 
+/** Get the server name for \a j. */
 #define JupeServer(j)          ((j)->ju_server)
+/** Get the reason fro \a j. */
 #define JupeReason(j)          ((j)->ju_reason)
+/** Get the last modification time for \a j. */
 #define JupeLastMod(j)         ((j)->ju_lastmod)
 
 extern int jupe_add(struct Client *cptr, struct Client *sptr, char *server,

diff --git a/ircd/jupe.c b/ircd/jupe.c
index 7597ab6002bc1ba7162dc86e5ab88e66f29cbf32..3d69a74f8cfe74359caeca836c69641a5088e2db 100644 (file)
--- a/ircd/jupe.c
+++ b/ircd/jupe.c
@@ -17,8 +17,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 Implementation of juped server handling functions.
+ * @version $Id$
  */
 #include "config.h"
 
@@ -44,8 +46,16 @@
 #include <assert.h>
 #include <string.h>
 
+/** List of jupes. */
 static struct Jupe *GlobalJupeList = 0;
 
+/** Allocate a new jupe with the given parameters.
+ * @param[in] server Server name to jupe.
+ * @param[in] reason Reason for jupe.
+ * @param[in] expire Expiration time for jupe.
+ * @param[in] lastmod Last modification time for jupe.
+ * @param[in] flags Flags to set for the jupe.
+ */
 static struct Jupe *
 make_jupe(char *server, char *reason, time_t expire, time_t lastmod,
          unsigned int flags)
@@ -70,6 +80,11 @@ make_jupe(char *server, char *reason, time_t expire, time_t lastmod,
   return ajupe;
 }
 
+/** Apply a jupe.
+ * @param[in] cptr Local client that sent us the jupe.
+ * @param[in] sptr Originator of the jupe.
+ * @param[in] jupe Jupe to check.
+ */
 static int
 do_jupe(struct Client *cptr, struct Client *sptr, struct Jupe *jupe)
 {
@@ -87,6 +102,11 @@ do_jupe(struct Client *cptr, struct Client *sptr, struct Jupe *jupe)
   return exit_client_msg(cptr, acptr, &me, "Juped: %s", jupe->ju_reason);
 }
 
+/** Forward a jupe to another server.
+ * @param[in] cptr Local client that sent us the jupe.
+ * @param[in] sptr Originator of the jupe.
+ * @param[in] jupe Jupe to forward.
+ */
 static void
 propagate_jupe(struct Client *cptr, struct Client *sptr, struct Jupe *jupe)
 {
@@ -99,6 +119,17 @@ propagate_jupe(struct Client *cptr, struct Client *sptr, struct Jupe *jupe)
                        jupe->ju_reason);
 }
 
+/** Add a new server jupe.
+ * @param[in] cptr Local client that sent us the jupe.
+ * @param[in] sptr Originator of the jupe.
+ * @param[in] server Server name to jupe.
+ * @param[in] reason Reason for the jupe.
+ * @param[in] expire Jupe duration in seconds.
+ * @param[in] lastmod Last modification timestamp (or NULL).
+ * @param[in] flags Flags to set on jupe.
+ * @return Zero, unless the jupe causes \a cptr to be SQUIT, in which
+ * case CPTR_KILLED.
+ */
 int
 jupe_add(struct Client *cptr, struct Client *sptr, char *server, char *reason,
         time_t expire, time_t lastmod, unsigned int flags)
@@ -142,6 +173,15 @@ jupe_add(struct Client *cptr, struct Client *sptr, char *server, char *reason,
   return do_jupe(cptr, sptr, ajupe); /* remove server if necessary */
 }
 
+/** Activate a jupe, optionally changing its lastmod and flags.
+ * @param[in] cptr Local client that sent us the jupe.
+ * @param[in] sptr Originator of the jupe.
+ * @param[in] jupe Jupe to activate.
+ * @param[in] lastmod New timestamp for last modification of the jupe.
+ * @param[in] flags Flags to set on the jupe.
+ * @return Zero, unless the jupe causes \a cptr to be SQUIT, in which
+ * case CPTR_KILLED.
+ */
 int
 jupe_activate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe,
              time_t lastmod, unsigned int flags)
@@ -185,6 +225,14 @@ jupe_activate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe,
   return do_jupe(cptr, sptr, jupe);
 }
 
+/** Deactivate a jupe.
+ * @param[in] cptr Local client that sent us the jupe.
+ * @param[in] sptr Originator of the jupe.
+ * @param[in] jupe Jupe to deactivate.
+ * @param[in] lastmod New timestamp for last modification of the jupe.
+ * @param[in] flags Flags to set on the jupe.
+ * @return Zero.
+ */
 int
 jupe_deactivate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe,
                time_t lastmod, unsigned int flags)
@@ -234,6 +282,10 @@ jupe_deactivate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe,
   return 0;
 }
 
+/** Find a jupe by name.
+ * @param[in] server %Jupe name to search for.
+ * @return Matching jupe (or NULL if none match).
+ */
 struct Jupe *
 jupe_find(char *server)
 {
@@ -252,6 +304,9 @@ jupe_find(char *server)
   return 0;
 }
 
+/** Unlink and free an unused jupe.
+ * @param[in] jupe Server jupe to free.
+ */
 void
 jupe_free(struct Jupe* jupe)
 {
@@ -266,6 +321,9 @@ jupe_free(struct Jupe* jupe)
   MyFree(jupe);
 }
 
+/** Send the full list of active global jupes to \a cptr.
+ * @param[in] cptr Local server to send jupes to.
+ */
 void
 jupe_burst(struct Client *cptr)
 {
@@ -285,6 +343,10 @@ jupe_burst(struct Client *cptr)
   }
 }
 
+/** Forward a jupe to another server.
+ * @param[in] cptr %Server to send jupe to.
+ * @param[in] jupe Jupe to forward.
+ */
 int
 jupe_resend(struct Client *cptr, struct Jupe *jupe)
 {
@@ -299,6 +361,11 @@ jupe_resend(struct Client *cptr, struct Jupe *jupe)
   return 0;
 }
 
+/** Send a jupe (or a list of jupes) to a server.
+ * @param[in] sptr Client searching for jupes.
+ * @param[in] server Name of jupe to search for (if NULL, list all).
+ * @return Zero.
+ */
 int
 jupe_list(struct Client *sptr, char *server)
 {
@@ -331,6 +398,10 @@ jupe_list(struct Client *sptr, char *server)
   return send_reply(sptr, RPL_ENDOFJUPELIST);
 }
 
+/** Count jupes and memory used by them.
+ * @param[out] ju_size Receives total number of bytes allocated for jupes.
+ * @return Number of jupes currently allocated.
+ */
 int
 jupe_memory_count(size_t *ju_size)
 {