[svn-r6578] Purpose:

    Code cleanup

Description:
    Added lots of comments to existing filters, so they are easier to understand
and use as examples for future filters.  Cleaned up various bits of code, etc.

Solution:

Platforms tested:
    FreeBSD 4.8 (sleipnir)
    IRIX64 6.5 (modi4) w/parallel

Misc. update:

1 files changed, 33 insertions, 31 deletions

diff --git a/src/H5Zfletcher32.c b/src/H5Zfletcher32.c
index b3d82df..62fbfa5 100644
--- a/src/H5Zfletcher32.c
+++ b/src/H5Zfletcher32.c
@@ -16,10 +16,11 @@
  * Programmer:  Raymond Lu<slu@ncsa.uiuc.edu>
  *              Jan 3, 2003
  */
-#include "H5private.h"
-#include "H5Eprivate.h"
-#include "H5MMprivate.h"
-#include "H5Zprivate.h"
+
+#include "H5private.h"		/* Generic Functions			*/
+#include "H5Eprivate.h"		/* Error handling		  	*/
+#include "H5MMprivate.h"	/* Memory management			*/
+#include "H5Zprivate.h"		/* Data filters				*/
 
 #ifdef H5_HAVE_FILTER_FLETCHER32
 
@@ -47,12 +48,10 @@ static int interface_initialize_g = 0;
  *
  *-------------------------------------------------------------------------
  */
-static unsigned int H5Z_filter_fletcher32_compute(unsigned short *buf, size_t len)
+static uint32_t H5Z_filter_fletcher32_compute(unsigned short *src, size_t len)
 {
-    size_t         count = len;
-    register unsigned int s1 = 0;
-    register unsigned int s2 = 0;
-    unsigned short *src = buf;
+    size_t count = len;         /* Number of bytes left to checksum */
+    uint32_t s1 = 0, s2 = 0;    /* Temporary partial checksums */
 
     FUNC_ENTER_NOINIT(H5Z_filter_fletcher32_compute);
 
@@ -93,8 +92,7 @@ static unsigned int H5Z_filter_fletcher32_compute(unsigned short *buf, size_t le
  *
  * Purpose:	Implement an I/O filter of Fletcher32 Checksum
  *
- * Return:	Success: size of data plus the size of Fletcher32 value	
- *
+ * Return:	Success: Size of buffer filtered
  *		Failure: 0	
  *
  * Programmer:	Raymond Lu
@@ -108,42 +106,43 @@ size_t
 H5Z_filter_fletcher32 (unsigned flags, size_t UNUSED cd_nelmts, const unsigned UNUSED cd_values[], 
                      size_t nbytes, size_t *buf_size, void **buf)
 {
-    size_t	ret_value = 0;
-    void	*outbuf = NULL;
-    
+    void    *outbuf = NULL;     /* Pointer to new buffer */
     unsigned char *src = (unsigned char*)(*buf);
-    unsigned int fletcher = 0;
+    uint32_t fletcher;          /* Checksum value */
+    size_t   ret_value;         /* Return value */
     
     FUNC_ENTER_NOAPI(H5Z_filter_fletcher32, 0);
 
-    assert(sizeof(unsigned int)==4);
+    assert(sizeof(uint32_t)==4);
    
     if (flags & H5Z_FLAG_REVERSE) { /* Read */
-        size_t  src_nbytes = nbytes;
-        unsigned int origin_fletcher;
-
         /* Do checksum if it's enabled for read; otherwise skip it
          * to save performance. */
-        if (!(flags & H5Z_FLAG_SKIP_EDC)) { /* Read */
-            unsigned char *tmp_src;
+        if (!(flags & H5Z_FLAG_SKIP_EDC)) {
+            unsigned char *tmp_src;             /* Pointer to checksum in buffer */
+            size_t  src_nbytes = nbytes;        /* Original number of bytes */
+            uint32_t stored_fletcher;           /* Stored checksum value */
 
+            /* Get the stored checksum */
             src_nbytes -= FLETCHER_LEN;
             tmp_src=src+src_nbytes;
-            UINT32DECODE(tmp_src, origin_fletcher);
+            UINT32DECODE(tmp_src, stored_fletcher);
 
-            /* Compute checksum */
+            /* Compute checksum (can't fail) */
             fletcher = H5Z_filter_fletcher32_compute((unsigned short*)src,src_nbytes);
 
-            if(origin_fletcher != fletcher)
+            /* Verify computed checksum matches stored checksum */
+            if(stored_fletcher != fletcher)
 	        HGOTO_ERROR(H5E_STORAGE, H5E_READERROR, 0, "data error detected by Fletcher32 checksum");
         }
         
-        *buf_size = nbytes - FLETCHER_LEN;
-        ret_value = *buf_size;
+        /* Set return values */
+        /* (Re-use the input buffer, just note that the size is smaller by the size of the checksum) */
+        ret_value = nbytes-FLETCHER_LEN;
     } else { /* Write */
-        unsigned char *dst;
+        unsigned char *dst;     /* Temporary pointer to destination buffer */
 
-        /* Compute checksum */
+        /* Compute checksum (can't fail) */
         fletcher = H5Z_filter_fletcher32_compute((unsigned short*)src,nbytes);
         
 	if (NULL==(dst=outbuf=H5MM_malloc(nbytes+FLETCHER_LEN)))
@@ -152,12 +151,15 @@ H5Z_filter_fletcher32 (unsigned flags, size_t UNUSED cd_nelmts, const unsigned U
         /* Copy raw data */
         HDmemcpy((void*)dst, (void*)(*buf), nbytes);
 
-        /* Append checksum to raw data */
+        /* Append checksum to raw data for storage */
         dst += nbytes;
         UINT32ENCODE(dst, fletcher);
 
-        *buf_size = nbytes + FLETCHER_LEN;
+        /* Free input buffer */
  	H5MM_xfree(*buf);
+
+        /* Set return values */
+        *buf_size = nbytes + FLETCHER_LEN;
 	*buf = outbuf;
 	outbuf = NULL;
 	ret_value = *buf_size;           
@@ -168,5 +170,5 @@ done:
         H5MM_xfree(outbuf);
     FUNC_LEAVE_NOAPI(ret_value);
 }
-
 #endif /* H5_HAVE_FILTER_FLETCHER32 */
+