Add another big set of doxygen documentation improvements from snuffy.

(closes issue #9892)
(closes issue #10395)


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@78541 65c4cc65-6c06-0410-ace0-fbb531ad65f3

main/sha1.c

@@ -1,6 +1,6 @@
-/*
+/*! \file
  *
- * Based on the RFC 3174
+ * \brief Based on the RFC 3174
  * 
  * Full Copyright Statement
  *
@@ -63,9 +63,7 @@
 
 #include "asterisk/sha1.h"
 
-/*
- *  Define the SHA1 circular left shift macro
- */
+/*! Define the SHA1 circular left shift macro */
 #define SHA1CircularShift(bits,word) \
 		         (((word) << (bits)) | ((word) >> (32-(bits))))
 
@@ -73,20 +71,12 @@
 void SHA1PadMessage(SHA1Context *);
 void SHA1ProcessMessageBlock(SHA1Context *);
 
-/*
- *  SHA1Reset
- *
- *  Description:
- *	  This function will initialize the SHA1Context in preparation
- *	  for computing a new SHA1 message digest.
- *
- *  Parameters:
- *	  context: [in/out]
- *		   The context to reset.
- *
- *  Returns:
- *	  sha Error Code.
- *
+/*!
+ * \brief SHA1Reset
+ * \param context the context to be reset
+ * This function will initialize the SHA1Context in preparation
+ * for computing a new SHA1 message digest.
+ * \return sha Error Code.
  */
 int SHA1Reset(SHA1Context *context)
 {
@@ -110,24 +100,15 @@ int SHA1Reset(SHA1Context *context)
 	return shaSuccess;
 }
 
-/*
- *  SHA1Result
- *
- *  Description:
- *	  This function will return the 160-bit message digest into the
- *	  Message_Digest array  provided by the caller.
- *	  NOTE: The first octet of hash is stored in the 0th element,
- *		     the last octet of hash in the 19th element.
- *
- *  Parameters:
- *	  context: [in/out]
- *		   The context to use to calculate the SHA-1 hash.
- *	  Message_Digest: [out]
- *		   Where the digest is returned.
- *
- *  Returns:
- *	  sha Error Code.
- *
+/*!
+ * \brief SHA1Result
+ * \param context [in/out] The context to use to calculate the SHA-1 hash.
+ * \param Message_Digest [out] Where the digest is returned.
+ *  This function will return the 160-bit message digest into the
+ *  Message_Digest array  provided by the caller.
+ * \note The first octet of hash is stored in the 0th element, 
+ * 	the last octet of hash in the 19th element.
+ * \return sha Error Code.
  */
 int SHA1Result( SHA1Context *context,
 		         uint8_t Message_Digest[SHA1HashSize])
@@ -160,25 +141,15 @@ int SHA1Result( SHA1Context *context,
 	return shaSuccess;
 }
 
-/*
- *  SHA1Input
- *
- *  Description:
- *	  This function accepts an array of octets as the next portion
- *	  of the message.
- *
- *  Parameters:
- *	  context: [in/out]
- *		   The SHA context to update
- *	  message_array: [in]
- *		   An array of characters representing the next portion of
+/*!
+ *  \brief SHA1Input
+ * \param context [in/out] The SHA context to update
+ * \param message_array [in] An array of characters representing the next portion of
  *		   the message.
- *	  length: [in]
- *		   The length of the message in message_array
- *
- *  Returns:
- *	  sha Error Code.
- *
+ * \param length [in] The length of the message in message_array
+ *  This function accepts an array of octets as the next portion
+ *  of the message.
+ * \return sha Error Code.
  */
 int SHA1Input(SHA1Context *context, const uint8_t *message_array, unsigned length)
 {
@@ -221,25 +192,13 @@ int SHA1Input(SHA1Context *context, const uint8_t *message_array, unsigned lengt
 	return shaSuccess;
 }
 
-/*
- *  SHA1ProcessMessageBlock
- *
- *  Description:
- *	  This function will process the next 512 bits of the message
- *	  stored in the Message_Block array.
- *
- *  Parameters:
- *	  None.
- *
- *  Returns:
- *	  Nothing.
- *
- *  Comments:
- *	  Many of the variable names in this code, especially the
+/*!
+ * \brief Process the next 512 bits of the message stored in the Message_Block array.
+ * \param context [in/out] The SHA context to update
+ * \note  Many of the variable names in this code, especially the
  *	  single character names, were used because those were the
  *	  names used in the publication.
- *
- *
+ * \returns nothing.
  */
 void SHA1ProcessMessageBlock(SHA1Context *context)
 {
@@ -320,27 +279,20 @@ void SHA1ProcessMessageBlock(SHA1Context *context)
 }
 
 
-/*
- *  SHA1PadMessage
- *
- *  Description:
- *	  According to the standard, the message must be padded to an even
- *	  512 bits.  The first padding bit must be a '1'.  The last 64
- *	  bits represent the length of the original message.  All bits in
- *	  between should be 0.  This function will pad the message
- *	  according to those rules by filling the Message_Block array
- *	  accordingly.  It will also call the ProcessMessageBlock function
- *	  provided appropriately.  When it returns, it can be assumed that
- *	  the message digest has been computed.
- *
- *  Parameters:
- *	  context: [in/out]
- *		   The context to pad
- *	  ProcessMessageBlock: [in]
- *		   The appropriate SHA*ProcessMessageBlock function
- *  Returns:
- *	  Nothing.
+/*!
+ * \brief Pad message to be 512 bits.
+ * \param context [in/out]  The context to pad
+ * 
+ * According to the standard, the message must be padded to an even
+ *  512 bits.  The first padding bit must be a '1'.  The last 64
+ *  bits represent the length of the original message.  All bits in
+ *  between should be 0.  This function will pad the message
+ *  according to those rules by filling the Message_Block array
+ *  accordingly.  It will also call the ProcessMessageBlock function
+ *  provided appropriately.  When it returns, it can be assumed that
+ *  the message digest has been computed.
  *
+ * \returns nothing.
  */
 
 void SHA1PadMessage(SHA1Context *context)