[svn-r8465] Purpose:

    Add more C++ wrappers - incrementally check-in

Description:
    Added wrapper for many C property list functions and added Doxygen
    documentation to existing C++ functions in these files.  This is
    an incremental check-in to preserve the code, corresponding tests
    will follow in a few weeks.

    For H5PropList.h and H5PropList.cpp, added C++ wrappers for:
	H5Pexist
	H5Pclose_class
	H5Pget
	H5Pget_size
	H5Pget_class_name
	H5Pget_nprops
	H5Pset
	H5Pisa_class
	H5Premove
	H5Pequal
	H5Pget_class_parent

   For H5FaccProp.h and H5FaccProp.cpp, added C++ wrappers for:
	H5Ps[g]et_driver
	H5Ps[g]et_family_offset
	H5Ps[g]et_fapl_core
	H5Ps[g]et_fapl_family
	H5Ps[g]et_fapl_stream
	H5Ps[g]et_sieve_buf_size
	H5Ps[g]et_meta_block_size
	H5Ps[g]et_alignment
	H5Ps[g]et_multi_type
	H5Ps[g]et_fclose_degree
	H5Pset_fapl_stdio
	H5Pset_fapl_split
	H5Pset_fapl_log
	H5Pset_fapl_sec2

   For H5FcreatProp.h and H5FcreatProp.cpp, added C++ wrappers for:
	H5Pfill_value_defined
	H5Premove_filter
	H5Pget_filter_by_id
	H5Pmodify_filter
	H5Pall_filters_avail
	H5Pset_shuffle
	H5Ps[g]et_alloc_time
	H5Ps[g]et_fill_time
	H5Pset_fletcher32

   For H5DxferProp.h and H5DxferProp.cpp, added C++ wrappers for:
	H5Ps[g]et_dxpl_multi
	H5Ps[g]et_small_data_block_size
	H5Ps[g]et_hyper_vector_size
	H5Ps[g]et_edc_check

Platforms:
    SunOS 5.7 (arabica)
    Linux 2.4 (eirene)
    SunOS 5.8-64 (sol)

1 files changed, 430 insertions, 37 deletions

diff --git a/c++/src/H5DcreatProp.cpp b/c++/src/H5DcreatProp.cpp
index efaf30d..6fc445f 100644
--- a/c++/src/H5DcreatProp.cpp
+++ b/c++/src/H5DcreatProp.cpp
@@ -29,13 +29,33 @@ namespace H5 {
 
 const DSetCreatPropList DSetCreatPropList::DEFAULT( H5P_DEFAULT );
 
-// Creates a dataset creation property list
+//--------------------------------------------------------------------------
+// Function:	Default Constructor
+///\brief	Default Constructor: Creates a dataset creation property list
+//--------------------------------------------------------------------------
 DSetCreatPropList::DSetCreatPropList() : PropList( H5P_DATASET_CREATE) {}
 
-// Copy constructor: makes a copy of the original DSetCreatPropList object;
+//--------------------------------------------------------------------------
+// Function:	Copy Constructor
+///\brief	Copy Constructor: Makes a copy of the original 
+///		DSetCreatPropList object
+//--------------------------------------------------------------------------
 DSetCreatPropList::DSetCreatPropList( const DSetCreatPropList& orig ) : PropList( orig ) {}
 
-// Sets the size of the chunks used to store a chunked layout dataset.
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::setChunk
+///\brief	Sets the size of the chunks used to store a chunked layout 
+///		dataset.
+///\param       ndims - IN: Number of dimensions of each chunk
+///\param	dim   - IN: Array containing the size of each chunk
+///\exception	H5::PropListIException
+///\par Description
+///		The \a ndims parameter currently must have the same value as
+///		the rank of the dataset.  The values of the \a dim array 
+///		define the size of the chunks to store the dataset's raw 
+///		data.  As a side-effect, the layout of the dataset will be 
+///		changed to \c H5D_CHUNKED, if it is not so already.
+//--------------------------------------------------------------------------
 void DSetCreatPropList::setChunk( int ndims, const hsize_t* dim ) const
 {
    herr_t ret_value = H5Pset_chunk( id, ndims, dim );
@@ -45,20 +65,14 @@ void DSetCreatPropList::setChunk( int ndims, const hsize_t* dim ) const
    }
 }
 
-// Gets the layout of the raw data storage of the data that uses this
-// property list
-H5D_layout_t DSetCreatPropList::getLayout() const
-{
-   H5D_layout_t layout = H5Pget_layout( id );
-   if( layout == H5D_LAYOUT_ERROR )
-   {
-      throw PropListIException("DSetCreatPropList::getLayout", 
-		"H5Pget_layout returns H5D_LAYOUT_ERROR");
-   }
-   return( layout );
-}
-
-// Retrieves the size of the chunks used to store a chunked layout dataset.
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::getChunk
+///\brief	Retrieves the size of the chunks used to store a chunked 
+///		layout dataset.
+///\param       max_ndims - IN: Size of \a dim array
+///\param	dim      - OUT: Array to store the chunk dimensions
+///\exception	H5::PropListIException
+//--------------------------------------------------------------------------
 int DSetCreatPropList::getChunk( int max_ndims, hsize_t* dim ) const
 {
    int chunk_size = H5Pget_chunk( id, max_ndims, dim );
@@ -70,7 +84,16 @@ int DSetCreatPropList::getChunk( int max_ndims, hsize_t* dim ) const
    return( chunk_size );
 }
 
-// Sets the type of storage used store the raw data for a dataset.
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::setLayout
+///\brief	Sets the type of storage used store the raw data for a dataset.
+///\param	plist  - IN: Property list id, here by mistake, should be removed
+///\param       layout - IN: Type of storage layout for raw data
+///\exception	H5::PropListIException
+///\par Description
+///		For information on setting layout type, please refer to
+/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetLayout
+//--------------------------------------------------------------------------
 void DSetCreatPropList::setLayout(hid_t plist, H5D_layout_t layout ) const
 {
    herr_t ret_value = H5Pset_layout( id, layout );
@@ -81,7 +104,43 @@ void DSetCreatPropList::setLayout(hid_t plist, H5D_layout_t layout ) const
    }
 }
 
-// Sets compression method and compression level
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::getLayout
+///\brief	Retrieves the layout type of this property list
+///\return	Layout type, which can be:
+///		\li \c H5D_COMPACT - raw data is stored in the object 
+///				header in the file. 
+///		\li \c H5D_CONTIGUOUS - raw data is stored separately from the
+///				object header in one contiguous chunk in 
+///				the file. 
+///		\li \c H5D_CHUNKED - raw data is stored separately from the 
+///				object header in chunks in separate locations 
+///				in the file. 
+///\exception	H5::PropListIException
+///\par Description
+//--------------------------------------------------------------------------
+H5D_layout_t DSetCreatPropList::getLayout() const
+{
+   H5D_layout_t layout = H5Pget_layout( id );
+   if( layout == H5D_LAYOUT_ERROR )
+   {
+      throw PropListIException("DSetCreatPropList::getLayout", 
+		"H5Pget_layout returns H5D_LAYOUT_ERROR");
+   }
+   return( layout );
+}
+
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::setDeflate
+///\brief	Sets compression method and compression level
+///\param	level - IN: Compression level, should [0..9], inclusive
+///\exception	H5::PropListIException
+///\par Description
+///		The function sets the compression method for this property 
+///		list to \c H5D_COMPRESS_DEFLATE and the compression level to 
+///		\a level. Lower compression levels are faster but result in 
+///		less compression.
+//--------------------------------------------------------------------------
 void DSetCreatPropList::setDeflate( int level ) const
 {
    herr_t ret_value = H5Pset_deflate( id, level );
@@ -92,7 +151,23 @@ void DSetCreatPropList::setDeflate( int level ) const
    }
 }
 
-// Sets a dataset fill value
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::setFillValue
+///\brief	Sets a dataset fill value
+///\param	fvalue_type - IN: Data type for the value passed via \a value
+///\param	value - IN: Pointer to buffer containing the fill value
+///\exception	H5::PropListIException
+///\par Description
+///		The datatype may differ from that of the dataset, but it must
+///		be one that the HDF5 library is able to convert \a value to 
+///		the dataset datatype when the dataset is created.
+///		The default fill value is 0 (zero,) which is interpreted 
+///		according to the actual dataset datatype.
+///\par		
+///		For information on setting fill value, please refer to the
+///		C layer Reference Manual at:
+/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetFillValue
+//--------------------------------------------------------------------------
 void DSetCreatPropList::setFillValue( const DataType& fvalue_type, const void* value ) const
 {
    herr_t ret_value = H5Pset_fill_value( id, fvalue_type.getId(), value );
@@ -103,7 +178,18 @@ void DSetCreatPropList::setFillValue( const DataType& fvalue_type, const void* v
    }
 }
 
-// Retrieves a dataset fill value
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::getFillValue
+///\brief	Retrieves a dataset fill value
+///\param	fvalue_type - IN: Data type for the value passed via \a value
+///\param	value - OUT: Pointer to buffer to hold the retrieved fill value
+///\exception	H5::PropListIException
+///\par Description
+///		The fill value is returned through \a value pointer 
+///             and the memory is allocated by the caller.  The fill
+///             value will be converted from its current data type to the
+///             specified by \a fvalue_type.
+//--------------------------------------------------------------------------
 void DSetCreatPropList::getFillValue( const DataType& fvalue_type, void* value ) const
 {
    herr_t ret_value = H5Pget_fill_value( id, fvalue_type.getId(), value );
@@ -114,10 +200,50 @@ void DSetCreatPropList::getFillValue( const DataType& fvalue_type, void* value )
    }
 }
 
-// Adds a filter to the filter pipeline
-void DSetCreatPropList::setFilter( H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] ) const
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::isFillValueDefined
+///\brief	Check if fill value has been defined for this property
+///\return     	
+///		\li \c H5D_FILL_VALUE_UNDEFINED    =0,
+///		\li \c H5D_FILL_VALUE_DEFAULT      =1,
+///		\li \c H5D_FILL_VALUE_USER_DEFINED =2
+///\exception	H5::PropListIException
+//--------------------------------------------------------------------------
+H5D_fill_value_t DSetCreatPropList::isFillValueDefined()
 {
-   herr_t ret_value = H5Pset_filter( id, filter, flags, cd_nelmts, cd_values );
+   H5D_fill_value_t status;
+   herr_t ret_value = H5Pfill_value_defined(id, &status);
+   if( ret_value < 0 )
+   {
+      throw PropListIException("DSetCreatPropList::isFillValueDefined",
+                "H5Pfill_value_defined returned H5D_FILL_VALUE_ERROR (-1)");
+   }
+   else
+      return (status);
+}
+
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::setFilter
+///\brief       Adds a filter to the filter pipeline
+///\param       filter_id - IN: Filter to add
+///\param	flags     - IN: Specifies general properties of the filter
+///\param	cd_nelmts - IN: Number of elements in cd_values
+///\param	cd_values - IN: Auxiliary data for the filter
+///\exception	H5::PropListIException
+///\par Description
+///             The \a flags argument is a bit vector of the field:
+///             \c H5Z_FLAG_OPTIONAL(0x0001)
+///\par
+///		If this bit is set then the filter is optional.  If the filter
+///             fails during a \c DataSet::write() operation then the filter
+///             is just excluded from the pipeline for the chunk for which it
+///             failed; the filter will not participate in the pipeline
+///             during a \c DataSet::read() of the chunk.  If this bit is clear 
+///             and the filter fails then the entire I/O operation fails.
+//--------------------------------------------------------------------------
+void DSetCreatPropList::setFilter( H5Z_filter_t filter_id, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] ) const
+{
+   herr_t ret_value = H5Pset_filter( id, filter_id, flags, cd_nelmts, cd_values );
    if( ret_value < 0 )
    {
       throw PropListIException("DSetCreatPropList::setFilter",
@@ -125,10 +251,18 @@ void DSetCreatPropList::setFilter( H5Z_filter_t filter, unsigned int flags, size
    }
 }
 
-// Removes one or more filters to the filter pipeline
-void DSetCreatPropList::removeFilter( H5Z_filter_t filter) const
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::removeFilter
+///\brief	Removes one or more filters 
+///\param       filter_id - IN: Filter to remove
+///\exception	H5::PropListIException
+///\par Description
+///		Deletes a filter from the dataset creation property list;
+///		deletes all filters if \a filter_id is \c H5Z_FILTER_NONE.
+//--------------------------------------------------------------------------
+void DSetCreatPropList::removeFilter(H5Z_filter_t filter_id) const
 {
-   herr_t ret_value = H5Premove_filter( id, filter);
+   herr_t ret_value = H5Premove_filter( id, filter_id);
    if( ret_value < 0 )
    {
       throw PropListIException("DSetCreatPropList::removeFilter",
@@ -136,7 +270,12 @@ void DSetCreatPropList::removeFilter( H5Z_filter_t filter) const
    }
 }
 
-// Returns the number of filters in the pipeline 
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::getNfilters
+///\brief	Returns the number of filters in the pipeline 
+///\return	Number of filters
+///\exception	H5::PropListIException
+//--------------------------------------------------------------------------
 int DSetCreatPropList::getNfilters() const
 {
    int num_filters = H5Pget_nfilters( id );
@@ -149,22 +288,251 @@ int DSetCreatPropList::getNfilters() const
       return( num_filters );
 }
 
-// Returns information about a filter in a pipeline
-H5Z_filter_t DSetCreatPropList::getFilter( int filter_number, unsigned int& flags, size_t& cd_nelmts, unsigned int* cd_values, size_t namelen, char name[] ) const
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::getFilter
+///\brief	Returns information about a filter in a pipeline
+///\param       filter_number - IN: Filter to get, range [0..N-1], where 
+///				N is returned by H5Pget_nfilters()
+///\param	flags     - OUT: General properties of the filter
+///\param	cd_nelmts - IN/OUT: Number of elements in \a cd_values /Number 
+///				of values defined by the filter
+///\param	cd_values - OUT: Array to hold the data; allocated by the user
+///\param	namelen   - OUT: Length of \a name
+///\param	name      - OUT: Name of the filter
+///\return	Filter id
+///\exception	H5::PropListIException
+///\par Description
+///		Failure occurs when \a filter_number is out of range.
+//--------------------------------------------------------------------------
+H5Z_filter_t DSetCreatPropList::getFilter(int filter_number, unsigned int &flags, size_t &cd_nelmts, unsigned int* cd_values, size_t namelen, char name[]) const
 {
-   H5Z_filter_t filter;
-   filter = H5Pget_filter( id, filter_number, &flags, &cd_nelmts, 
+   H5Z_filter_t filter_id;
+   filter_id = H5Pget_filter( id, filter_number, &flags, &cd_nelmts, 
 				cd_values, namelen, name );
-   if( filter == H5Z_FILTER_ERROR )
+   if( filter_id == H5Z_FILTER_ERROR )
    {
       throw PropListIException("DSetCreatPropList::getFilter",
                 "H5Pget_filter returned H5Z_FILTER_ERROR");
    }
    else
-      return( filter );
+      return(filter_id);
+}
+
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::getFilterById
+///\brief	Returns information about a filter in a pipeline given the
+///		filter id
+///\param       filter_id -  IN: Filter to get
+///\param	flags     - OUT: General properties of the filter
+///\param	cd_nelmts - IN/OUT: Number of elements in \a cd_values /Number 
+///				of values defined by the filter
+///\param	cd_values - OUT: Array to hold the data; allocated by the user
+///\param	namelen   -  IN: Length of \a name
+///\param	name      - OUT: Name of the filter
+///\exception	H5::PropListIException
+//--------------------------------------------------------------------------
+void DSetCreatPropList::getFilterById(H5Z_filter_t filter_id, unsigned int &flags, size_t &cd_nelmts, unsigned int* cd_values, size_t namelen, char name[]) const
+{
+   herr_t ret_value = H5Pget_filter_by_id(id, filter_id, &flags, &cd_nelmts, 
+				cd_values, namelen, name );
+   if (ret_value < 0)
+   {
+      throw PropListIException("DSetCreatPropList::getFilterById",
+                "H5Pget_filter_by_id failed");
+   }
+}
+
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::modifyFilter
+///\brief	Modifies the specified filter
+///\param	filter_id -  IN: Filter to get
+///\param	flags     - OUT: General properties of the filter
+///\param	cd_nelmts -  IN: Number of elements in \a cd_values
+///			\n  OUT: Number of values defined by the filter
+///\param	cd_values - OUT: Array to hold the data; allocated by the user
+///\exception	H5::PropListIException
+///\par Description
+///             The \a flags argument is a bit vector of the field:
+///             \c H5Z_FLAG_OPTIONAL(0x0001)
+///\par
+///		If this bit is set then the filter is optional.  If the filter
+///             fails during a DataSet::write() operation then the filter
+///             is just excluded from the pipeline for the chunk for which it
+///             failed; the filter will not participate in the pipeline
+///             during a DataSet::read() of the chunk.  If this bit is clear 
+///             and the filter fails then the entire I/O operation fails.
+//--------------------------------------------------------------------------
+void DSetCreatPropList::modifyFilter( H5Z_filter_t filter_id, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] ) const
+{
+   herr_t ret_value = H5Pmodify_filter(id, filter_id, flags, cd_nelmts, cd_values);
+   if( ret_value < 0 )
+   {
+      throw PropListIException("DSetCreatPropList::modifyFilter",
+                "H5Pmodify_filter failed");
+   }
+}
+
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::allFiltersAvail
+///\brief       Queries whether all the filters set in this property list 
+///		are available currently.
+///\return      true if all filters available, and false if one or more 
+///		filters not currently available
+///\exception   H5::PropListIException
+//--------------------------------------------------------------------------
+bool DSetCreatPropList::allFiltersAvail()
+{
+   htri_t ret_value = H5Pall_filters_avail(id);
+   if( ret_value > 0 )
+      return true;
+   else if( ret_value == 0 )
+      return false;
+   else // Raise exception when H5Pall_filters_avail returns a negative value
+   {
+      throw PropListIException("DSetCreatPropList::allFiltersAvail", "H5Pall_filters_avail returned negative value");
+   }
+}
+
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::setShuffle
+///\brief       Sets method of the shuffle filter
+///\exception   H5::PropListIException
+///\par Description
+///		Please refer to the Reference Manual of \c H5Pset_shuffle for
+///		details.
+/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetShuffle 
+//--------------------------------------------------------------------------
+void DSetCreatPropList::setShuffle()
+{
+   herr_t ret_value = H5Pset_shuffle(id);
+   if( ret_value < 0 )
+   {
+      throw PropListIException("DSetCreatPropList::setShuffle",
+                "H5Pset_shuffle failed");
+   }
+}
+
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::getAllocTime
+///\brief	Get space allocation time for this property.
+///\return	Space allocation time.
+///\exception	H5::PropListIException
+///\par Description
+///		The values of space allocation time can be one of the 
+///		followings:
+///		\li \c H5D_ALLOC_TIME_DEFAULT
+///		\li \c H5D_ALLOC_TIME_EARLY
+///		\li \c H5D_ALLOC_TIME_LATE
+///		\li \c H5D_ALLOC_TIME_INCR
+//--------------------------------------------------------------------------
+H5D_alloc_time_t DSetCreatPropList::getAllocTime()
+{
+   H5D_alloc_time_t alloc_time;
+   herr_t ret_value = H5Pget_alloc_time(id, &alloc_time);
+   if( ret_value < 0 )
+   {
+      throw PropListIException("DSetCreatPropList::getAllocTime",
+                "H5Pget_alloc_time failed");
+   }
+   else
+      return (alloc_time);
+}
+
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::getFillTime
+///\brief       Gets fill value writing time.
+///\return	Fill value writing time
+///\exception   H5::PropListIException
+///\par Description
+///		Valid values for fill value writing time include 
+///		\li \c H5D_FILL_TIME_NEVER 
+///		\li \c H5D_FILL_TIME_ALLOC.
+//--------------------------------------------------------------------------
+H5D_fill_time_t DSetCreatPropList::getFillTime()
+{
+   H5D_fill_time_t fill_time;
+   herr_t ret_value = H5Pget_fill_time(id, &fill_time);
+   if( ret_value < 0 )
+   {
+      throw PropListIException("DSetCreatPropList::getFillTime",
+                "H5Pget_fill_time failed");
+   }
+   else
+      return (fill_time);
+}
+
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::setAllocTime
+///\brief	Sets space allocation time for dataset during creation.
+///\param	alloc_time -  IN: Allocation time
+///\exception	H5::PropListIException
+///\par Description
+///		Valid values for space allocation time include:
+///		\li \c H5D_ALLOC_TIME_DEFAULT
+///		\li \c H5D_ALLOC_TIME_EARLY
+///		\li \c H5D_ALLOC_TIME_LATE
+///		\li \c H5D_ALLOC_TIME_INCR
+//--------------------------------------------------------------------------
+void DSetCreatPropList::setAllocTime(H5D_alloc_time_t alloc_time)
+{
+   herr_t ret_value = H5Pset_alloc_time(id, alloc_time);
+   if( ret_value < 0 )
+   {
+      throw PropListIException("DSetCreatPropList::setAllocTime",
+                "H5Pset_alloc_time failed");
+   }
+}
+
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::setFillTime
+///\brief       Sets fill value writing time for dataset.
+///\return	Fill value writing time
+///\exception   H5::PropListIException
+///\par Description
+///		Valid values for fill value writing time include 
+///		\li \c H5D_FILL_TIME_NEVER 
+///		\li \c H5D_FILL_TIME_ALLOC.
+//--------------------------------------------------------------------------
+void DSetCreatPropList::setFillTime(H5D_fill_time_t fill_time)
+{
+   herr_t ret_value = H5Pset_fill_time(id, fill_time);
+   if( ret_value < 0 )
+   {
+      throw PropListIException("DSetCreatPropList::setFillTime",
+                "H5Pset_fill_time failed");
+   }
+}
+
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::setFletcher32
+///\brief       Sets Fletcher32 checksum of EDC for this property list.
+///\exception   H5::PropListIException
+//--------------------------------------------------------------------------
+void DSetCreatPropList::setFletcher32()
+{
+   herr_t ret_value = H5Pset_fletcher32(id);
+   if( ret_value < 0 )
+   {
+      throw PropListIException("DSetCreatPropList::setFletcher32",
+                "H5Pset_fletcher32 failed");
+   }
 }
 
-// Adds an external file to the list of external files
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::setExternal
+///\brief       Adds an external file to the list of external files
+///\param	name   - IN: Name of the external file
+///\param	offset - IN: Location where the data starts in the file
+///\param	size   - IN: Number of bytes reserved in the file for the data
+///\exception   H5::PropListIException
+///\par Description
+///		If a dataset is splitted across multiple files then the files
+///             should be defined in order. The total size of the dataset is
+///             the sum of the \a size arguments for all the external files.  If
+///             the total size is larger than the size of a dataset then the
+///             dataset can be extended (provided the data space also allows
+///             the extending).
+//--------------------------------------------------------------------------
 void DSetCreatPropList::setExternal( const char* name, off_t offset, hsize_t size ) const
 {
    herr_t ret_value = H5Pset_external( id, name, offset, size );
@@ -175,7 +543,12 @@ void DSetCreatPropList::setExternal( const char* name, off_t offset, hsize_t siz
    }
 }
 
-// Returns the number of external files for a dataset 
+//--------------------------------------------------------------------------
+// Function:    DSetCreatPropList::getExternalCount
+///\brief       Returns the number of external files for a dataset
+///\return	Number of external files
+///\exception   H5::PropListIException
+//--------------------------------------------------------------------------
 int DSetCreatPropList::getExternalCount() const
 {
    int num_ext_files = H5Pget_external_count( id );
@@ -188,7 +561,27 @@ int DSetCreatPropList::getExternalCount() const
       return( num_ext_files );
 }
 
-// Returns information about an external file
+//--------------------------------------------------------------------------
+// Function:	DSetCreatPropList::getExternal
+///\brief	Returns information about an external file
+///\param	idx    - IN: Index of the external file, ranges [0-(N-1)] and
+///				returned by getExternalCount()
+///\param	name_size - IN: Maximum length of \a name
+///\param	name   - IN: Name of the external file
+///\param	offset - IN: Location to return an offset value
+///\param	size   - OUT: Location to return the size of the external file data
+///\exception   H5::PropListIException
+///\par Description
+///		The parameter \a idx ranges [0..N-1] where N is returned by
+///		getExternalCount().  At most \a name_size characters are copied 
+///		into the name array. If the external file name is longer than 
+///		name_size with the null terminator, the return value is not 
+///		null terminated (similar to strncpy()). 
+///		If \a name_size is zero or \a name is a null pointer, the 
+///		external file name will not be returned.  If \a offset or 
+///		\a size are null pointers then the corresponding information 
+///		will not be returned.
+//--------------------------------------------------------------------------
 void DSetCreatPropList::getExternal( int idx, size_t name_size, char* name, off_t& offset, hsize_t& size ) const
 {
    herr_t ret_value = H5Pget_external( id, idx, name_size, name, &offset, &size );