Doxyfy ircd_md5.h and ircd_md5.c.

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

diff --git a/include/ircd_md5.h b/include/ircd_md5.h
index 69332dd602af478f8879df01e481b6ebd2105d54..732a6e981beb69bc09e71a0ca213367cec7f6ffc 100644 (file)
--- a/include/ircd_md5.h
+++ b/include/ircd_md5.h
@@ -12,20 +12,25 @@
  * with every copy.
  *
  * ircuified 2002 by hikari
- *
- * $Id$
-*/
+ */
+/** @file
+ * @brief MD5 implementation for ircu.
+ * @version $Id$
+ */
 #ifndef ircd_md5_h
 #define ircd_md5_h
 
+/** Macro to prepend MD5 variant to a function name. */
 #define MD5Name(x) Good##x
 
+/** Typedef for an unsigned 32-bit integer. */
 typedef unsigned int uint32;
 
+/** MD5 context structure. */
 struct MD5Context {
-       uint32 buf[4];
-       uint32 bits[2];
-       unsigned char in[64];
+       uint32 buf[4];        /**< Current digest state/value. */
+       uint32 bits[2];       /**< Number of bits hashed so far. */
+       unsigned char in[64]; /**< Residual input buffer. */
 };
 
 void GoodMD5Init(struct MD5Context *);
@@ -40,10 +45,7 @@ void BrokenMD5Transform(uint32 buf[4], uint32 const in[16]);
 char *Goodcrypt_md5(const char *pw, const char *salt);
 char *Brokencrypt_md5(const char *pw, const char *salt);
 
-/*
- * This is needed to make RSAREF happy on some MS-DOS compilers.
- */
-
+/** Helper typedef for the MD5 context structure. */
 typedef struct MD5Context MD5_CTX;
 
 #endif /* ircd_md5_h */

diff --git a/ircd/ircd_md5.c b/ircd/ircd_md5.c
index b5b15d46981ad863a7c007bc370284f02fe223c2..a450c3a4eb9888f779343c84d2f2bd3a465da788 100644 (file)
--- a/ircd/ircd_md5.c
+++ b/ircd/ircd_md5.c
@@ -25,6 +25,7 @@
 #include "ircd_md5.h"
 
 #ifndef HIGHFIRST
+/** Bit-reverse bytes in a buffer. */
 #define byteReverse(buf, len)  /* Nothing */
 #else
 static void byteReverse(unsigned char *buf, unsigned longs);
@@ -46,9 +47,8 @@ static void byteReverse(unsigned char *buf, unsigned longs)
 #endif
 #endif
 
-/*
- * Start MD5 accumulation.  Set bit count to 0 and buffer to mysterious
- * initialization constants.
+/** Iniitalize MD5 context.
+ * @param[out] ctx MD5 context to initialize.
  */
 void MD5Name(MD5Init)(struct MD5Context *ctx)
 {
@@ -61,9 +61,10 @@ void MD5Name(MD5Init)(struct MD5Context *ctx)
        ctx->bits[1] = 0;
 }
 
-/*
- * Update context to reflect the concatenation of another buffer full
- * of bytes.
+/** Update MD5 context with data from a buffer.
+ * @param[in,out] ctx MD5 context to operate on.
+ * @param[in] buf Input buffer.
+ * @param[in] len Number of bytes in input buffer.
  */
 void MD5Name(MD5Update)(struct MD5Context *ctx, unsigned const char *buf, unsigned len)
 {
@@ -109,9 +110,9 @@ void MD5Name(MD5Update)(struct MD5Context *ctx, unsigned const char *buf, unsign
        memcpy(ctx->in, buf, len);
 }
 
-/*
- * Final wrapup - pad to 64-byte boundary with the bit pattern 
- * 1 0* (64-bit count of bits processed, MSB-first)
+/** Perform final steps of MD5 hash.
+ * @param[out] digest Receives output hash value.
+ * @param[in,out] ctx MD5 context to finalize.
  */
 void MD5Name(MD5Final)(unsigned char digest[16], struct MD5Context *ctx)
 {
@@ -159,19 +160,23 @@ void MD5Name(MD5Final)(unsigned char digest[16], struct MD5Context *ctx)
 /* The four core functions - F1 is optimized somewhat */
 
 /* #define F1(x, y, z) (x & y | ~x & z) */
+/** Helper function for first round of MD5. */
 #define F1(x, y, z) (z ^ (x & (y ^ z)))
+/** Helper function for second round of MD5. */
 #define F2(x, y, z) F1(z, x, y)
+/** Helper function for third round of MD5. */
 #define F3(x, y, z) (x ^ y ^ z)
+/** Helper function for fourth round of MD5. */
 #define F4(x, y, z) (y ^ (x | ~z))
 
-/* This is the central step in the MD5 algorithm. */
+/** Step function for each round of MD5 */
 #define MD5STEP(f, w, x, y, z, data, s) \
        ( w += f(x, y, z) + data,  w = w<<s | w>>(32-s),  w += x )
 
-/*
- * The core of the MD5 algorithm, this alters an existing MD5 hash to
- * reflect the addition of 16 longwords of new data.  MD5Update blocks
- * the data and converts bytes into longwords for this routine.
+/** Perform the core MD5 update steps to update a 128-bit hash value
+ * with 512 bits of input data.
+ * @param[in,out] buf Hash value.
+ * @param[in] in Input buffer.
  */
 void MD5Name(MD5Transform)(uint32 buf[4], uint32 const in[16])
 {