Browse code

doxygen: convert existing documentation to doxygen, small whitespace cleanup

Henning Westerholt authored on 23/06/2011 22:25:09
Showing 2 changed files
... ...
@@ -23,7 +23,7 @@
23 23
 
24 24
 /*!
25 25
  * \file
26
- * \brief SIP-router core :: 
26
+ * \brief SIP-router core :: md5 hash support
27 27
  * \ingroup core
28 28
  * Module: \ref core
29 29
  */
... ...
@@ -34,9 +34,11 @@
34 34
 #include "md5.h"
35 35
 
36 36
 
37
-/* Constants for MD5Transform routine.
37
+/**
38
+ * \brief Constants for MD5Transform routine.
38 39
  */
39 40
 
41
+/*@{ */
40 42
 #define S11 7
41 43
 #define S12 12
42 44
 #define S13 17
... ...
@@ -53,6 +55,7 @@
53 53
 #define S42 10
54 54
 #define S43 15
55 55
 #define S44 21
56
+/*@} */
56 57
 
57 58
 static void MD5Transform PROTO_LIST ((UINT4 [4], unsigned char [64]));
58 59
 static void Encode PROTO_LIST
... ...
@@ -66,20 +69,30 @@ static unsigned char PADDING[64] = {
66 66
   0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
67 67
 };
68 68
 
69
-/* F, G, H and I are basic MD5 functions.
69
+/**
70
+ * \brief F, G, H and I are basic MD5 functions.
70 71
  */
72
+
73
+/*@{ */
71 74
 #define F(x, y, z) (((x) & (y)) | ((~x) & (z)))
72 75
 #define G(x, y, z) (((x) & (z)) | ((y) & (~z)))
73 76
 #define H(x, y, z) ((x) ^ (y) ^ (z))
74 77
 #define I(x, y, z) ((y) ^ ((x) | (~z)))
78
+/*@} */
75 79
 
76
-/* ROTATE_LEFT rotates x left n bits.
80
+/**
81
+ * \brief ROTATE_LEFT rotates x left n bits.
77 82
  */
78 83
 #define ROTATE_LEFT(x, n) (((x) << (n)) | ((x) >> (32-(n))))
79 84
 
80
-/* FF, GG, HH, and II transformations for rounds 1, 2, 3, and 4.
81
-Rotation is separate from addition to prevent recomputation.
85
+/**
86
+ * \brief FF, GG, HH, and II transformations for rounds 1, 2, 3, and 4.
87
+ * 
88
+ * FF, GG, HH, and II transformations for rounds 1, 2, 3, and 4.
89
+ * Rotation is separate from addition to prevent recomputation.
82 90
  */
91
+
92
+/*@{ */
83 93
 #define FF(a, b, c, d, x, s, ac) { \
84 94
  (a) += F ((b), (c), (d)) + (x) + (UINT4)(ac); \
85 95
  (a) = ROTATE_LEFT ((a), (s)); \
... ...
@@ -100,11 +113,16 @@ Rotation is separate from addition to prevent recomputation.
100 100
  (a) = ROTATE_LEFT ((a), (s)); \
101 101
  (a) += (b); \
102 102
   }
103
+/*@} */
103 104
 
104
-/* MD5 initialization. Begins an MD5 operation, writing a new context.
105
+/**
106
+ * \brief MD5 context initialization
107
+ * 
108
+ * MD5 context initialization. Begins an MD5 operation, writing a new context.
109
+ * \param context initialized context
105 110
  */
106 111
 void MD5Init (context)
107
-MD5_CTX *context;                                        /* context */
112
+MD5_CTX *context;
108 113
 {
109 114
   context->count[0] = context->count[1] = 0;
110 115
   /* Load magic initialization constants.
... ...
@@ -115,14 +133,20 @@ MD5_CTX *context;                                        /* context */
115 115
   context->state[3] = 0x10325476;
116 116
 }
117 117
 
118
-/* MD5 block update operation. Continues an MD5 message-digest
119
-  operation, processing another message block, and updating the
120
-  context.
118
+/**
119
+ * \brief MD5 block update operation
120
+ * 
121
+ * MD5 block update operation. Continues an MD5 message-digest
122
+ * operation, processing another message block, and updating the
123
+ * context.
124
+ * \param context context
125
+ * \param input input block
126
+ * \param inputLen length of input block
121 127
  */
122 128
 void MD5Update (context, input, inputLen)
123
-MD5_CTX *context;                                        /* context */
124
-unsigned char *input;                                /* input block */
125
-unsigned int inputLen;                     /* length of input block */
129
+MD5_CTX *context;
130
+unsigned char *input;
131
+unsigned int inputLen;
126 132
 {
127 133
   unsigned int i, index, partLen;
128 134
 
... ...
@@ -159,12 +183,17 @@ unsigned int inputLen;                     /* length of input block */
159 159
   inputLen-i);
160 160
 }
161 161
 
162
-/* MD5 finalization. Ends an MD5 message-digest operation, writing the
163
-  the message digest and zeroizing the context.
162
+/**
163
+ * \brief MD5 finalization
164
+ * 
165
+ * MD5 finalization. Ends an MD5 message-digest operation, writing the
166
+ * the message digest and zeroizing the context.
167
+ * \param digest message digest
168
+ * \param context context
164 169
  */
165 170
 void MD5Final (digest, context)
166
-unsigned char digest[16];                         /* message digest */
167
-MD5_CTX *context;                                       /* context */
171
+unsigned char digest[16];
172
+MD5_CTX *context;
168 173
 {
169 174
   unsigned char bits[8];
170 175
   unsigned int index, padLen;
... ...
@@ -189,7 +218,12 @@ MD5_CTX *context;                                       /* context */
189 189
   memset ((POINTER)context, 0, sizeof (*context));
190 190
 }
191 191
 
192
-/* MD5 basic transformation. Transforms state based on block.
192
+/**
193
+ * \brief MD5 basic transformation
194
+ * 
195
+ * MD5 basic transformation. Transforms state based on block.
196
+ * \param state transformed state
197
+ * \param block block input for transformation
193 198
  */
194 199
 static void MD5Transform (state, block)
195 200
 UINT4 state[4];
... ...
@@ -281,8 +315,14 @@ unsigned char block[64];
281 281
   memset ((POINTER)x, 0, sizeof (x));
282 282
 }
283 283
 
284
-/* Encodes input (UINT4) into output (unsigned char). Assumes len is
285
-  a multiple of 4.
284
+/**
285
+ * \brief Encodes input (UINT4) into output (unsigned char)
286
+ * 
287
+ * Encodes input (UINT4) into output (unsigned char). Assumes len is
288
+ * a multiple of 4.
289
+ * \param output output character
290
+ * \param input integer input
291
+ * \param len length of output
286 292
  */
287 293
 static void Encode (output, input, len)
288 294
 unsigned char *output;
... ...
@@ -299,8 +339,14 @@ unsigned int len;
299 299
   }
300 300
 }
301 301
 
302
-/* Decodes input (unsigned char) into output (UINT4). Assumes len is
303
-  a multiple of 4.
302
+/**
303
+ * \brief Decodes input (unsigned char) into output (UINT4)
304
+ * 
305
+ * Decodes input (unsigned char) into output (UINT4). Assumes len is
306
+ * a multiple of 4.
307
+ * \param output output integer
308
+ * \param input input character
309
+ * \param len length of input
304 310
  */
305 311
 static void Decode (output, input, len)
306 312
 UINT4 *output;
... ...
@@ -1,28 +1,24 @@
1
-/* MD5.H - header file for MD5C.C
2
- * $Id$
3
- */
4
-
5
-
6
-/* Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All
7
-rights reserved.
8
-
9
-License to copy and use this software is granted provided that it
10
-is identified as the "RSA Data Security, Inc. MD5 Message-Digest
11
-Algorithm" in all material mentioning or referencing this software
12
-or this function.
13
-
14
-License is also granted to make and use derivative works provided
15
-that such works are identified as "derived from the RSA Data
16
-Security, Inc. MD5 Message-Digest Algorithm" in all material
17
-mentioning or referencing the derived work.
18
-
19
-RSA Data Security, Inc. makes no representations concerning either
20
-the merchantability of this software or the suitability of this
21
-software for any particular purpose. It is provided "as is"
22
-without express or implied warranty of any kind.
23
-
24
-These notices must be retained in any copies of any part of this
25
-documentation and/or software.
1
+/*
2
+ * Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All
3
+ * rights reserved.
4
+ * 
5
+ * License to copy and use this software is granted provided that it
6
+ * is identified as the "RSA Data Security, Inc. MD5 Message-Digest
7
+ * Algorithm" in all material mentioning or referencing this software
8
+ * or this function.
9
+ * 
10
+ * License is also granted to make and use derivative works provided
11
+ * that such works are identified as "derived from the RSA Data
12
+ * Security, Inc. MD5 Message-Digest Algorithm" in all material
13
+ * mentioning or referencing the derived work.
14
+ * 
15
+ * RSA Data Security, Inc. makes no representations concerning either
16
+ * the merchantability of this software or the suitability of this
17
+ * software for any particular purpose. It is provided "as is"
18
+ * without express or implied warranty of any kind.
19
+ * 
20
+ * These notices must be retained in any copies of any part of this
21
+ * documentation and/or software.
26 22
  */
27 23
 
28 24
 #ifndef MD5_H
... ...
@@ -30,16 +26,44 @@ documentation and/or software.
30 30
 
31 31
 #include "md5global.h"
32 32
 
33
-/* MD5 context. */
33
+/**
34
+ * \brief MD5 context
35
+ */
34 36
 typedef struct {
35 37
   UINT4 state[4];                                   /* state (ABCD) */
36 38
   UINT4 count[2];        /* number of bits, modulo 2^64 (lsb first) */
37 39
   unsigned char buffer[64];                         /* input buffer */
38 40
 } MD5_CTX;
39 41
 
42
+/**
43
+ * \brief MD5 context initialization
44
+ * 
45
+ * MD5 context initialization. Begins an MD5 operation, writing a new context.
46
+ * \param context initialized context
47
+ */
40 48
 void MD5Init PROTO_LIST ((MD5_CTX *));
49
+
50
+/**
51
+ * \brief MD5 block update operation
52
+ * 
53
+ * MD5 block update operation. Continues an MD5 message-digest
54
+ * operation, processing another message block, and updating the
55
+ * context.
56
+ * \param context context
57
+ * \param input input block
58
+ * \param inputLen length of input block
59
+ */
41 60
 void MD5Update PROTO_LIST
42 61
   ((MD5_CTX *, unsigned char *, unsigned int));
62
+
63
+  /**
64
+ * \brief MD5 finalization
65
+ * 
66
+ * MD5 finalization. Ends an MD5 message-digest operation, writing the
67
+ * the message digest and zeroizing the context.
68
+ * \param digest message digest
69
+ * \param context context
70
+ */
43 71
 void MD5Final PROTO_LIST ((unsigned char [16], MD5_CTX *));
44 72
 
45 73
 #endif /* MD5_H */