[svn-r8555] Purpose:

    Add documentation

Description:
    Added doxygen documentation and removed incorrect comments.

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

Misc. update:

3 files changed, 163 insertions, 67 deletions

diff --git a/c++/src/H5AbstractDs.cpp b/c++/src/H5AbstractDs.cpp
index d677237..108a847 100644
--- a/c++/src/H5AbstractDs.cpp
+++ b/c++/src/H5AbstractDs.cpp
@@ -27,17 +27,35 @@
 namespace H5 {
 #endif
 
-// Default constructor
+//--------------------------------------------------------------------------
+// Function:	AbstractDs default constructor
+///\brief	Default constructor
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 AbstractDs::AbstractDs() : H5Object() {}
 
-// Constructor that takes an id
+//--------------------------------------------------------------------------
+// Function:	AbstractDs default constructor
+///\brief	Creates an AbstractDs instance using an existing id.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 AbstractDs::AbstractDs( const hid_t ds_id ) : H5Object( ds_id ) {}
 
-// Copy constructor: makes copy of the original object; simply invokes
-// base-class copy constructor.
+//--------------------------------------------------------------------------
+// Function:	AbstractDs copy constructor
+///\brief	Copy constructor: makes a copy of the original AbstractDs object.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 AbstractDs::AbstractDs( const AbstractDs& original ) : H5Object( original ) {}
 
-// Returns the class of the datatype that is used by this dataset
+//--------------------------------------------------------------------------
+// Function:	AbstractDs::getTypeClass
+///\brief	Returns the class of the datatype that is used by this 
+///		object, which can be a dataset or an attribute.
+///\return      Datatype class identifier
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 H5T_class_t AbstractDs::getTypeClass() const
 {
    // Gets the datatype used by this dataset or attribute.
@@ -52,12 +70,18 @@ H5T_class_t AbstractDs::getTypeClass() const
    else
    {
       throw DataTypeIException("AbstractDs::getTypeClass", 
-		"H5Tget_class returns something different than H5T_NO_CLASS");
+		"H5Tget_class returns H5T_NO_CLASS");
    }
 }
 
-// Returns the generic datatype of this abstract dataset which 
-// can be a dataset or an attribute.
+//--------------------------------------------------------------------------
+// Function:	AbstractDs::getDataType
+///\brief	Returns the generic datatype of this abstract dataset, which
+///		can be a dataset or an attribute.
+///\return      DataType instance
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 DataType AbstractDs::getDataType() const
 {
    // Gets the id of the datatype used by this dataset or attribute.
@@ -70,79 +94,82 @@ DataType AbstractDs::getDataType() const
    return( datatype );
 }
 
-// Returns the enumeration datatype of this abstract dataset which 
 // can be a dataset or an attribute.
+//--------------------------------------------------------------------------
+// Function:	AbstractDs::getEnumType
+///\brief	Returns the enumeration datatype of this abstract dataset which 
+///		can be a dataset or an attribute.
+///\return      EnumType instance
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 EnumType AbstractDs::getEnumType() const
 {
    EnumType enumtype( p_getType());
    return( enumtype );
 }
 
-// Returns the compound datatype of this abstract dataset which 
-// can be a dataset or an attribute.
+//--------------------------------------------------------------------------
+// Function:	AbstractDs::getCompType
+///\brief	Returns the compound datatype of this abstract dataset which 
+///		can be a dataset or an attribute.
+///\return      CompType instance
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 CompType AbstractDs::getCompType() const
 {
    CompType comptype( p_getType());
    return( comptype );
 }
 
-// Returns the integer datatype of this abstract dataset which 
-// can be a dataset or an attribute.
+//--------------------------------------------------------------------------
+// Function:	AbstractDs::getIntType
+///\brief	Returns the integer datatype of this abstract dataset which 
+///		can be a dataset or an attribute.
+///\return      IntType instance
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 IntType AbstractDs::getIntType() const
 {
    IntType inttype( p_getType());
    return( inttype );
 }
 
-// Returns the floating-point datatype of this abstract dataset which 
-// can be a dataset or an attribute.
+//--------------------------------------------------------------------------
+// Function:	AbstractDs::getFloatType
+///\brief	Returns the floating-point datatype of this abstract dataset,
+///		which can be a dataset or an attribute.
+///\return      FloatType instance
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 FloatType AbstractDs::getFloatType() const
 {
    FloatType floatype( p_getType());
    return( floatype );
 }
 
-// Returns the string datatype of this abstract dataset which 
-// can be a dataset or an attribute.
+//--------------------------------------------------------------------------
+// Function:	AbstractDs::getStrType
+///\brief	Returns the string datatype of this abstract dataset which 
+///		can be a dataset or an attribute.
+///\return      StrType instance
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 StrType AbstractDs::getStrType() const
 {
    StrType strtype( p_getType());
    return( strtype );
 }
 
-/* This version of getDataType is older style.  New style above doesn't
-use overloading.  Remove it when knowing for sure that the other way
-is prefered
-// Gets the specific datatype of this abstract dataset which can be a 
-// dataset or an attribute.  Several overloaded getDataType's below
-// are for specific sub-datatypes.
-void AbstractDs::getDataType( EnumType& enumtype ) const
-{
-   enumtype.setId( p_getType());
-}
-
-void AbstractDs::getDataType( CompType& comptype ) const
-{
-   comptype.setId( p_getType());
-}
-
-void AbstractDs::getDataType( IntType& inttype ) const
-{
-   inttype.setId( p_getType());
-}
-
-void AbstractDs::getDataType( FloatType& floatype ) const
-{
-   floatype.setId( p_getType());
-}
-
-void AbstractDs::getDataType( StrType& strtype ) const
-{
-   strtype.setId( p_getType());
-}
-end of old style of getDataType */
-
-// Default destructor
+//--------------------------------------------------------------------------
+// Function:	StrType destructor
+///\brief	Default destructor
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 AbstractDs::~AbstractDs() {}
 
 #ifndef H5_NO_NAMESPACE
diff --git a/c++/src/H5Group.cpp b/c++/src/H5Group.cpp
index 03dca68..4530dba 100644
--- a/c++/src/H5Group.cpp
+++ b/c++/src/H5Group.cpp
@@ -42,23 +42,47 @@
 namespace H5 {
 #endif
 
-// Default constructor
+//--------------------------------------------------------------------------
+// Function:	Group default constructor
+///\brief	Default constructor: Creates a stub group
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 Group::Group() : H5Object() {}
 
-// Copy constructor: makes a copy of the original Group object 
+//--------------------------------------------------------------------------
+// Function:	Group copy constructor
+///\brief	Copy constructor: makes a copy of the original Group object.
+///\param	original - IN: Original group to copy
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 Group::Group( const Group& original ) : H5Object( original ) {}
 
-// Get id of the location, which id the group id here; used by CommonFG
-// member functions
+//--------------------------------------------------------------------------
+// Function:	Group::getLocId
+///\brief	Returns the id of this group.
+///\return	Id of this group
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 hid_t Group::getLocId() const
 {
    return( getId() );
 }
 
-// Creates a copy of an existing Group using its id
+//--------------------------------------------------------------------------
+// Function:	Group overloaded constructor
+///\brief	Creates a Group object using the id of an existing group.
+///\param	group_id - IN: Id of an existing group
+///\exception	H5::GroupIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 Group::Group( const hid_t group_id ) : H5Object( group_id ) {}
 
-// Returns the number of objects in the group.
+//--------------------------------------------------------------------------
+// Function:	Group::getNumObjs
+///\brief	Returns the number of objects in this group.
+///\exception	H5::GroupIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 hsize_t Group::getNumObjs() const
 {
    hsize_t num_objs;
@@ -70,7 +94,14 @@ hsize_t Group::getNumObjs() const
    return (num_objs);
 }
 
-// Retrieves the name of an object in a given group by giving index
+//--------------------------------------------------------------------------
+// Function:	Group::getObjnameByIdx
+///\brief	Retrieves the name of an object in this group by giving the
+///		object's index.
+///\return	Object name
+///\exception	H5::GroupIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 ssize_t Group::getObjnameByIdx(hsize_t idx, string& name, size_t size) const
 {
    char* name_C = new char[size];
@@ -84,7 +115,14 @@ ssize_t Group::getObjnameByIdx(hsize_t idx, string& name, size_t size) const
    return (name_len);
 }
 
-// Returns the type of an object in a given group by giving index
+//--------------------------------------------------------------------------
+// Function:	Group::getObjTypeByIdx
+///\brief	Returns the type of an object in this group by giving the
+///		object's index.
+///\return	Object type
+///\exception	H5::GroupIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 int Group::getObjTypeByIdx(hsize_t idx) const
 {
    int obj_type = H5Gget_objtype_by_idx(id, idx);
@@ -94,6 +132,18 @@ int Group::getObjTypeByIdx(hsize_t idx) const
    }
    return (obj_type);
 }
+
+//--------------------------------------------------------------------------
+// Function:	Group::getObjTypeByIdx
+///\brief	This is an overloaded member function, provided for convenience.
+///		It differs from the above function because it also provides 
+///		the returned object type in text.
+///\param	idx - IN: Index of the object
+///\param	type_name - IN: Object type in text
+///\return	Object type
+///\exception	H5::GroupIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 int Group::getObjTypeByIdx(hsize_t idx, string& type_name) const
 {
    int obj_type = H5Gget_objtype_by_idx(id, idx);
@@ -127,7 +177,15 @@ int Group::getObjTypeByIdx(hsize_t idx, string& type_name) const
    //}
 //}
 
-// Calls the C API H5Gclose to close this group.  Used by IdComponent::reset
+//--------------------------------------------------------------------------
+// Function:	Group::p_close (private)
+///\brief	Closes this group.
+///\exception   H5::GroupIException
+///\note
+///		This function will be obsolete because its functionality 
+///		is recently handled by the C library layer.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void Group::p_close() const
 {
    herr_t ret_value = H5Gclose( id );
@@ -137,7 +195,20 @@ void Group::p_close() const
    }
 }
 
-// Throw file exception
+//--------------------------------------------------------------------------
+// Function:	Group::throwException
+///\brief	Throws group exception - initially implemented for CommonFG
+///\param	func_name - Name of the function where failure occurs
+///\param	msg       - Message describing the failure
+///\exception	H5::GroupIException
+// Description
+//		This function is used in CommonFG implementation so that
+//		proper exception can be thrown for file or group.  The
+//		argument func_name is a member of CommonFG and "Group::"
+//		will be inserted to indicate the function called is an
+//		implementation of Group.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void Group::throwException(const string func_name, const string msg) const
 {
    string full_name = func_name;
@@ -145,11 +216,11 @@ void Group::throwException(const string func_name, const string msg) const
    throw GroupIException(full_name, msg);
 }
 
-// The destructor of this instance calls IdComponent::reset to
-// reset its identifier - no longer true
-// Older compilers (baldric) don't support template member functions
-// and IdComponent::reset is one; so at this time, the resetId is not
-// a member function so it can be template to work around that problem.
+//--------------------------------------------------------------------------
+// Function:	Group destructor
+///\brief	Properly terminates access to this group.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 Group::~Group()
 {  
    // The group id will be closed properly
@@ -158,7 +229,6 @@ Group::~Group()
     catch (Exception close_error) { // thrown by p_close
         cerr << "Group::~Group - " << close_error.getDetailMsg() << endl;
     }
-
 }  
 
 #ifndef H5_NO_NAMESPACE
diff --git a/c++/src/H5IntType.cpp b/c++/src/H5IntType.cpp
index dc27904..7dcd891 100644
--- a/c++/src/H5IntType.cpp
+++ b/c++/src/H5IntType.cpp
@@ -92,7 +92,6 @@ IntType::IntType( const DataSet& dataset ) : AtomType()
 //--------------------------------------------------------------------------
 // Function:	IntType::getSign
 ///\brief	Retrieves the sign type for an integer type.
-///\param	dataset - IN: Dataset that this integer datatype associates with
 ///\return	Valid sign type
 ///\exception	H5::DataTypeIException
 // Programmer	Binh-Minh Ribler - 2000