[svn-r27547] Fill in public function descriptions from RM entries.

Tested: ummon

2 files changed, 94 insertions, 15 deletions

diff --git a/src/H5Pdapl.c b/src/H5Pdapl.c
index 5574fa9..94ae0b4 100644
--- a/src/H5Pdapl.c
+++ b/src/H5Pdapl.c
@@ -316,7 +316,16 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Pset_virtual_view
  *
- * Purpose:     VDSINC
+ * Purpose:     Takes the access property list for the virtual dataset,
+ *              dapl_id, and the flag, view, and sets the VDS view
+ *              according to the flag value.  The view will include all
+ *              data before the first missing mapped data found if the
+ *              flag is set to H5D_VDS_FIRST_MISSING or to include all
+ *              available mapped data if the flag is set to
+ *              H5D_VDS_LAST_AVAIALBLE.  Missing mapped data will be
+ *              filled with the fill value according to the VDS creation
+ *              property settings.  For VDS with unlimited mappings, the
+ *              view defines the extent.
  *
  * Return:      Non-negative on success/Negative on failure
  *
@@ -354,7 +363,10 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Pget_virtual_view
  *
- * Purpose:     VDSINC
+ * Purpose:     Takes the access property list for the virtual dataset,
+ *              dapl_id, and gets the flag, view, set by the
+ *              H5Pset_virtual_view call.  The possible values of view are
+ *              H5D_VDS_FIRST_MISSING or H5D_VDS_LAST_AVAIALBLE. 
  *
  * Return:      Success:        H5D_VDS_FIRST_MISSING or
  *                              H5D_VDS_LAST_AVAILABLE
@@ -462,7 +474,22 @@ H5P__dacc_vds_view_dec(const void **_pp, void *_value)
 /*-------------------------------------------------------------------------
  * Function:    H5Pset_virtual_printf_gap
  *
- * Purpose:     VDSINC
+ * Purpose:     Sets the access property list for the virtual dataset,
+ *              dapl_id, to instruct the library to stop looking for the
+ *              mapped data stored in the files and/or datasets with the
+ *              printf-style names after not finding gap_size files and/or
+ *              datasets.  The found source files and datasets will
+ *              determine the extent of the unlimited VDS with the printf
+ *              -style mappings.
+ *
+ *              For example, if regularly spaced blocks of VDS are mapped
+ *              to datasets with the names d-1, d-2, d-3, ..., d-N, ...,
+ *              and d-2 dataset is missing and gap_size is set to 0, then
+ *              VDS will contain only data found in d-1.  If d-2 and d-3
+ *              are missing and gap_size is set to 2, then VDS will
+ *              contain the data from d-1, d-3, ..., d-N, ....  The blocks
+ *              that are mapped to d-2 and d-3 will be filled according to
+ *              the VDS fill value setting.
  *
  * Return:      Non-negative on success/Negative on failure
  *
@@ -500,7 +527,11 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Pget_virtual_printf_gap
  *
- * Purpose:     VDSINC
+ * Purpose:     Gets the maximum number of missing printf-style files
+ *              and/or datasets for determining the extent of the
+ *              unlimited VDS, gap_size, using the access property list
+ *              for the virtual dataset, dapl_id.  The default library
+ *              value for gap_size is 0.
  *
  * Return:      Non-negative on success/Negative on failure
  *
diff --git a/src/H5Pdcpl.c b/src/H5Pdcpl.c
index ebc3919..16577e7 100644
--- a/src/H5Pdcpl.c
+++ b/src/H5Pdcpl.c
@@ -1785,7 +1785,12 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Pset_virtual
  *
- * Purpose:     VDSINC
+ * Purpose:     Maps elements of the virtual dataset described by the
+ *              virtual dataspace identifier vspace_id to the elements of
+ *              the source dataset described by the source dataset
+ *              dataspace identifier src_space_id.  The source dataset is
+ *              identified by the name of the file where it is located,
+ *              src_file_name, and the name of the dataset, src_dset_name.
  *
  *              As a side effect, the layout method is changed to
  *              H5D_VIRTUAL.
@@ -1981,7 +1986,9 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Pget_virtual_count
  *
- * Purpose:     VDSINC
+ * Purpose:     Gets the number of mappings for the virtual dataset that
+ *              has a creation property list specified by the dcpl_id
+ *              parameter.
  *
  * Return:      Non-negative on success/Negative on failure
  *
@@ -2023,9 +2030,13 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Pget_virtual_vspace
  *
- * Purpose:     VDSINC
+ * Purpose:     Takes the dataset creation property list for the virtual
+ *              dataset, dcpl_id, and the mapping index, index, and
+ *              returns a dataspace identifier for the selection within
+ *              the virtual dataset used in the mapping. 
  *
- * Return:      VDSINC
+ * Return:      Returns a dataspace identifier if successful; otherwise
+ *              returns a negative value.
  *
  * Programmer:  Neil Fortner
  *              Friday, February  13, 2015
@@ -2077,9 +2088,13 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Pget_virtual_srcspace
  *
- * Purpose:     VDSINC
+ * Purpose:     Takes the dataset creation property list for the virtual
+ *              dataset, dcpl_id, and the mapping index, index, and
+ *              returns a dataspace identifier for the selection within
+ *              the source dataset used in the mapping. 
  *
- * Return:      VDSINC
+ * Return:      Returns a dataspace identifier if successful; otherwise
+ *              returns a negative value.
  *
  * Programmer:  Neil Fortner
  *              Saturday, February  14, 2015
@@ -2165,9 +2180,26 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Pget_virtual_filename
  *
- * Purpose:     VDSINC
+ * Purpose:     Takes the dataset creation property list for the virtual
+ *              dataset, dcpl_id, and the mapping index, index, and
+ *              retrieves a name of a file for a source dataset used in
+ *              the mapping.
  *
- * Return:      VDSINC
+ *              Up to size characters of the filename are returned in
+ *              name; additional characters, if any, are not returned to
+ *              the user application.
+ *
+ *              If the length of the filename, which determines the
+ *              required value of size, is unknown, a preliminary call to
+ *              H5Pget_virtual_filename with the last two parameters set
+ *              to NULL can be made.  The return value of this call will
+ *              be the size in bytes of the filename.  That value, plus 1
+ *              for a NULL terminator, is then assigned to size for a
+ *              second H5Pget_virtual_filename call, which will retrieve
+ *              the actual filename. 
+ *
+ * Return:      Returns the length of the name if successful, otherwise
+ *              returns a negative value.
  *
  * Programmer:  Neil Fortner
  *              Saturday, February  14, 2015
@@ -2212,9 +2244,25 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5Pget_virtual_dsetname
  *
- * Purpose:     VDSINC
- *
- * Return:      VDSINC
+ * Purpose:     Takes the dataset creation property list for the virtual
+ *              dataset, dcpl_id, and the mapping index, index, and
+ *              retrieves the name of a source dataset used in the mapping.
+ *
+ *              Up to size characters of the name are returned in name;
+ *              additional characters, if any, are not returned to the
+ *              user application.
+ *
+ *              If the length of the filename, which determines the
+ *              required value of size, is unknown, a preliminary call to
+ *              H5Pget_virtual_dsetname with the last two parameters set
+ *              to NULL can be made.  The return value of this call will
+ *              be the size in bytes of the filename.  That value, plus 1
+ *              for a NULL terminator, is then assigned to size for a
+ *              second H5Pget_virtual_dsetname call, which will retrieve
+ *              the actual filename. 
+ *
+ * Return:      Returns the length of the name if successful, otherwise
+ *              returns a negative value.
  *
  * Programmer:  Neil Fortner
  *              Saturday, February  14, 2015