More merges from 1.10 comments and inits

1 files changed, 211 insertions, 239 deletions

diff --git a/src/H5D.c b/src/H5D.c
index 6265e5d..e3e9095 100644
--- a/src/H5D.c
+++ b/src/H5D.c
@@ -23,11 +23,11 @@
 /***********/
 /* Headers */
 /***********/
-#include "H5private.h"   /* Generic Functions			*/
-#include "H5Dpkg.h"      /* Datasets 				*/
-#include "H5Eprivate.h"  /* Error handling		  	*/
-#include "H5FLprivate.h" /* Free lists                           */
-#include "H5Iprivate.h"  /* IDs			  		*/
+#include "H5private.h"   /* Generic Functions                        */
+#include "H5Dpkg.h"      /* Datasets                                 */
+#include "H5Eprivate.h"  /* Error handling                           */
+#include "H5FLprivate.h" /* Free lists                               */
+#include "H5Iprivate.h"  /* IDs                                      */
 
 /****************/
 /* Local Macros */
@@ -106,31 +106,28 @@ H5D__term_pub_interface(void)
 } /* H5D__term_pub_interface() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dcreate2
+ * Function:    H5Dcreate2
  *
- * Purpose:	Creates a new dataset named NAME at LOC_ID, opens the
- *		dataset for access, and associates with that dataset constant
- *		and initial persistent properties including the type of each
- *		datapoint as stored in the file (TYPE_ID), the size of the
- *		dataset (SPACE_ID), and other initial miscellaneous
- *		properties (DCPL_ID).
+ * Purpose:     Creates a new dataset named NAME at LOC_ID, opens the
+ *              dataset for access, and associates with that dataset constant
+ *              and initial persistent properties including the type of each
+ *              datapoint as stored in the file (TYPE_ID), the size of the
+ *              dataset (SPACE_ID), and other initial miscellaneous
+ *              properties (DCPL_ID).
  *
- *		All arguments are copied into the dataset, so the caller is
- *		allowed to derive new types, dataspaces, and creation
- *		parameters from the old ones and reuse them in calls to
- *		create other datasets.
+ *              All arguments are copied into the dataset, so the caller is
+ *              allowed to derive new types, dataspaces, and creation
+ *              parameters from the old ones and reuse them in calls to
+ *              create other datasets.
  *
- * Return:	Success:	The object ID of the new dataset.  At this
- *				point, the dataset is ready to receive its
- *				raw data.  Attempting to read raw data from
- *				the dataset will probably return the fill
- *				value.	The dataset should be closed when the
- *				caller is no longer interested in it.
+ * Return:      Success:    The object ID of the new dataset. At this
+ *                          point, the dataset is ready to receive its
+ *                          raw data. Attempting to read raw data from
+ *                          the dataset will probably return the fill
+ *                          value. The dataset should be closed when the
+ *                          caller is no longer interested in it.
  *
- *		Failure:	FAIL
- *
- * Programmer:	Quincey Koziol
- *		Thursday, April 5, 2007
+ *              Failure:    H5I_INVALID_HID
  *
  *-------------------------------------------------------------------------
  */
@@ -138,126 +135,126 @@ hid_t
 H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id,
            hid_t dapl_id)
 {
-    H5G_loc_t    loc;         /* Object location to insert dataset into */
-    H5D_t *      dset = NULL; /* New dataset's info */
-    const H5S_t *space;       /* Dataspace for dataset */
-    hid_t        ret_value;   /* Return value */
+    H5G_loc_t    loc;                         /* Object location to insert dataset into */
+    H5D_t *      dset = NULL;                 /* New dataset's info */
+    const H5S_t *space;                       /* Dataspace for dataset */
+    hid_t        ret_value = H5I_INVALID_HID; /* Return value */
 
-    FUNC_ENTER_API(FAIL)
+    FUNC_ENTER_API(H5I_INVALID_HID)
     H5TRACE7("i", "i*siiiii", loc_id, name, type_id, space_id, lcpl_id, dcpl_id, dapl_id);
 
     /* Check arguments */
     if (H5G_loc(loc_id, &loc) < 0)
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location ID")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a location ID")
     if (H5I_DATATYPE != H5I_get_type(type_id))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a datatype ID")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a datatype ID")
     if (NULL == (space = (const H5S_t *)H5I_object_verify(space_id, H5I_DATASPACE)))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataspace ID")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a dataspace ID")
 
-    /* Get correct property list */
+    /* Get link creation property list */
     if (H5P_DEFAULT == lcpl_id)
         lcpl_id = H5P_LINK_CREATE_DEFAULT;
     else if (TRUE != H5P_isa_class(lcpl_id, H5P_LINK_CREATE))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not link creation property list")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "lcpl_id is not a link creation property list")
 
-    /* Get correct property list */
+    /* Get dataset creation property list */
     if (H5P_DEFAULT == dcpl_id)
         dcpl_id = H5P_DATASET_CREATE_DEFAULT;
     else if (TRUE != H5P_isa_class(dcpl_id, H5P_DATASET_CREATE))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not dataset create property list ID")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID,
+                    "dcpl_id is not a dataset create property list ID")
 
     /* Get correct property list */
     if (H5P_DEFAULT == dapl_id)
         dapl_id = H5P_DATASET_ACCESS_DEFAULT;
     else if (TRUE != H5P_isa_class(dapl_id, H5P_DATASET_ACCESS))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not dataset access property list")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not dataset access property list")
 
     /* Create the new dataset & get its ID */
     if (NULL ==
         (dset = H5D__create_named(&loc, name, type_id, space, lcpl_id, dcpl_id, dapl_id, H5AC_dxpl_id)))
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "unable to create dataset")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to create dataset")
+
+    /* Get an ID for the dataset */
     if ((ret_value = H5I_register(H5I_DATASET, dset, TRUE)) < 0)
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, FAIL, "unable to register dataset")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register dataset")
 
 done:
-    if (ret_value < 0)
+    if (H5I_INVALID_HID == ret_value)
         if (dset && H5D_close(dset) < 0)
-            HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, FAIL, "unable to release dataset")
+            HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, H5I_INVALID_HID, "unable to release dataset")
 
     FUNC_LEAVE_API(ret_value)
 } /* end H5Dcreate2() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dcreate_anon
+ * Function:    H5Dcreate_anon
  *
- * Purpose:	Creates a new dataset named NAME at LOC_ID, opens the
- *		dataset for access, and associates with that dataset constant
- *		and initial persistent properties including the type of each
- *		datapoint as stored in the file (TYPE_ID), the size of the
- *		dataset (SPACE_ID), and other initial miscellaneous
- *		properties (DCPL_ID).
+ * Purpose:     Creates a new dataset named NAME at LOC_ID, opens the
+ *              dataset for access, and associates with that dataset constant
+ *              and initial persistent properties including the type of each
+ *              datapoint as stored in the file (TYPE_ID), the size of the
+ *              dataset (SPACE_ID), and other initial miscellaneous
+ *              properties (DCPL_ID).
  *
- *		All arguments are copied into the dataset, so the caller is
- *		allowed to derive new types, dataspaces, and creation
- *		parameters from the old ones and reuse them in calls to
- *		create other datasets.
+ *              All arguments are copied into the dataset, so the caller is
+ *              allowed to derive new types, dataspaces, and creation
+ *              parameters from the old ones and reuse them in calls to
+ *              create other datasets.
  *
  *              The resulting ID should be linked into the file with
  *              H5Olink or it will be deleted when closed.
  *
- * Return:	Success:	The object ID of the new dataset.  At this
- *				point, the dataset is ready to receive its
- *				raw data.  Attempting to read raw data from
- *				the dataset will probably return the fill
- *				value.	The dataset should be linked into
- *                              the group hierarchy before being closed or
- *                              it will be deleted.  The dataset should be
- *                              closed when the caller is no longer interested
- *                              in it.
- *
- *		Failure:	FAIL
+ * Return:      Success:    The object ID of the new dataset. At this
+ *                          point, the dataset is ready to receive its
+ *                          raw data. Attempting to read raw data from
+ *                          the dataset will probably return the fill
+ *                          value. The dataset should be linked into
+ *                          the group hierarchy before being closed or
+ *                          it will be deleted. The dataset should be
+ *                          closed when the caller is no longer interested
+ *                          in it.
  *
- * Programmer:	James Laird
- *		Tuesday, January 24, 2006
+ *              Failure:    H5I_INVALID_HID
  *
  *-------------------------------------------------------------------------
  */
 hid_t
 H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id)
 {
-    H5G_loc_t    loc;         /* Object location to insert dataset into */
-    H5D_t *      dset = NULL; /* New dataset's info */
-    const H5S_t *space;       /* Dataspace for dataset */
-    hid_t        ret_value;   /* Return value */
+    H5G_loc_t    loc;                         /* Object location to insert dataset into */
+    H5D_t *      dset = NULL;                 /* New dataset's info */
+    const H5S_t *space;                       /* Dataspace for dataset */
+    hid_t        ret_value = H5I_INVALID_HID; /* Return value */
 
-    FUNC_ENTER_API(FAIL)
+    FUNC_ENTER_API(H5I_INVALID_HID)
     H5TRACE5("i", "iiiii", loc_id, type_id, space_id, dcpl_id, dapl_id);
 
     /* Check arguments */
     if (H5G_loc(loc_id, &loc) < 0)
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location ID")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a location ID")
     if (H5I_DATATYPE != H5I_get_type(type_id))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a datatype ID")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a datatype ID")
     if (NULL == (space = (const H5S_t *)H5I_object_verify(space_id, H5I_DATASPACE)))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataspace ID")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a dataspace ID")
     if (H5P_DEFAULT == dcpl_id)
         dcpl_id = H5P_DATASET_CREATE_DEFAULT;
     else if (TRUE != H5P_isa_class(dcpl_id, H5P_DATASET_CREATE))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not dataset create property list ID")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not dataset create property list ID")
 
     /* Get correct property list */
     if (H5P_DEFAULT == dapl_id)
         dapl_id = H5P_DATASET_ACCESS_DEFAULT;
     else if (TRUE != H5P_isa_class(dapl_id, H5P_DATASET_ACCESS))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not dataset access property list")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not dataset access property list")
 
     /* build and open the new dataset */
     if (NULL == (dset = H5D__create(loc.oloc->file, type_id, space, dcpl_id, dapl_id, H5AC_dxpl_id)))
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "unable to create dataset")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to create dataset")
 
     /* Register the new dataset to get an ID for it */
     if ((ret_value = H5I_register(H5I_DATASET, dset, TRUE)) < 0)
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, FAIL, "unable to register dataset")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register dataset")
 
 done:
     /* Release the dataset's object header, if it was created */
@@ -266,36 +263,34 @@ done:
 
         /* Get the new dataset's object location */
         if (NULL == (oloc = H5D_oloc(dset)))
-            HDONE_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "unable to get object location of dataset")
+            HDONE_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "unable to get object location of dataset")
 
         /* Decrement refcount on dataset's object header in memory */
         if (H5O_dec_rc_by_loc(oloc, H5AC_dxpl_id) < 0)
-            HDONE_ERROR(H5E_DATASET, H5E_CANTDEC, FAIL,
+            HDONE_ERROR(H5E_DATASET, H5E_CANTDEC, H5I_INVALID_HID,
                         "unable to decrement refcount on newly created object")
-    } /* end if */
+    }
 
     /* Cleanup on failure */
-    if (ret_value < 0)
+    if (H5I_INVALID_HID == ret_value)
         if (dset && H5D_close(dset) < 0)
-            HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, FAIL, "unable to release dataset")
+            HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, H5I_INVALID_HID, "unable to release dataset")
 
     FUNC_LEAVE_API(ret_value)
 } /* end H5Dcreate_anon() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dopen2
+ * Function:    H5Dopen2
  *
- * Purpose:	Finds a dataset named NAME at LOC_ID, opens it, and returns
- *		its ID.	 The dataset should be close when the caller is no
- *		longer interested in it.
+ * Purpose:     Finds a dataset named NAME at LOC_ID, opens it, and returns
+ *              its ID. The dataset should be close when the caller is no
+ *              longer interested in it.
  *
  *              Takes a dataset access property list
  *
- * Return:	Success:	A new dataset ID
- *		Failure:	FAIL
+ * Return:      Success:    Object ID of the dataset
  *
- * Programmer:	James Laird
- *		Thursday, July 27, 2006
+ *              Failure:    H5I_INVALID_HID
  *
  *-------------------------------------------------------------------------
  */
@@ -310,22 +305,22 @@ H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id)
     H5O_type_t obj_type;                     /* Type of object at location */
     hbool_t    loc_found = FALSE;            /* Location at 'name' found */
     hid_t      dxpl_id   = H5AC_ind_dxpl_id; /* dxpl to use to open datset */
-    hid_t      ret_value;
+    hid_t      ret_value = H5I_INVALID_HID;  /* Return value */
 
-    FUNC_ENTER_API(FAIL)
+    FUNC_ENTER_API(H5I_INVALID_HID)
     H5TRACE3("i", "i*si", loc_id, name, dapl_id);
 
     /* Check args */
     if (H5G_loc(loc_id, &loc) < 0)
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a location")
     if (!name || !*name)
-        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, H5I_INVALID_HID, "no name")
 
     /* Get correct property list */
     if (H5P_DEFAULT == dapl_id)
         dapl_id = H5P_DATASET_ACCESS_DEFAULT;
     else if (TRUE != H5P_isa_class(dapl_id, H5P_DATASET_ACCESS))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not dataset access property list")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not dataset access property list")
 
     /* Set up dataset location to fill in */
     dset_loc.oloc = &oloc;
@@ -334,49 +329,46 @@ H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id)
 
     /* Find the dataset object */
     if (H5G_loc_find(&loc, name, &dset_loc, dapl_id, dxpl_id) < 0)
-        HGOTO_ERROR(H5E_DATASET, H5E_NOTFOUND, FAIL, "not found")
+        HGOTO_ERROR(H5E_DATASET, H5E_NOTFOUND, H5I_INVALID_HID, "not found")
     loc_found = TRUE;
 
     /* Check that the object found is the correct type */
     if (H5O_obj_type(&oloc, &obj_type, dxpl_id) < 0)
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "can't get object type")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "can't get object type")
     if (obj_type != H5O_TYPE_DATASET)
-        HGOTO_ERROR(H5E_DATASET, H5E_BADTYPE, FAIL, "not a dataset")
+        HGOTO_ERROR(H5E_DATASET, H5E_BADTYPE, H5I_INVALID_HID, "not a dataset")
 
     /* Open the dataset */
     if (NULL == (dset = H5D_open(&dset_loc, dapl_id, dxpl_id)))
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "can't open dataset")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "can't open dataset")
 
     /* Register an atom for the dataset */
     if ((ret_value = H5I_register(H5I_DATASET, dset, TRUE)) < 0)
-        HGOTO_ERROR(H5E_ATOM, H5E_CANTREGISTER, FAIL, "can't register dataset atom")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "can't register dataset atom")
 
 done:
-    if (ret_value < 0) {
+    if (H5I_INVALID_HID == ret_value) {
         if (dset) {
             if (H5D_close(dset) < 0)
-                HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, FAIL, "unable to release dataset")
+                HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, H5I_INVALID_HID, "unable to release dataset")
         } /* end if */
         else {
             if (loc_found && H5G_loc_free(&dset_loc) < 0)
-                HDONE_ERROR(H5E_DATASET, H5E_CANTRELEASE, FAIL, "can't free location")
+                HDONE_ERROR(H5E_DATASET, H5E_CANTRELEASE, H5I_INVALID_HID, "can't free location")
         } /* end else */
-    }     /* end if */
+    }
 
     FUNC_LEAVE_API(ret_value)
 } /* end H5Dopen2() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dclose
+ * Function:    H5Dclose
  *
- * Purpose:	Closes access to a dataset (DATASET_ID) and releases
- *		resources used by it. It is illegal to subsequently use that
- *		same dataset ID in calls to other dataset functions.
+ * Purpose:     Closes access to a dataset and releases resources used by
+ *              it. It is illegal to subsequently use that same dataset
+ *              ID in calls to other dataset functions.
  *
- * Return:	Non-negative on success/Negative on failure
- *
- * Programmer:	Robb Matzke
- *		Thursday, December  4, 1997
+ * Return:      Non-negative on success/Negative on failure
  *
  *-------------------------------------------------------------------------
  */
@@ -392,8 +384,7 @@ H5Dclose(hid_t dset_id)
     if (NULL == H5I_object_verify(dset_id, H5I_DATASET))
         HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
 
-    /*
-     * Decrement the counter on the dataset.  It will be freed if the count
+    /* Decrement the counter on the dataset.  It will be freed if the count
      * reaches zero.
      *
      * Pass in TRUE for the 3rd parameter to tell the function to remove
@@ -408,52 +399,44 @@ done:
 } /* end H5Dclose() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dget_space
- *
- * Purpose:	Returns a copy of the file dataspace for a dataset.
+ * Function:    H5Dget_space
  *
- * Return:	Success:	ID for a copy of the dataspace.  The data
- *				space should be released by calling
- *				H5Sclose().
+ * Purpose:     Returns a copy of the file dataspace for a dataset.
  *
- *		Failure:	FAIL
+ * Return:      Success:    ID for a copy of the dataspace.  The data
+ *                          space should be released by calling
+ *                          H5Sclose().
  *
- * Programmer:	Robb Matzke
- *		Wednesday, January 28, 1998
+ *              Failure:    H5I_INVALID_HID
  *
  *-------------------------------------------------------------------------
  */
 hid_t
 H5Dget_space(hid_t dset_id)
 {
-    H5D_t *dset = NULL;
-    hid_t  ret_value;
+    H5D_t *dset      = NULL;
+    hid_t  ret_value = H5I_INVALID_HID; /* Return value         */
 
-    FUNC_ENTER_API(FAIL)
+    FUNC_ENTER_API(H5I_INVALID_HID)
     H5TRACE1("i", "i", dset_id);
 
     /* Check args */
     if (NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid dataset identifier")
 
     if ((ret_value = H5D_get_space(dset)) < 0)
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "unable to get dataspace")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to get dataspace")
 
 done:
     FUNC_LEAVE_API(ret_value)
-}
+} /* end H5Dget_space() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dget_space_status
- *
- * Purpose:	Returns the status of dataspace allocation.
+ * Function:    H5Dget_space_status
  *
- * Return:
- *		Success:	Non-negative
+ * Purpose:     Returns the status of dataspace allocation.
  *
- *		Failture:	Negative
- *
- * Programmer:	Raymond Lu
+ * Return:      Non-negative on success/Negative on failure
  *
  *-------------------------------------------------------------------------
  */
@@ -461,14 +444,14 @@ herr_t
 H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation)
 {
     H5D_t *dset      = NULL;
-    herr_t ret_value = SUCCEED;
+    herr_t ret_value = SUCCEED; /* Return value         */
 
     FUNC_ENTER_API(FAIL)
     H5TRACE2("e", "i*Ds", dset_id, allocation);
 
-    /* Check arguments */
+    /* Check args */
     if (NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid dataset identifier")
 
     /* Read dataspace address and return */
     if (H5D__get_space_status(dset, allocation, H5AC_ind_dxpl_id) < 0)
@@ -476,166 +459,161 @@ H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation)
 
 done:
     FUNC_LEAVE_API(ret_value)
-}
+} /* H5Dget_space_status() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dget_type
+ * Function:    H5Dget_type
  *
- * Purpose:	Returns a copy of the file datatype for a dataset.
+ * Purpose:     Returns a copy of the file datatype for a dataset.
  *
- * Return:	Success:	ID for a copy of the datatype.	 The data
- *				type should be released by calling
- *				H5Tclose().
+ * Return:      Success:    ID for a copy of the datatype. The data
+ *                          type should be released by calling
+ *                          H5Tclose().
  *
- *		Failure:	FAIL
- *
- * Programmer:	Robb Matzke
- *		Tuesday, February  3, 1998
+ *              Failure:    H5I_INVALID_HID
  *
  *-------------------------------------------------------------------------
  */
 hid_t
 H5Dget_type(hid_t dset_id)
 {
+    H5D_t *dset;                        /* Dataset */
+    hid_t  ret_value = H5I_INVALID_HID; /* Return value         */
 
-    H5D_t *dset;      /* Dataset */
-    hid_t  ret_value; /* Return value */
-
-    FUNC_ENTER_API(FAIL)
+    FUNC_ENTER_API(H5I_INVALID_HID)
     H5TRACE1("i", "i", dset_id);
 
     /* Check args */
     if (NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid dataset identifier")
 
     if ((ret_value = H5D_get_type(dset)) < 0)
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "unable to get dataspace")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to get dataspace")
 
 done:
     FUNC_LEAVE_API(ret_value)
 } /* end H5Dget_type() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dget_create_plist
+ * Function:    H5Dget_create_plist
  *
- * Purpose:	Returns a copy of the dataset creation property list.
+ * Purpose:     Returns a copy of the dataset creation property list.
  *
- * Return:	Success:	ID for a copy of the dataset creation
- *				property list.  The template should be
- *				released by calling H5P_close().
+ * Return:      Success:    ID for a copy of the dataset creation
+ *                          property list.  The template should be
+ *                          released by calling H5P_close().
  *
- *		Failure:	FAIL
+ *              Failure:    H5I_INVALID_HID
  *
- * Programmer:	Robb Matzke
- *		Tuesday, February  3, 1998
+ * Programmer:  Robb Matzke
+ *              Tuesday, February  3, 1998
  *
  *-------------------------------------------------------------------------
  */
 hid_t
 H5Dget_create_plist(hid_t dset_id)
 {
-    H5D_t *dataset;             /* Dataset structure */
-    hid_t  ret_value = SUCCEED; /* Return value */
+    H5D_t *dataset;                     /* Dataset structure */
+    hid_t  ret_value = H5I_INVALID_HID; /* Return value         */
 
-    FUNC_ENTER_API(FAIL)
+    FUNC_ENTER_API(H5I_INVALID_HID)
     H5TRACE1("i", "i", dset_id);
 
     /* Check args */
     if (NULL == (dataset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid dataset identifier")
 
+    /* Get the dataset creation property list */
     if ((ret_value = H5D_get_create_plist(dataset)) < 0)
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "Can't get creation plist")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "unable to get dataset creation properties")
 
 done:
     FUNC_LEAVE_API(ret_value)
 } /* end H5Dget_create_plist() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dget_access_plist
+ * Function:    H5Dget_access_plist
  *
- * Purpose:	Returns a copy of the dataset creation property list.
+ * Purpose:     Returns a copy of the dataset access property list.
  *
  * Description: H5Dget_access_plist returns the dataset access property
- *      list identifier of the specified dataset.
+ *              list identifier of the specified dataset.
  *
- *      The chunk cache parameters in the returned property lists will be
- *      those used by the dataset.  If the properties in the file access
- *      property list were used to determine the dataset’s chunk cache
- *      configuration, then those properties will be present in the
- *      returned dataset access property list.  If the dataset does not
- *      use a chunked layout, then the chunk cache properties will be set
- *      to the default.  The chunk cache properties in the returned list
- *      are considered to be “set”, and any use of this list will override
- *      the corresponding properties in the file’s file access property
- *      list.
+ *              The chunk cache parameters in the returned property lists will be
+ *              those used by the dataset.  If the properties in the file access
+ *              property list were used to determine the dataset’s chunk cache
+ *              configuration, then those properties will be present in the
+ *              returned dataset access property list.  If the dataset does not
+ *              use a chunked layout, then the chunk cache properties will be set
+ *              to the default.  The chunk cache properties in the returned list
+ *              are considered to be “set”, and any use of this list will override
+ *              the corresponding properties in the file’s file access property
+ *              list.
  *
- *      All link access properties in the returned list will be set to the
- *      default values.
+ *              All link access properties in the returned list will be set to the
+ *              default values.
  *
- * Return:	Success:	ID for a copy of the dataset access
- *				property list.  The template should be
- *				released by calling H5Pclose().
+ * Return:      Success:    ID for a copy of the dataset access
+ *                          property list.  The template should be
+ *                          released by calling H5Pclose().
  *
- *		Failure:	FAIL
+ *              Failure:    H5I_INVALID_HID
  *
- * Programmer:	Neil Fortner
- *		Wednesday, October 29, 2008
+ * Programmer:  Neil Fortner
+ *              Wednesday, October 29, 2008
  *
  *-------------------------------------------------------------------------
  */
 hid_t
 H5Dget_access_plist(hid_t dset_id)
 {
-    H5D_t *dset;      /* Dataset structure */
-    hid_t  ret_value; /* Return value */
+    H5D_t *dset;                        /* Dataset structure */
+    hid_t  ret_value = H5I_INVALID_HID; /* Return value         */
 
-    FUNC_ENTER_API(FAIL)
+    FUNC_ENTER_API(H5I_INVALID_HID)
     H5TRACE1("i", "i", dset_id);
 
     /* Check args */
     if (NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid dataset identifier")
 
+    /* Get the dataset access property list */
     if ((ret_value = H5D_get_access_plist(dset)) < 0)
-        HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "Can't get access plist")
+        HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "unable to get dataset access properties")
 
 done:
     FUNC_LEAVE_API(ret_value)
 } /* end H5Dget_access_plist() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dget_storage_size
+ * Function:    H5Dget_storage_size
  *
- * Purpose:	Returns the amount of storage that is required for the
- *		dataset. For chunked datasets this is the number of allocated
- *		chunks times the chunk size.
+ * Purpose:     Returns the amount of storage that is required for the
+ *              dataset. For chunked datasets this is the number of allocated
+ *              chunks times the chunk size.
  *
- * Return:	Success:	The amount of storage space allocated for the
- *				dataset, not counting meta data. The return
- *				value may be zero if no data has been stored.
+ * Return:      Success:    The amount of storage space allocated for the
+ *                          dataset, not counting meta data. The return
+ *                          value may be zero if no data has been stored.
  *
- *		Failure:	Zero
- *
- * Programmer:	Robb Matzke
- *              Wednesday, April 21, 1999
+ *              Failure:    Zero
  *
  *-------------------------------------------------------------------------
  */
 hsize_t
 H5Dget_storage_size(hid_t dset_id)
 {
-    H5D_t * dset;      /* Dataset to query */
-    hsize_t ret_value; /* Return value */
+    H5D_t * dset;          /* Dataset to query */
+    hsize_t ret_value = 0; /* Return value                 */
 
     FUNC_ENTER_API(0)
     H5TRACE1("h", "i", dset_id);
 
     /* Check args */
     if (NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, 0, "not a dataset")
+        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, 0, "invalid dataset identifier")
 
-    /* Set return value */
+    /* Get the storage size */
     if (H5D__get_storage_size(dset, H5AC_ind_dxpl_id, &ret_value) < 0)
         HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, 0, "can't get size of dataset's storage")
 
@@ -644,24 +622,21 @@ done:
 } /* end H5Dget_storage_size() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dget_offset
- *
- * Purpose:	Returns the address of dataset in file.
+ * Function:    H5Dget_offset
  *
- * Return:	Success:        the address of dataset
+ * Purpose:     Returns the address of dataset in file.
  *
- *		Failure:	HADDR_UNDEF
+ * Return:      Success:    The address of dataset
  *
- * Programmer:  Raymond Lu
- *              November 6, 2002
+ *              Failure:    HADDR_UNDEF (can also be a valid return value!)
  *
  *-------------------------------------------------------------------------
  */
 haddr_t
 H5Dget_offset(hid_t dset_id)
 {
-    H5D_t * dset;      /* Dataset to query */
-    haddr_t ret_value; /* Return value */
+    H5D_t * dset;                    /* Dataset to query */
+    haddr_t ret_value = HADDR_UNDEF; /* Return value                 */
 
     FUNC_ENTER_API(HADDR_UNDEF)
     H5TRACE1("a", "i", dset_id);
@@ -670,7 +645,7 @@ H5Dget_offset(hid_t dset_id)
     if (NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
         HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, HADDR_UNDEF, "not a dataset")
 
-    /* Set return value */
+    /* Get the offset */
     ret_value = H5D__get_offset(dset);
 
 done:
@@ -678,9 +653,9 @@ done:
 } /* end H5Dget_offset() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Diterate
+ * Function:    H5Diterate
  *
- * Purpose:	This routine iterates over all the elements selected in a memory
+ * Purpose: This routine iterates over all the elements selected in a memory
  *      buffer.  The callback function is called once for each element selected
  *      in the dataspace.  The selection in the dataspace is modified so
  *      that any elements already iterated over are removed from the selection
@@ -727,11 +702,11 @@ done:
  *              indicating failure. The iterator can be restarted at the next
  *              element.
  *
- * Return:	Returns the return value of the last operator if it was non-zero,
+ * Return:  Returns the return value of the last operator if it was non-zero,
  *          or zero if all elements were processed. Otherwise returns a
  *          negative value.
  *
- * Programmer:	Quincey Koziol
+ * Programmer:  Quincey Koziol
  *              Friday, June 11, 1999
  *
  *-------------------------------------------------------------------------
@@ -817,9 +792,9 @@ done:
 } /* end H5Dvlen_reclaim() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dvlen_get_buf_size
+ * Function:    H5Dvlen_get_buf_size
  *
- * Purpose:	This routine checks the number of bytes required to store the VL
+ * Purpose: This routine checks the number of bytes required to store the VL
  *      data from the dataset, using the space_id for the selection in the
  *      dataset on disk and the type_id for the memory representation of the
  *      VL data, in memory.  The *size value is modified according to how many
@@ -833,9 +808,9 @@ done:
  *      Kinda kludgy, but easier than the other method of trying to figure out
  *      the sizes without actually reading the data in... - QAK
  *
- * Return:	Non-negative on success, negative on failure
+ * Return:  Non-negative on success, negative on failure
  *
- * Programmer:	Quincey Koziol
+ * Programmer:  Quincey Koziol
  *              Wednesday, August 11, 1999
  *
  *-------------------------------------------------------------------------
@@ -930,16 +905,13 @@ done:
 } /* end H5Dvlen_get_buf_size() */
 
 /*-------------------------------------------------------------------------
- * Function:	H5Dset_extent
+ * Function:    H5Dset_extent
  *
- * Purpose:	Modifies the dimensions of a dataset.
- *		Can change to a smaller dimension.
+ * Purpose:     Modifies the dimensions of a dataset.
+ *              Can change to a smaller dimension.
  *
  * Return:	Non-negative on success, negative on failure
  *
- * Programmer:  Pedro Vicente, pvn@ncsa.uiuc.edu
- *              April 9, 2002
- *
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -968,7 +940,7 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Dget_chunk_storage_size
  *
- * Purpose:     Returns the size of an allocated of chunk.
+ * Purpose:     Returns the size of an allocated chunk.
  *
  * Return:	Non-negative on success, negative on failure
  *
@@ -981,7 +953,7 @@ herr_t
 H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hsize_t *chunk_nbytes)
 {
     H5D_t *dset      = NULL;
-    herr_t ret_value = SUCCEED;
+    herr_t ret_value = SUCCEED; /* Return value                 */
 
     FUNC_ENTER_API(FAIL)
     H5TRACE3("e", "i*h*h", dset_id, offset, chunk_nbytes);
@@ -997,7 +969,7 @@ H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hsize_t *chunk_n
     if (H5D_CHUNKED != dset->shared->layout.type)
         HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a chunked dataset")
 
-    /* Call private function */
+    /* Get the dataset creation property list */
     if (H5D__get_chunk_storage_size(dset, H5AC_ind_dxpl_id, offset, chunk_nbytes) < 0)
         HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "can't get storage size of chunk")