[svn-r27450] Add descriptions for all non-public functions.

Other comments.
Add some input checking.

Tested: ummon

7 files changed, 156 insertions, 45 deletions

diff --git a/src/H5Dvirtual.c b/src/H5Dvirtual.c
index 8b8af36..09519bf 100644
--- a/src/H5Dvirtual.c
+++ b/src/H5Dvirtual.c
@@ -17,7 +17,24 @@
  *              Wednesday, January 28, 2015
  *
  * Purpose:
- *      VDSINC
+ *      Virtual Dataset (VDS) functions.  Creates a layout type which allows
+ *      definition of a virtual dataset, where the actual dataset is stored in
+ *      other datasets (called source datasets).  The mappings between the
+ *      virtual and source datasets are specified by hyperslab or "all"
+ *      dataspace selections.  Point selections are not currently supported.
+ *      Overlaps in the mappings in the virtual dataset result in undefined
+ *      behaviour.
+ *
+ *      Mapping selections may be unlimited, in which case the size of the
+ *      virtual dataset is determined by the size of the source dataset(s).
+ *      Names for the source datasets may also be generated procedurally, in
+ *      which case the virtual selection should be unlimited with an unlimited
+ *      count and the source selection should be limited with a size equal to
+ *      that of the virtual selection with the unlimited count set to 1.
+ *
+ *      Source datasets are opened lazily (only when needed for I/O or to
+ *      determine the size of the virtual dataset), and are currently held open
+ *      until the virtual dataset is closed.
  */
 
 /****************/
@@ -1786,7 +1803,7 @@ done:
 /*-------------------------------------------------------------------------
  * Function:    H5D__virtual_post_io
  *
- * Purpose:     VDSINC
+ * Purpose:     Frees memory structures allocated by H5D__virtual_pre_io.
  *
  * Return:      Non-negative on success/Negative on failure
  *
diff --git a/src/H5Pdcpl.c b/src/H5Pdcpl.c
index bc32274..f687104 100644
--- a/src/H5Pdcpl.c
+++ b/src/H5Pdcpl.c
@@ -1805,6 +1805,7 @@ H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name,
     H5O_layout_t layout;        /* Layout information for setting chunk info */
     H5S_t *vspace;              /* Virtual dataset space selection */
     H5S_t *src_space;           /* Source dataset space selection */
+    hssize_t nelmts;           /* Number of elements */
     hbool_t new_layout = FALSE; /* Whether we are adding a new virtual layout message to plist */
     H5O_storage_virtual_ent_t *ent = NULL; /* Convenience pointer to new VDS entry */
     hbool_t adding_entry = FALSE; /* Whether we are in the middle of adding an entry */
@@ -1824,9 +1825,14 @@ H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name,
         HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataspace")
     if(NULL == (src_space = (H5S_t *)H5I_object_verify(src_space_id, H5I_DATASPACE)))
         HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataspace")
-
-    //VDSINC add check for overlapping virtual spaces and same number of
-    // elements in vspace and src_space
+    nelmts = H5S_GET_SELECT_NPOINTS(vspace);
+    if((nelmts != H5S_UNLIMITED)
+            && (nelmts != H5S_GET_SELECT_NPOINTS(src_space)))
+        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "virtual and source space selections have different numbers of elements")
+    /* Check for unlimited selections having the same number of elements in the
+     * non-unlimited dimensions, and check for printf selections having the
+     * correct numbers of elements and unlimited/non-unlimited dimensions VDSINC
+     */
 
 #ifndef H5_HAVE_C99_DESIGNATED_INITIALIZER
     /* If the compiler doesn't support C99 designated initializers, check if
diff --git a/src/H5Sall.c b/src/H5Sall.c
index 96ca1e5..1b9ceec 100644
--- a/src/H5Sall.c
+++ b/src/H5Sall.c
@@ -676,11 +676,16 @@ H5S_all_offset(const H5S_t H5_ATTR_UNUSED *space, hsize_t *offset)
  PURPOSE
     Return unlimited dimension of selection, or -1 if none
  USAGE
-    VDSINC
+    int H5S_all_unlim_dim(space)
+        H5S_t *space;           IN: Dataspace pointer to check
  RETURNS
     Unlimited dimension of selection, or -1 if none (never fails).
  DESCRIPTION
-    VDSINC
+    Returns the index of the unlimited dimension in this selection, or -1
+    if the selection has no unlimited dimension.  "All" selections are
+    always unlimited in every dimension, though this is not reflected in
+    other calls, where the selection is "clipped" against the current
+    extent, so for consistency this function always returns -1.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
  EXAMPLES
diff --git a/src/H5Shyper.c b/src/H5Shyper.c
index f0879b6..8736b69 100644
--- a/src/H5Shyper.c
+++ b/src/H5Shyper.c
@@ -2984,11 +2984,13 @@ done:
  PURPOSE
     Return unlimited dimension of selection, or -1 if none
  USAGE
-    VDSINC
+    int H5S_hyper_unlim_dim(space)
+        H5S_t *space;           IN: Dataspace pointer to check
  RETURNS
     Unlimited dimension of selection, or -1 if none (never fails).
  DESCRIPTION
-    VDSINC
+    Returns the index of the unlimited dimension of the selection, or -1
+    if the selection has no unlimited dimension.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
  EXAMPLES
@@ -9221,7 +9223,11 @@ H5S_hyper_get_seq_list(const H5S_t *space, unsigned H5_ATTR_UNUSED flags, H5S_se
     src_intersect_space within the selection of src_space as a selection
     within the selection of dst_space
  USAGE
-    VDSINC
+    herr_t H5S__hyper_project_intersection(src_space,dst_space,src_intersect_space,proj_space)
+        H5S_t *src_space;       IN: Selection that is mapped to dst_space, and intersected with src_intersect_space
+        H5S_t *dst_space;       IN: Selection that is mapped to src_space, and which contains the result
+        H5S_t *src_intersect_space; IN: Selection whose intersection with src_space is projected to dst_space to obtain the result
+        H5S_t *proj_space;      OUT: Will contain the result (intersection of src_intersect_space and src_space projected from src_space to dst_space) after the operation
  RETURNS
     Non-negative on success/Negative on failure.
  DESCRIPTION
@@ -9621,13 +9627,17 @@ done:
  NAME
     H5S__hyper_subtract
  PURPOSE
-    VDSINC
+    Subtract one hyperslab selection from another
  USAGE
-    VDSINC
+    herr_t H5S__hyper_subtract(space,subtract_space)
+        H5S_t *space;           IN/OUT: Selection to be operated on
+        H5S_t *subtract_space;  IN: Selection that will be subtracted from space
  RETURNS
     Non-negative on success/Negative on failure.
  DESCRIPTION
-    VDSINC
+    Removes any and all portions of space that are also present in
+    subtract_space.  In essence, performs an A_NOT_B operation with the
+    two selections.
 
     Note this function basically duplicates a subset of the functionality
     of H5S_select_select().  It should probably be removed when that
@@ -9735,7 +9745,12 @@ done:
     unlimited dimension to include clip_size.  The returned selection may
     extent beyond clip_size.
  USAGE
-    VDSINC
+    void H5S__hyper_get_clip_diminfo(start,stride,count,block,clip_size)
+        hsize_t start;          IN: Start of hyperslab in unlimited dimension
+        hsize_t stride;         IN: Stride of hyperslab in unlimited dimension
+        hsize_t *count;         IN/OUT: Count of hyperslab in unlimited dimension
+        hsize_t *block;         IN/OUT: Block of hyperslab in unlimited dimension
+        hsize_t clip_size;      IN: Extent that hyperslab will be clipped to
  RETURNS
     Non-negative on success/Negative on failure.
  DESCRIPTION
@@ -9784,12 +9799,15 @@ H5S__hyper_get_clip_diminfo(hsize_t start, hsize_t stride, hsize_t *count,
     Clips the unlimited dimension of the hyperslab selection to the
     specified size
  USAGE
-    VDSINC
+    void H5S_hyper_clip_unlim(space,clip_size)
+        H5S_t *space,           IN/OUT: Unlimited space to clip
+        hsize_t clip_size;      IN: Extent that hyperslab will be clipped to
  RETURNS
     Non-negative on success/Negative on failure.
  DESCRIPTION
-    This function recalculates the internal description of the hyperslab
-    to make the unlimited dimension extend to the specified extent.
+    This function changes the unlimited selection into a limited selection
+    with the extent of the formerly unlimited dimension specified by
+    * clip_size.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
     Note this function does not take the offset into account.
@@ -9895,13 +9913,23 @@ done:
  NAME
     H5S__hyper_get_clip_extent_real
  PURPOSE
-    VDSINC
+    Gets the extent a space should be clipped to in order to contain the
+    specified number of slices in the unlimited dimension
  USAGE
-    VDSINC
+    hsize_t H5S__hyper_get_clip_extent_real(clip_space,num_slices,incl_trail)
+        const H5S_t *clip_space, IN: Space that clip size will be calculated based on
+        hsize_t num_slizes,     IN: Number of slices clip_space should contain when clipped
+        hbool_t incl_trail;     IN: Whether to include trailing unselected space
  RETURNS
-    Non-negative on success/Negative on failure.
+    Clip extent to match num_slices (never fails)
  DESCRIPTION
-    VDSINC
+    Calculates and returns the extent that clip_space should be clipped to
+    (via H5S_hyper_clip_unlim) in order for it to contain num_slices
+    slices in the unlimited dimension.  If the clipped selection would end
+    immediately before a section of unselected space (i.e. at the end of a
+    block), then if incl_trail is TRUE, the returned clip extent is
+    selected to include that trailing "blank" space, otherwise it is
+    selected to end at the end before the blank space.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
     Note this assumes the offset has been normalized.
@@ -9970,13 +9998,23 @@ H5S__hyper_get_clip_extent_real(const H5S_t *clip_space, hsize_t num_slices,
  NAME
     H5S_hyper_get_clip_extent
  PURPOSE
-    VDSINC
+    Gets the extent a space should be clipped to in order to contain the
+    same number of elements as another space
  USAGE
-    VDSINC
+    hsize_t H5S__hyper_get_clip_extent(clip_space,match_space,incl_trail)
+        const H5S_t *clip_space, IN: Space that clip size will be calculated based on
+        const H5S_t *match_space, IN: Space containing the same number of elements as clip_space should after clipping
+        hbool_t incl_trail;     IN: Whether to include trailing unselected space
  RETURNS
-    Non-negative on success/Negative on failure.
+    Calculated clip extent (never fails)
  DESCRIPTION
-    VDSINC
+    Calculates and returns the extent that clip_space should be clipped to
+    (via H5S_hyper_clip_unlim) in order for it to contain the same number
+    of elements as match_space.  If the clipped selection would end
+    immediately before a section of unselected space (i.e. at the end of a
+    block), then if incl_trail is TRUE, the returned clip extent is
+    selected to include that trailing "blank" space, otherwise it is
+    selected to end at the end before the blank space.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
     Note this assumes the offset has been normalized.
@@ -10015,13 +10053,26 @@ H5S_hyper_get_clip_extent(const H5S_t *clip_space, const H5S_t *match_space,
  NAME
     H5S_hyper_get_clip_extent_match
  PURPOSE
-    VDSINC
+    Gets the extent a space should be clipped to in order to contain the
+    same number of elements as another unlimited space that has been
+    clipped to a different extent
  USAGE
-    VDSINC
+    hsize_t H5S__hyper_get_clip_extent_match(clip_space,match_space,match_clip_size,incl_trail)
+        const H5S_t *clip_space, IN: Space that clip size will be calculated based on
+        const H5S_t *match_space, IN: Space that, after being clipped to match_clip_size, contains the same number of elements as clip_space should after clipping
+        hsize_t match_clip_size, IN: Extent match_space would be clipped to to match the number of elements in clip_space
+        hbool_t incl_trail;     IN: Whether to include trailing unselected space
  RETURNS
-    Non-negative on success/Negative on failure.
+    Calculated clip extent (never fails)
  DESCRIPTION
-    VDSINC
+    Calculates and returns the extent that clip_space should be clipped to
+    (via H5S_hyper_clip_unlim) in order for it to contain the same number
+    of elements as match_space would have after being clipped to
+    match_clip_size.  If the clipped selection would end immediately
+    before a section of unselected space (i.e. at the end of a block),
+    then if incl_trail is TRUE, the returned clip extent is selected to
+    include that trailing "blank" space, otherwise it is selected to end
+    at the end before the blank space.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
     Note this assumes the offset has been normalized.
@@ -10090,13 +10141,18 @@ H5S_hyper_get_clip_extent_match(const H5S_t *clip_space,
  NAME
     H5S_hyper_get_unlim_block
  PURPOSE
-    VDSINC
+    Get the nth block in the unlimited dimension
  USAGE
-    VDSINC
+    H5S_t *H5S_hyper_get_unlim_block(space,block_index)
+        const H5S_t *space,     IN: Space with unlimited selection
+        hsize_t block_index,    IN: Index of block to return in unlimited dimension
+        hbool_t incl_trail;     IN: Whether to include trailing unselected space
  RETURNS
     New space on success/NULL on failure.
  DESCRIPTION
-    VDSINC
+    Returns a space containing only the block_indexth block in the
+    unlimited dimension on space.  All blocks in all other dimensions are
+    preserved.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
     Note this assumes the offset has been normalized.
@@ -10172,13 +10228,20 @@ done:
  NAME
     H5S_hyper_get_first_inc_block
  PURPOSE
-    VDSINC
+    Get the index of the first incomplete block in the specified extent
  USAGE
-    VDSINC
+    hsize_t H5S_hyper_get_first_inc_block(space,clip_size,partial)
+        const H5S_t *space,     IN: Space with unlimited selection
+        hsize_t clip_size,      IN: Extent space would be clipped to
+        hbool_t *partial;       OUT: Whether the ret_valueth block (first incomplete block) is partial
  RETURNS
     Index of first incomplete block in clip_size (never fails).
  DESCRIPTION
-    VDSINC
+    Calculates and returns the index (as would be passed to
+    H5S_hyper_get_unlim_block()) of the first block in the unlimited
+    dimension of space which would be incomplete or missing when space is
+    clipped to clip_size.  partial is set to TRUE if the first incomplete
+    block is partial, and FALSE if the first incomplete block is missing.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
     Note this assumes the offset has been normalized.
diff --git a/src/H5Snone.c b/src/H5Snone.c
index 196cf54..b4e2f0e 100644
--- a/src/H5Snone.c
+++ b/src/H5Snone.c
@@ -626,11 +626,14 @@ H5S_none_offset(const H5S_t H5_ATTR_UNUSED *space, hsize_t H5_ATTR_UNUSED *offse
  PURPOSE
     Return unlimited dimension of selection, or -1 if none
  USAGE
-    VDSINC
+    int H5S_none_unlim_dim(space)
+        H5S_t *space;           IN: Dataspace pointer to check
  RETURNS
     Unlimited dimension of selection, or -1 if none (never fails).
  DESCRIPTION
-    VDSINC
+    Returns the index of the unlimited dimension in this selection, or -1
+    if the selection has no unlimited dimension.  "None" selections cannot
+    have an unlimited dimension, so this function always returns -1.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
  EXAMPLES
diff --git a/src/H5Spoint.c b/src/H5Spoint.c
index 8e04b18..1ea4a23 100644
--- a/src/H5Spoint.c
+++ b/src/H5Spoint.c
@@ -1202,11 +1202,15 @@ done:
  PURPOSE
     Return unlimited dimension of selection, or -1 if none
  USAGE
-    VDSINC
+    int H5S_point_unlim_dim(space)
+        H5S_t *space;           IN: Dataspace pointer to check
  RETURNS
     Unlimited dimension of selection, or -1 if none (never fails).
  DESCRIPTION
-    VDSINC
+    Returns the index of the unlimited dimension in this selection, or -1
+    if the selection has no unlimited dimension.  Currently point
+    selections cannot have an unlimited dimension, so this function always
+    returns -1.
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
  EXAMPLES
diff --git a/src/H5Sselect.c b/src/H5Sselect.c
index 535e955..bb74b14 100644
--- a/src/H5Sselect.c
+++ b/src/H5Sselect.c
@@ -2170,16 +2170,25 @@ done:
     H5S_select_project_intersection
 
  PURPOSE
-    VDSINC
+    Projects the intersection of of the selections of src_space and
+    src_intersect_space within the selection of src_space as a selection
+    within the selection of dst_space
 
  USAGE
-    VDSINC
+    herr_t H5S_select_project_intersection(src_space,dst_space,src_intersect_space,proj_space)
+        H5S_t *src_space;       IN: Selection that is mapped to dst_space, and intersected with src_intersect_space
+        H5S_t *dst_space;       IN: Selection that is mapped to src_space, and which contains the result
+        H5S_t *src_intersect_space; IN: Selection whose intersection with src_space is projected to dst_space to obtain the result
+        H5S_t *proj_space;      OUT: Will contain the result (intersection of src_intersect_space and src_space projected from src_space to dst_space) after the operation
 
  RETURNS
     Non-negative on success/Negative on failure.
 
  DESCRIPTION
-    VDSINC
+    Projects the intersection of of the selections of src_space and
+    src_intersect_space within the selection of src_space as a selection
+    within the selection of dst_space.  The result is placed in the
+    selection of proj_space.
     
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS
@@ -2259,16 +2268,20 @@ done:
     H5S_select_subtract
 
  PURPOSE
-    VDSINC
+    Subtract one selection from another
 
  USAGE
-    VDSINC
+    herr_t H5S_select_subtract(space,subtract_space)
+        H5S_t *space;           IN/OUT: Selection to be operated on
+        H5S_t *subtract_space;  IN: Selection that will be subtracted from space
 
  RETURNS
     Non-negative on success/Negative on failure.
 
  DESCRIPTION
-    VDSINC
+    Removes any and all portions of space that are also present in
+    subtract_space.  In essence, performs an A_NOT_B operation with the
+    two selections.
     
  GLOBAL VARIABLES
  COMMENTS, BUGS, ASSUMPTIONS