Merge pull request #1721 in HDFFV/hdf5 from ~DEROBINS/hdf5_der:release_fixes to develop

* commit 'a668acfc6cb541cc6afa63f964af3d808d058883':
  Minor tweaks to the VOL function comments to bring them in line with the RM.

1 files changed, 27 insertions, 6 deletions

diff --git a/src/H5VL.c b/src/H5VL.c
index 2cd5f02..5c62f6f 100644
--- a/src/H5VL.c
+++ b/src/H5VL.c
@@ -74,6 +74,9 @@
  * Purpose:     Registers a new VOL connector as a member of the virtual object
  *              layer class.
  *
+ *              VIPL_ID is a VOL initialization property list which must be
+ *              created with H5Pcreate(H5P_VOL_INITIALIZE) (or H5P_DEFAULT).
+ *
  * Return:      Success:    A VOL connector ID which is good until the
  *                          library is closed or the connector is
  *                          unregistered.
@@ -124,6 +127,9 @@ done:
  * Purpose:     Registers a new VOL connector as a member of the virtual object
  *              layer class.
  *
+ *              VIPL_ID is a VOL initialization property list which must be
+ *              created with H5Pcreate(H5P_VOL_INITIALIZE) (or H5P_DEFAULT).
+ *
  * Return:      Success:    A VOL connector ID which is good until the
  *                          library is closed or the connector is
  *                          unregistered.
@@ -168,6 +174,9 @@ done:
  * Purpose:     Registers a new VOL connector as a member of the virtual object
  *              layer class.
  *
+ *              VIPL_ID is a VOL initialization property list which must be
+ *              created with H5Pcreate(H5P_VOL_INITIALIZE) (or H5P_DEFAULT).
+ *
  * Return:      Success:    A VOL connector ID which is good until the
  *                          library is closed or the connector is
  *                          unregistered.
@@ -209,9 +218,9 @@ done:
  *
  * Purpose:     Tests whether a VOL class has been registered or not
  *
- * Return:      >0 if the VOL class has been registered
- *              0 if it is unregistered
- *              <0 on error (if the class is not a valid class ID)
+ * Return:      >0 if a VOL connector with that name has been registered
+ *              0 if a VOL connector with that name has NOT been registered
+ *              <0 on errors
  *
  * Programmer:  Dana Robinson
  *              June 17, 2017
@@ -240,8 +249,12 @@ done:
  *
  * Purpose:     Retrieves the ID for a registered VOL connector.
  *
- * Return:      Positive if the VOL class has been registered
- *              Negative on error (if the class is not a valid class or not registered)
+ * Return:      A valid VOL connector ID if a connector by that name has
+ *              been registered. This ID will need to be closed using
+ *              H5VLclose().
+ *
+ *              H5I_INVALID_HID on error or if a VOL connector of that
+ *              name has not been registered.
  *
  * Programmer:  Dana Robinson
  *              June 17, 2017
@@ -269,7 +282,12 @@ done:
  * Function:    H5VLget_connector_name
  *
  * Purpose:     Returns the connector name for the VOL associated with the
- *              object or file ID
+ *              object or file ID.
+ *
+ *              This works like other calls where the caller must provide a
+ *              buffer of the appropriate size for the library to fill in.
+ *              i.e., passing in a NULL pointer for NAME will return the
+ *              required size of the buffer.
  *
  * Return:      Success:        The length of the connector name
  *
@@ -336,6 +354,9 @@ done:
  *              this VOL connector or files which are already opened under with
  *              this connector.
  *
+ *              The native VOL connector cannot be unregistered and attempts
+ *              to do so are considered an error.
+ *
  * Return:      Success:    Non-negative
  *
  *              Failure:    Negative