[svn-r8595] Purpose:

    Add/Improve documentation

Description
    Added doxygen documentation to H5PredType.cpp and made minor changes
    to the others for either correction or clarification.

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

Misc. update:

1 files changed, 19 insertions, 14 deletions

diff --git a/c++/src/H5Object.cpp b/c++/src/H5Object.cpp
index 37d64a1..811ce75 100644
--- a/c++/src/H5Object.cpp
+++ b/c++/src/H5Object.cpp
@@ -187,9 +187,13 @@ Attribute H5Object::openAttribute( const unsigned int idx ) const
 ///\param	user_op - IN: User's function to operate on each attribute
 ///\param	idx - IN/OUT: Starting (IN) and ending (OUT) attribute indices
 ///\param	op_data - IN: User's data to pass to user's operator function 
-///\return	Returned value of the last operator if it was non-zero, or 
+///\return	Returned value of the last operator if it was non-zero, or
 ///		zero if all attributes were processed
 ///\exception	H5::AttributeIException
+///\par Description
+///		For information, please refer to the C layer Reference Manual
+///		at:
+/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5A.html#Annot-Iterate
 // Programmer	Binh-Minh Ribler - 2000
 //--------------------------------------------------------------------------
 int H5Object::iterateAttrs( attr_operator_t user_op, unsigned * idx, void *op_data )
@@ -284,20 +288,18 @@ void H5Object::flush(H5F_scope_t scope ) const
 
 //--------------------------------------------------------------------------
 // Function:	H5Object::Reference
-///\brief	Creates a reference to an Hdf5 object.
+///\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
-///\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* H5Object::Reference(const char* name, DataSpace& dataspace, H5R_type_t ref_type) const
 {
    void *ref;
-   herr_t ret_value = H5Rcreate(ref, id, name, H5R_OBJECT, -1);
+   herr_t ret_value = H5Rcreate(ref, id, name, ref_type, dataspace.getId());
    if (ret_value < 0)
    {
       throw AttributeIException("H5Object::Reference", 
@@ -308,18 +310,22 @@ void* H5Object::Reference(const char* name) const
 
 //--------------------------------------------------------------------------
 // Function:	H5Object::Reference
-///\brief	Creates a 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
-///\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
+///\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, DataSpace& dataspace, H5R_type_t ref_type) const
+void* H5Object::Reference(const char* name) const
 {
    void *ref;
-   herr_t ret_value = H5Rcreate(ref, id, name, ref_type, dataspace.getId());
+   herr_t ret_value = H5Rcreate(ref, id, name, H5R_OBJECT, -1);
    if (ret_value < 0)
    {
       throw AttributeIException("H5Object::Reference", 
@@ -327,7 +333,6 @@ void* H5Object::Reference(const char* name, DataSpace& dataspace, H5R_type_t ref
    }
    return(ref);
 }
-
 //--------------------------------------------------------------------------
 // Function:	H5Object destructor
 ///\brief	Noop destructor.