Sync with develop

1 files changed, 67 insertions, 100 deletions

diff --git a/src/H5F.c b/src/H5F.c
index e80b1bd..9d426ac 100644
--- a/src/H5F.c
+++ b/src/H5F.c
@@ -280,7 +280,7 @@ H5Fget_create_plist(hid_t file_id)
 
     /* Retrieve the file creation property list */
     if(H5VL_file_get(vol_obj, H5VL_FILE_GET_FCPL, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL, &ret_value) < 0)
-        HGOTO_ERROR(H5E_PLIST, H5E_CANTCOPY, H5I_INVALID_HID, "unable to retrieve file creation properties")
+        HGOTO_ERROR(H5E_FILE, H5E_CANTCOPY, H5I_INVALID_HID, "unable to retrieve file creation properties")
 
 done:
     FUNC_LEAVE_API(ret_value)
@@ -320,7 +320,7 @@ H5Fget_access_plist(hid_t file_id)
 
     /* Retrieve the file's access property list */
     if(H5VL_file_get(vol_obj, H5VL_FILE_GET_FAPL, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL, &ret_value) < 0)
-        HGOTO_ERROR(H5E_PLIST, H5E_CANTGET, H5I_INVALID_HID, "can't get file access property list")
+        HGOTO_ERROR(H5E_FILE, H5E_CANTGET, H5I_INVALID_HID, "can't get file access property list")
 
 done:
     FUNC_LEAVE_API(ret_value)
@@ -549,8 +549,8 @@ done:
  * Purpose:     Returns a pointer to the file handle of the low-level file
  *              driver.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -584,8 +584,8 @@ done:
  *
  * Purpose:     Check if the file can be opened with the given fapl.
  *
- * Return:      Succeed:    TRUE/FALSE
- *              Failure:    FAIL (includes file does not exist)
+ * Return:      Success:    TRUE/FALSE
+ *              Failure:    -1 (includes file does not exist)
  *
  *-------------------------------------------------------------------------
  */
@@ -637,9 +637,7 @@ done:
  *              the list of file creation and file access properties.
  *
  * Return:      Success:    A file ID
- *
  *              Failure:    H5I_INVALID_HID
- *
  *-------------------------------------------------------------------------
  */
 hid_t
@@ -739,9 +737,7 @@ done:
  * See Also:    H5Fpublic.h for a list of possible values for FLAGS.
  *
  * Return:      Success:    A file ID
- *
  *              Failure:    H5I_INVALID_HID
- *
  *-------------------------------------------------------------------------
  */
 hid_t
@@ -798,7 +794,7 @@ H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)
 
     /* Get the file object */
     if(NULL == (vol_obj = H5VL_vol_object(ret_value)))
-        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid object identifier")
+        HGOTO_ERROR(H5E_FILE, H5E_CANTGET, H5I_INVALID_HID, "invalid object identifier")
 
     /* Make the 'post open' callback */
     supported = FALSE;
@@ -820,8 +816,8 @@ done:
  *              not remove them from the cache.  The OBJECT_ID can be a file,
  *              dataset, group, attribute, or named data type.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -863,8 +859,8 @@ done:
  *              closed until those objects are closed; however, all data for
  *              the file and the open objects is flushed.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -879,11 +875,9 @@ H5Fclose(hid_t file_id)
     if(H5I_FILE != H5I_get_type(file_id))
         HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file ID")
 
-    /* Decrement reference count on atom.  When it reaches zero the file will
-     * be closed.
-     */
+    /* Close the file */
     if(H5I_dec_app_ref(file_id) < 0)
-        HGOTO_ERROR(H5E_ATOM, H5E_CANTCLOSEFILE, FAIL, "decrementing file ID failed")
+        HGOTO_ERROR(H5E_FILE, H5E_CANTCLOSEFILE, FAIL, "closing file ID failed")
 
 done:
     FUNC_LEAVE_API(ret_value)
@@ -1011,8 +1005,8 @@ done:
  * Purpose:     Public API to retrieve the file's 'intent' flags passed
  *              during H5Fopen()
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1083,9 +1077,7 @@ done:
  * Purpose:     Retrieves the amount of free space in the file.
  *
  * Return:      Success:    Amount of free space for type
- *
  *              Failure:    -1
- *
  *-------------------------------------------------------------------------
  */
 hssize_t
@@ -1117,8 +1109,8 @@ done:
  *              is called after an existing file is opened in order
  *              to learn the true size of the underlying file.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:        Non-negative
+ *              Failure:        Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1179,9 +1171,7 @@ done:
  *              this now.
  *
  * Return:      Success:    Bytes copied / number of bytes needed
- *
  *              Failure:    -1
- *
  *-------------------------------------------------------------------------
  */
 ssize_t
@@ -1216,8 +1206,8 @@ done:
  *              filled in by the caller.  This allows us to adapt for
  *              obsolete versions of the structure.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1253,8 +1243,8 @@ done:
  *              configuration, using the contents of the instance of
  *              H5AC_cache_config_t pointed to by config_ptr.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1287,8 +1277,8 @@ done:
  *              the hit rate statistics were reset either manually or
  *              automatically.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1324,8 +1314,8 @@ done:
  *              the ptr parameters are NULL, the associated datum is
  *              not returned.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1364,8 +1354,8 @@ done:
  *              you are controlling cache size from your program instead
  *              of using our cache size control code.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1406,9 +1396,7 @@ done:
  *              not the actual name after resolving symlinks, etc.
  *
  * Return:      Success:    The length of the file name
- *
  *              Failure:    -1
- *
  *-------------------------------------------------------------------------
  */
 ssize_t
@@ -1448,8 +1436,8 @@ done:
  *                 in the SOHM table if there is one.
  *              3. The amount of free space tracked in the file.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1490,8 +1478,8 @@ done:
  * Purpose:     To retrieve the collection of read retries for metadata
  *              items with checksum.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1529,9 +1517,7 @@ done:
  *              sections.
  *
  * Return:      Success:   The total # of free space sections
- *
  *              Failure:   -1
- *
  *-------------------------------------------------------------------------
  */
 ssize_t
@@ -1566,8 +1552,8 @@ done:
  *              provided file, potentially closing any cached files
  *              unless they are held open from somewhere\ else.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1622,14 +1608,14 @@ done:
  *              set up flush dependency/proxy even for file opened without
  *              SWMR to resolve issues with opened objects.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
 H5Fstart_swmr_write(hid_t file_id)
 {
-    H5VL_object_t   *vol_obj = NULL;                   /* File info */
+    H5VL_object_t   *vol_obj = NULL;                /* File info */
     herr_t          ret_value = SUCCEED;            /* Return value */
 
     FUNC_ENTER_API(FAIL)
@@ -1658,8 +1644,8 @@ done:
  * Purpose:     Start metadata cache logging operations for a file.
  *                  - Logging must have been set up via the fapl.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1691,8 +1677,8 @@ done:
  *                  - Does not close the log file.
  *                  - Logging must have been set up via the fapl.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1724,8 +1710,8 @@ done:
  *              set up via the fapl. is_currently_logging determines if
  *              log messages are being recorded at this time.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1759,8 +1745,8 @@ done:
  *              H5Fset_latest_format() starting release 1.10.2.
  *              See explanation for H5Fset_latest_format() in H5Fdeprec.c.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1796,8 +1782,8 @@ done:
  *              downgrade persistent file space to non-persistent
  *              for 1.8 library.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1831,8 +1817,8 @@ done:
  *
  * Purpose:     Resets statistics for the page buffer layer.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1862,8 +1848,8 @@ done:
  *
  * Purpose:     Retrieves statistics for the page buffer layer.
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1901,8 +1887,8 @@ done:
  *              image_len:   --size of the on disk metadata cache image
  *                           --zero if no cache image
  *
- * Return:      SUCCEED/FAIL
- *
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1930,11 +1916,12 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Fget_eoa
  *
- * Purpose:     Returns the address of the first byte after the last
+ * Purpose:     Gets the address of the first byte after the last
  *              allocated memory in the file.
  *              (See H5FDget_eoa() in H5FD.c)
  *
- * Return:      SUCCEED/FAIL
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1967,7 +1954,8 @@ done:
  *
  * Purpose:     Set the EOA for the file to the maximum of (EOA, EOF) + increment
  *
- * Return:      SUCCEED/FAIL
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -1993,24 +1981,13 @@ done:
 
 
 /*-------------------------------------------------------------------------
- * Function: H5Fget_dset_no_attrs_hint
- *
- * Purpose:
- *
- *     Get the file-level setting to create minimized dataset object headers.
- *     Result is stored at pointer `minimize`.
+ * Function:    H5Fget_dset_no_attrs_hint
  *
- * Return:
+ * Purpose:     Get the file-level setting to create minimized dataset object headers.
+ *              Result is stored at pointer `minimize`.
  *
- *     Success: SUCCEED (0) (non-negative value)
- *     Failure: FAIL (-1) (negative value)
- *
- * Programmer:
- *
- *     Jacob Smith
- *     15 August 2018
- *
- * Changes: None.
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t
@@ -2038,23 +2015,13 @@ done:
 
 
 /*-------------------------------------------------------------------------
- * Function: H5Fset_dset_no_attrs_hint
- *
- * Purpose:
- *
- *     Set the file-level setting to create minimized dataset object headers.
- *
- * Return:
- *
- *     Success: SUCCEED (0) (non-negative value)
- *     Failure: FAIL (-1) (negative value)
- *
- * Programmer:
+ * Function:    H5Fset_dset_no_attrs_hint
  *
- *     Jacob Smith
- *     15 August 2018
+ * Purpose:     Set the file-level setting to create minimized dataset object
+ *              headers.
  *
- * Changes: None.
+ * Return:      Success:    Non-negative
+ *              Failure:    Negative
  *-------------------------------------------------------------------------
  */
 herr_t