From ba41da69fda6fa9a2388e50a00e97992f509145d Mon Sep 17 00:00:00 2001
From: David Sommerseth <dazo@users.sourceforge.net>
Date: Fri, 11 Sep 2009 11:15:04 +0200
Subject: Some simple comments to the SHA512 implementation

---
 common/sha512.c | 32 ++++++++++++++++++++++++++++++--
 common/sha512.h | 26 ++++++++++++++++++++------
 2 files changed, 50 insertions(+), 8 deletions(-)

diff --git a/common/sha512.c b/common/sha512.c
index a09a5aa..2462424 100644
--- a/common/sha512.c
+++ b/common/sha512.c
@@ -65,6 +65,10 @@ static const char rcsid[] =
 	"$Id: sha512.c 680 2003-07-25 21:58:07Z asaddi $";
 #endif /* !lint */
 
+
+/**
+ * @{
+ */
 #define ROTL(x, n) (((x) << (n)) | ((x) >> (32 - (n))))
 #define ROTR(x, n) (((x) >> (n)) | ((x) << (32 - (n))))
 #define ROTL64(x, n) (((x) << (n)) | ((x) >> (64 - (n))))
@@ -164,6 +168,11 @@ static inline uint64_t _byteswap64(uint64_t x)
 		      (ROTL((x), 8) & 0x00ff00ffL))
 #define _BYTESWAP64(x) __byteswap64(x)
 
+/**
+ * @}
+ */
+
+
 static inline uint64_t __byteswap64(uint64_t x)
 {
   uint32_t a = x >> 32;
@@ -219,6 +228,11 @@ static const uint8_t padding[128] = {
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
 };
 
+/**
+ * Initiates a new SHA512 context with needed values
+ *
+ * @param sc SHA512Context
+ */
 void
 SHA512Init (SHA512Context *sc)
 {
@@ -303,6 +317,14 @@ SHA512Guts (SHA512Context *sc, const uint64_t *cbuf)
   sc->hash[7] += h;
 }
 
+
+/**
+ * Feeds the SHA512 with data for calculating the hash
+ *
+ * @param sc     SHA512Context
+ * @param vdata  Pointer to the data
+ * @param len    Length of the data
+ */
 void
 SHA512Update (SHA512Context *sc, const void *vdata, uint32_t len)
 {
@@ -392,8 +414,14 @@ SHA512Update (SHA512Context *sc, const void *vdata, uint32_t len)
     burnStack (sizeof (uint64_t[90]) + sizeof (uint64_t *[6]) + sizeof (int));
 }
 
-void
-SHA512Final (SHA512Context *sc, uint8_t hash[SHA512_HASH_SIZE])
+
+/**
+ * Completes the calculation and returns a SHA512 hash.
+ *
+ * @param sc   SHA512Context
+ * @param hash Array where the hash result will be put
+ */
+void SHA512Final (SHA512Context *sc, uint8_t hash[SHA512_HASH_SIZE])
 {
   uint32_t bytesToPad;
   uint64_t lengthPad[2];
diff --git a/common/sha512.h b/common/sha512.h
index 5639790..39eb01e 100644
--- a/common/sha512.h
+++ b/common/sha512.h
@@ -46,35 +46,49 @@
 
 #include <stdint.h>
 
+/**
+ * Hash size
+ */
 #define SHA512_HASH_SIZE 64
 
-/* Hash size in 64-bit words */
+/**
+ *Hash size in 64-bit words
+*/
 #define SHA512_HASH_WORDS 8
 
 /**
- * SHA512 context, used during creating the SHA512 hash
+ * SHA512 context, used during calculation if SHA512 hashes
  */
 struct _SHA512Context {
-  uint64_t totalLength[2];
-  uint64_t hash[SHA512_HASH_WORDS];
-  uint32_t bufferLength;
+  uint64_t totalLength[2];	    /**<  */
+  uint64_t hash[SHA512_HASH_WORDS]; /**<  */
+  uint32_t bufferLength;	    /**<  */
   union {
     uint64_t words[16];
     uint8_t bytes[128];
-  } buffer;
+  } buffer;			    /**<  */
 #ifdef RUNTIME_ENDIAN
   int littleEndian;
 #endif /* RUNTIME_ENDIAN */
 };
 
+/**
+ * @copydoc _SHA512Context
+ */
 typedef struct _SHA512Context SHA512Context;
 
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 void SHA512Init (SHA512Context *sc);
 void SHA512Update (SHA512Context *sc, const void *data, uint32_t len);
+
+/**
+ * @copydoc SHA512Final()
+ */
+/* Strange that this functino needs @copydoc .... */
 void SHA512Final (SHA512Context *sc, uint8_t hash[SHA512_HASH_SIZE]);
 
 #ifdef __cplusplus
-- 
cgit