[svn-r8837] Purpose: Update doc and fix minor bug

Description:
    H5IdComponent.cpp: initialized a pointer to NULL
    H5Object.cpp: removed functions being added by mistake
    Update function headers for the rest.

Platforms tested:
    SunOS 5.7 (arabica)
    Linux 2.4 (eirene)

10 files changed, 159 insertions, 112 deletions

diff --git a/c++/src/H5DataSpace.cpp b/c++/src/H5DataSpace.cpp
index 12fb269..6a119af 100644
--- a/c++/src/H5DataSpace.cpp
+++ b/c++/src/H5DataSpace.cpp
@@ -28,6 +28,9 @@
 namespace H5 {
 #endif
 
+//--------------------------------------------------------------------------
+///\brief	Constant for default dataspace
+//--------------------------------------------------------------------------
 const DataSpace DataSpace::ALL( H5S_ALL );
 
 //--------------------------------------------------------------------------
diff --git a/c++/src/H5DcreatProp.cpp b/c++/src/H5DcreatProp.cpp
index f4150ac..2f031a6 100644
--- a/c++/src/H5DcreatProp.cpp
+++ b/c++/src/H5DcreatProp.cpp
@@ -26,6 +26,9 @@
 namespace H5 {
 #endif
 
+//--------------------------------------------------------------------------
+///\brief	Constant for default property
+//--------------------------------------------------------------------------
 const DSetCreatPropList DSetCreatPropList::DEFAULT( H5P_DEFAULT );
 
 //--------------------------------------------------------------------------
@@ -154,7 +157,7 @@ void DSetCreatPropList::setDeflate( int level ) const
 // 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
+///\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
@@ -181,7 +184,7 @@ void DSetCreatPropList::setFillValue( const DataType& fvalue_type, const void* v
 // 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
+///\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 
@@ -290,15 +293,15 @@ int DSetCreatPropList::getNfilters() 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
-///\param   filter_config - OUT: Flags indicating whether filter can encode/decode
+///\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
+///\param	filter_config - OUT: Flags indicating whether filter can encode/decode
 ///\return	Filter id
 ///\exception	H5::PropListIException
 ///\par Description
@@ -324,14 +327,14 @@ H5Z_filter_t DSetCreatPropList::getFilter(int filter_number, unsigned int &flags
 // 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
-///\param   filter_config - OUT: Flags indicating whether filter can encode/decode
+///\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
+///\param	filter_config - OUT: Flags indicating whether filter can encode/decode
 ///\exception	H5::PropListIException
 //--------------------------------------------------------------------------
 void DSetCreatPropList::getFilterById(H5Z_filter_t filter_id, unsigned int &flags, size_t &cd_nelmts,
@@ -569,12 +572,12 @@ int DSetCreatPropList::getExternalCount() const
 //--------------------------------------------------------------------------
 // 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	idx       - IN: Index of the external file, ranges [0-(N-1)] 
+///				and returned by \c 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
+///\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
diff --git a/c++/src/H5DxferProp.cpp b/c++/src/H5DxferProp.cpp
index dd4df5d..dda7ba0 100644
--- a/c++/src/H5DxferProp.cpp
+++ b/c++/src/H5DxferProp.cpp
@@ -24,6 +24,9 @@
 namespace H5 {
 #endif
 
+//--------------------------------------------------------------------------
+///\brief	Constant for default property
+//--------------------------------------------------------------------------
 const DSetMemXferPropList DSetMemXferPropList::DEFAULT( H5P_DEFAULT );
 
 //--------------------------------------------------------------------------
@@ -44,7 +47,15 @@ DSetMemXferPropList::DSetMemXferPropList() : PropList(H5P_DATASET_XFER) {}
 //--------------------------------------------------------------------------
 DSetMemXferPropList::DSetMemXferPropList( const DSetMemXferPropList& orig ) : PropList( orig ) {}
 
-// Sets type conversion and background buffers
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::setBuffer
+///\brief	Sets type conversion and background buffers.
+///\param	size  - IN: Size, in bytes, of the type conversion and background buffers
+///\param	tconv - IN: Pointer to application-allocated type conversion buffer
+///\param	bkg   - IN: Pointer to application-allocated background buffer
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void DSetMemXferPropList::setBuffer( size_t size, void* tconv, void* bkg ) const
 {
    herr_t ret_value = H5Pset_buffer( id, size, tconv, bkg );
@@ -55,7 +66,16 @@ void DSetMemXferPropList::setBuffer( size_t size, void* tconv, void* bkg ) const
    }
 }
 
-// Reads buffer settings
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::getBuffer
+///\brief	Reads buffer settings.
+///\param	tconv - IN: Pointer to application-allocated type conversion buffer
+///\param	bkg   - IN: Pointer to application-allocated background buffer
+///\return	Buffer size, in bytes
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
+
 size_t DSetMemXferPropList::getBuffer( void** tconv, void** bkg ) const
 {
    size_t buffer_size = H5Pget_buffer( id, tconv, bkg );
@@ -67,7 +87,13 @@ size_t DSetMemXferPropList::getBuffer( void** tconv, void** bkg ) const
    return( buffer_size );
 }
 
-// Sets the dataset transfer property list status to TRUE or FALSE
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::setPreserve
+///\brief	Sets the dataset transfer property list status to true or false.
+///\param	status - IN: Status to set, true or false
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void DSetMemXferPropList::setPreserve( bool status ) const
 {
    herr_t ret_value = H5Pset_preserve( id, (hbool_t) status );
@@ -78,7 +104,13 @@ void DSetMemXferPropList::setPreserve( bool status ) const
    }
 }
 
-// Checks status of the dataset transfer property list
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::getPreserve
+///\brief	Checks status of the dataset transfer property list.
+///\return	Status of the dataset transfer property list
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 bool DSetMemXferPropList::getPreserve() const
 {
    int ret_value = H5Pget_preserve( id );
@@ -93,7 +125,15 @@ bool DSetMemXferPropList::getPreserve() const
    }
 }
 
-// Sets B-tree split ratios for a dataset transfer property list 
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::setBtreeRatios
+///\brief	Sets B-tree split ratios for a dataset transfer property list.
+///\param	left   - IN: B-tree split ratio for left-most nodes
+///\param	middle - IN: B-tree split ratio for right-most nodes and lone nodes
+///\param	right  - IN: B-tree split ratio for all other nodes
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void DSetMemXferPropList::setBtreeRatios( double left, double middle, double right ) const
 {
    herr_t ret_value = H5Pset_btree_ratios( id, left, middle, right );
@@ -104,7 +144,15 @@ void DSetMemXferPropList::setBtreeRatios( double left, double middle, double rig
    }
 }
 
-// Gets B-tree split ratios for a dataset transfer property list
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::getBtreeRatios
+///\brief	Gets B-tree split ratios for a dataset transfer property list.
+///\param	left   - OUT: B-tree split ratio for left-most nodes
+///\param	middle - OUT: B-tree split ratio for right-most nodes and lone nodes
+///\param	right  - OUT: B-tree split ratio for all other nodes
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void DSetMemXferPropList::getBtreeRatios( double& left, double& middle, double& right ) const
 {
    herr_t ret_value = H5Pget_btree_ratios( id, &left, &middle, &right );
@@ -115,8 +163,15 @@ void DSetMemXferPropList::getBtreeRatios( double& left, double& middle, double&
    }
 }
 
-// Sets an exception handling callback for datatype conversion
-// for a dataset transfer property list
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::setTypeConvCB
+///\brief	Sets an exception handling callback for datatype conversion
+///		for a dataset transfer property list.
+///\param	op        - IN: User's function
+///\param	user_data - IN: User's data
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - April, 2004
+//--------------------------------------------------------------------------
 void DSetMemXferPropList::setTypeConvCB( H5T_conv_except_func_t op, void *user_data) const
 {
    herr_t ret_value = H5Pset_type_conv_cb( id, op, user_data);
@@ -127,8 +182,14 @@ void DSetMemXferPropList::setTypeConvCB( H5T_conv_except_func_t op, void *user_d
    }
 }
 
-// Sets an exception handling callback for datatype conversion
-// for a dataset transfer property list
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::getTypeConvCB
+///\brief	Gets the exception handling callback function and data.
+///\param	op        - IN: Retrieved user function
+///\param	user_data - IN: Retrieved user data
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - April, 2004
+//--------------------------------------------------------------------------
 void DSetMemXferPropList::getTypeConvCB( H5T_conv_except_func_t *op, void **user_data) const
 {
    herr_t ret_value = H5Pget_type_conv_cb( id, op, user_data);
@@ -139,7 +200,16 @@ void DSetMemXferPropList::getTypeConvCB( H5T_conv_except_func_t *op, void **user
    }
 }
 
-// Sets the memory manager for variable-length datatype allocation
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::setVlenMemManager
+///\brief	Sets the memory manager for variable-length datatype allocation.
+///\param       alloc_func - IN: User's allocate routine
+///\param	alloc_info - IN: User's allocation parameters
+///\param	free_func  - IN: User's free routine
+///\param	free_info  - IN: User's free parameters
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void DSetMemXferPropList::setVlenMemManager( H5MM_allocate_t alloc_func, void* alloc_info, H5MM_free_t free_func, void* free_info ) const
 {
    herr_t ret_value = H5Pset_vlen_mem_manager( id, alloc_func, alloc_info, 
@@ -151,20 +221,28 @@ void DSetMemXferPropList::setVlenMemManager( H5MM_allocate_t alloc_func, void* a
    }
 }
 
-// alloc_func and free_func are set to NULL, indicating that system malloc and 
-// free are to be used
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::setVlenMemManager
+///\brief	Sets the memory manager for variable-length datatype 
+///		allocation - system \c malloc and \c free will be used.
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void DSetMemXferPropList::setVlenMemManager() const
 {
    setVlenMemManager( NULL, NULL, NULL, NULL );
-   //herr_t ret_value = H5Pset_vlen_mem_manager( id, NULL, NULL, NULL, NULL );
-   //if( ret_value < 0 )
-   //{
-      //throw PropListIException("DSetMemXferPropList::setVlenMemManager",
-		//"H5Pset_vlen_mem_manager failed");
-   //}
 }
 
-// Gets the memory manager for variable-length datatype allocation 
+//--------------------------------------------------------------------------
+// Function:	DSetMemXferPropList::getVlenMemManager
+///\brief	Gets the memory manager for variable-length datatype allocation 
+///\param       alloc_func - OUT: User's allocate routine
+///\param	alloc_info - OUT: User's allocation parameters
+///\param	free_func  - OUT: User's free routine
+///\param	free_info  - OUT: User's free parameters
+///\exception	H5::PropListIException
+// Programmer:	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void DSetMemXferPropList::getVlenMemManager( H5MM_allocate_t& alloc_func, void** alloc_info, H5MM_free_t& free_func, void** free_info ) const
 {
    herr_t ret_value = H5Pget_vlen_mem_manager( id, &alloc_func, alloc_info, &free_func, free_info );
diff --git a/c++/src/H5FaccProp.cpp b/c++/src/H5FaccProp.cpp
index d2da47d..fc1e0c7 100644
--- a/c++/src/H5FaccProp.cpp
+++ b/c++/src/H5FaccProp.cpp
@@ -24,6 +24,9 @@
 namespace H5 {
 #endif
 
+//--------------------------------------------------------------------------
+///\brief	Constant for default property
+//--------------------------------------------------------------------------
 const FileAccPropList FileAccPropList::DEFAULT( H5P_DEFAULT );
 
 //--------------------------------------------------------------------------
@@ -78,7 +81,7 @@ hid_t FileAccPropList::getDriver() const
 //--------------------------------------------------------------------------
 // Function:    FileAccPropList::setDriver
 ///\brief	Set file driver for this property list
-///\param       new_driver_id   - IN: Name of property to check for
+///\param       new_driver_id   - IN: File driver
 ///\param       new_driver_info - IN: Struct containing the driver-specific properites
 ///\exception   H5::PropListIException
 ///\par Description
diff --git a/c++/src/H5FcreatProp.cpp b/c++/src/H5FcreatProp.cpp
index e6b6fb9..657b04b 100644
--- a/c++/src/H5FcreatProp.cpp
+++ b/c++/src/H5FcreatProp.cpp
@@ -231,9 +231,9 @@ unsigned FileCreatPropList::getIstorek() const
 }
 
 //--------------------------------------------------------------------------
-// Function:    FileCreatPropList destructor
-///\brief       Properly terminates access to this file creation property list.
-// Programmer   Binh-Minh Ribler - 2000
+// Function:	FileCreatPropList destructor
+///\brief	Noop destructor.
+// Programmer	Binh-Minh Ribler - 2000
 //--------------------------------------------------------------------------
 FileCreatPropList::~FileCreatPropList() {}
 
diff --git a/c++/src/H5File.cpp b/c++/src/H5File.cpp
index a39d93f..aca787a 100644
--- a/c++/src/H5File.cpp
+++ b/c++/src/H5File.cpp
@@ -484,22 +484,22 @@ hid_t H5File::getLocId() const
 
 //--------------------------------------------------------------------------
 // Function:	H5File::getFileSize
-///\brief	Retrieves the file size of the HDF5 file. This function 
-///             is called after an existing file is opened in order
-///		to learn the true size of the underlying file.
+///\brief	Retrieves the file size of the HDF5 file.
 ///\exception	H5::FileIException
+///\return	File size
+///\par Description
+///		This function is called after an existing file is opened in 
+///		order to learn the true size of the underlying file.
 // Programmer   Raymond Lu - June 24, 2004
 //--------------------------------------------------------------------------
 haddr_t H5File::getFileSize(void) const
 {
-   herr_t ret;
-   
-   ret = H5Fget_filesize(id, size);
-   if( ret < 0 )
+   haddr_t file_size = H5Fget_filesize(id);
+   if( file_size < 0 )
    {
       throw FileIException("H5File::getFileSize", "H5Fget_filesize failed");
    }
-   return ret;
+   return(file_size);
 }
 
 //--------------------------------------------------------------------------
diff --git a/c++/src/H5File.h b/c++/src/H5File.h
index d688e6f..a6f40dd 100644
--- a/c++/src/H5File.h
+++ b/c++/src/H5File.h
@@ -73,23 +73,24 @@ class H5_DLLCPP H5File : public IdComponent, public CommonFG {
 	DataSpace getRegion(void *ref, H5R_type_t ref_type = H5R_DATASET_REGION) const;
 
         // Retrieves the file size of an opened file.
-        herr_t getFileSize(hsize_t *size) const;
+        haddr_t getFileSize() const;
 
-	// Reopens this file
+	// Reopens this file.
 	void reopen();
 
-	// Gets the creation property list of this file
+	// Gets the creation property list of this file.
 	FileCreatPropList getCreatePlist() const;
 
-	// Gets the access property list of this file
+	// Gets the access property list of this file.
 	FileAccPropList getAccessPlist() const;
 
-	// Throw file exception
+	// Throw file exception.
 	virtual void throwException(const string func_name, const string msg) const;
 
-	// Used by the API to appropriately close a file
+	// Used by the API to appropriately close a file.
 	void p_close() const;
 
+	// H5File destructor.
 	virtual ~H5File();
 
    private:
diff --git a/c++/src/H5IdComponent.cpp b/c++/src/H5IdComponent.cpp
index f04039b..7ccb7ff 100644
--- a/c++/src/H5IdComponent.cpp
+++ b/c++/src/H5IdComponent.cpp
@@ -190,7 +190,7 @@ IdComponent::~IdComponent() {
 //--------------------------------------------------------------------------
 void* IdComponent::p_reference(const char* name, hid_t space_id, H5R_type_t ref_type) const
 {
-   void *ref;
+   void *ref=NULL;
    herr_t ret_value = H5Rcreate(ref, id, name, ref_type, space_id);
    if (ret_value < 0)
    {
diff --git a/c++/src/H5Object.cpp b/c++/src/H5Object.cpp
index 5050f9d..1d6fd95 100644
--- a/c++/src/H5Object.cpp
+++ b/c++/src/H5Object.cpp
@@ -285,53 +285,6 @@ void H5Object::flush(H5F_scope_t scope ) const
 }
 
 //--------------------------------------------------------------------------
-// Function:	H5Object::Reference
-///\brief	Creates a reference to an Hdf5 object or to a dataset region.
-///\param	name - IN: Name of the object to be referenced
-///\param	dataspace - IN: Dataspace with selection
-///\param	ref_type - IN: Type of reference; default to \c H5R_DATASET_REGION
-///\return	A reference
-///\exception	H5::ReferenceIException
-// Programmer	Binh-Minh Ribler - May, 2004
-//--------------------------------------------------------------------------
-void* H5Object::Reference(const char* name, DataSpace& dataspace, H5R_type_t ref_type) const
-{
-   void *ref;
-   herr_t ret_value = H5Rcreate(ref, id, name, ref_type, dataspace.getId());
-   if (ret_value < 0)
-   {
-      throw AttributeIException("H5Object::Reference", 
-		"H5Rcreate failed");
-   }
-   return(ref);
-}
-
-//--------------------------------------------------------------------------
-// Function:	H5Object::Reference
-///\brief       This is an overloaded function, provided for your convenience.
-///             It differs from the above function in that it only creates
-///             a reference to an Hdf5 object, not to a dataset region.
-///\param	name - IN: Name of the object to be referenced
-///\return	A reference
-///\exception	H5::ReferenceIException
-///\par Description
-//		This function passes H5R_OBJECT and -1 to the C API H5Rcreate
-//		to create a reference to the named object.  The next function
-//		will create a reference to a dataset region.
-// Programmer	Binh-Minh Ribler - May, 2004
-//--------------------------------------------------------------------------
-void* H5Object::Reference(const char* name) const
-{
-   void *ref;
-   herr_t ret_value = H5Rcreate(ref, id, name, H5R_OBJECT, -1);
-   if (ret_value < 0)
-   {
-      throw AttributeIException("H5Object::Reference", 
-		"H5Rcreate failed");
-   }
-   return(ref);
-}
-//--------------------------------------------------------------------------
 // Function:	H5Object destructor
 ///\brief	Noop destructor.
 // Programmer	Binh-Minh Ribler - 2000
diff --git a/c++/src/H5PropList.cpp b/c++/src/H5PropList.cpp
index 8cc06bf..110ce6d 100644
--- a/c++/src/H5PropList.cpp
+++ b/c++/src/H5PropList.cpp
@@ -28,6 +28,9 @@
 namespace H5 {
 #endif
 
+//--------------------------------------------------------------------------
+///\brief	Constant for default property
+//--------------------------------------------------------------------------
 const PropList PropList::DEFAULT( H5P_DEFAULT );
 
 //--------------------------------------------------------------------------
@@ -559,8 +562,11 @@ PropList PropList::getClassParent() const
    return(pclass);
 }
 
-// The destructor of this instance calls the template resetIdComponent to
-// reset its identifier
+//--------------------------------------------------------------------------
+// Function:	PropList destructor
+///\brief	Properly terminates access to this property list.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 PropList::~PropList()
 {  
    // The property list id will be closed properly