[svn-r8593] Purpose:

    Add more C++ wrapper and documentation - incrementally check-in

Description
    Added another overloaded constructor to StrType.
    Added doxygen documentation to H5IdComponent.cpp.
    Corrected some comments.

    This is an incremental check-in to preserve the code, corresponding
    tests will follow in a few weeks.

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

Misc. update:

5 files changed, 195 insertions, 49 deletions

diff --git a/c++/src/H5DataSet.cpp b/c++/src/H5DataSet.cpp
index b8ee423..112b3fa 100644
--- a/c++/src/H5DataSet.cpp
+++ b/c++/src/H5DataSet.cpp
@@ -51,7 +51,7 @@ DataSet::DataSet() : AbstractDs() {}
 ///\param	existing_id - IN: Id of an existing dataset
 // Programmer	Binh-Minh Ribler - 2000
 //--------------------------------------------------------------------------
-DataSet::DataSet( const hid_t dataset_id ) : AbstractDs( dataset_id ) {}
+DataSet::DataSet(const hid_t existing_id) : AbstractDs(existing_id) {}
 
 //--------------------------------------------------------------------------
 // Function:	DataSet copy constructor
@@ -196,7 +196,8 @@ hsize_t DataSet::getVlenBufSize( DataType& type, DataSpace& space ) const
 //--------------------------------------------------------------------------
 // Function:	DataSet::getVlenBufSize
 ///\brief	Reclaims VL datatype memory buffers. 
-///\param	dataspace - IN: Selection for the memory buffer to free the 
+///\param	type - IN: Datatype, which is the datatype stored in the buffer
+///\param	space - IN: Selection for the memory buffer to free the 
 ///		VL datatypes within
 ///\param	xfer_plist - IN: Property list used to create the buffer
 ///\param	buf - IN: Pointer to the buffer to be reclaimed
diff --git a/c++/src/H5DataSet.h b/c++/src/H5DataSet.h
index 39640ea..6960757 100644
--- a/c++/src/H5DataSet.h
+++ b/c++/src/H5DataSet.h
@@ -79,18 +79,16 @@ class H5_DLLCPP DataSet : public AbstractDs {
 	// Retrieves a dataspace with the region pointed to selected.
 	DataSpace getRegion(void *ref, H5R_type_t ref_type = H5R_DATASET_REGION) const;
 
-	// Creates a copy of an existing DataSet using its id
-	// Note: used by CommonFG to return a DataSet; should be modified
-	// to use friend template function instead)
-	DataSet( const hid_t dataset_id );
+	// Creates a copy of an existing DataSet using its id.
+	DataSet(const hid_t existing_id);
 
-	// Used by the API to appropriately close a dataset
+	// Used by the API to appropriately close a dataset.
 	virtual void p_close() const;
 
-	// Default constructor
+	// Default constructor.
 	DataSet();
 
-	// Copy constructor
+	// Copy constructor.
 	DataSet( const DataSet& original );
 
 	virtual ~DataSet();
diff --git a/c++/src/H5IdComponent.cpp b/c++/src/H5IdComponent.cpp
index 4056dc2..a9c3520 100644
--- a/c++/src/H5IdComponent.cpp
+++ b/c++/src/H5IdComponent.cpp
@@ -25,22 +25,37 @@
 namespace H5 {
 #endif
 
-// Default constructor - private
+//--------------------------------------------------------------------------
+// Function:	IdComponent default constructor - private
+///\brief	Default constructor.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 IdComponent::IdComponent() : id( -1 )
 {
    // starts counting object references
    ref_count = new RefCounter;
 }
 
-// Constructor that takes an HDF5 object id.  It creates an instance
-// of IdComponent to hold the HDF5 id
+//--------------------------------------------------------------------------
+// Function:	IdComponent overloaded constructor
+///\brief	Creates an IdComponent object using the id of an existing object.
+///\param	h5_id - IN: Id of an existing object
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
+
 IdComponent::IdComponent( const hid_t h5_id ) : id( h5_id )
 {
    // starts counting object references
    ref_count = new RefCounter;
 }
 
-// Copy constructor: makes a copy of the original object
+//--------------------------------------------------------------------------
+// Function:	IdComponent copy constructor
+///\brief	Copy constructor: makes a copy of the original IdComponent object.
+///\param	original - IN: IdComponent instance to copy
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 IdComponent::IdComponent( const IdComponent& original )
 {
    id = original.id;
@@ -48,17 +63,36 @@ IdComponent::IdComponent( const IdComponent& original )
    ref_count->increment(); // increment number of references to this id
 }
 
-// Increment reference counter
+//--------------------------------------------------------------------------
+// Function:	IdComponent::incRefCount
+///\brief	Increment id reference counter.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void IdComponent::incRefCount() { ref_count->increment(); }
 
-// Decrement reference counter
+//--------------------------------------------------------------------------
+// Function:	IdComponent::decRefCount
+///\brief	Decrement id reference counter.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void IdComponent::decRefCount() { ref_count->decrement(); }
 
-// Get the reference counter to this identifier
+//--------------------------------------------------------------------------
+// Function:	IdComponent::getCounter
+///\brief	Returns the reference counter to this identifier.
+///\return	Reference count
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 int IdComponent::getCounter() { return( ref_count->getCounter()); }
 
-// Decrements the reference counter then determines if there are no more
-// reference to this object
+//--------------------------------------------------------------------------
+// Function:	IdComponent::noReference
+///\brief	Decrements the reference counter then determines if there 
+///		are no more reference to this object.
+///\return	true if there are no more reference to this object, and false,
+///		otherwise
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 bool IdComponent::noReference()
 {
    if( ref_count->getCounter() > 0 )
@@ -66,13 +100,20 @@ bool IdComponent::noReference()
    return( ref_count->getCounter() == 0 ? true:false );
 }
 
-/* Assignment operator.
-   Description:
-   Reset the identifier of this object so that the HDF5 id can be properly
-   closed.  Copy the new identifier to this object, then increment the 
-   reference counter of the identifier to indicate that another object 
-   is referencing the identifier.
-*/
+//--------------------------------------------------------------------------
+// Function:	IdComponent::operator=
+///\brief	Assignment operator.
+///\param	rhs - IN: Reference to the existing object
+///\return	Reference to IdComponent instance
+///\exception	H5::IdComponentException when attempt to close the HDF5
+///		object fails
+// Description
+//		Reset the identifier of this object so that the HDF5 id can 
+//		be properly closed.  Copy the id from rhs to this object, 
+//		then increment the reference counter of the id to indicate 
+//		that another object is referencing it.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 IdComponent& IdComponent::operator=( const IdComponent& rhs )
 {
    // reset the identifier of this object - resetIdComponent will call the 
@@ -93,13 +134,18 @@ IdComponent& IdComponent::operator=( const IdComponent& rhs )
    return( *this );
 }
 
-/* Sets the identifier of this object to a new value
-   Description:
-        Reset the current identifier of this object so that the HDF5
-        id can be appropriately closed.  If only this object references
-        its identifier, its reference counter will be deleted.  A new 
-        reference counter is created for the new HDF5 object id.
-*/
+//--------------------------------------------------------------------------
+// Function:	IdComponent::incRefCount
+///\brief	Sets the identifier of this object to a new value.
+///\exception	H5::IdComponentException when the attempt to close the HDF5
+///		object fails
+// Description:
+//		Reset the current id of this object so that the HDF5
+//		id can be appropriately closed.  If only this object references
+//		its id, its reference counter will be deleted.  A new 
+//		reference counter is created for the new HDF5 object id.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void IdComponent::setId( hid_t new_id )
 {
    // reset the identifier of this object, call appropriate H5Xclose
@@ -115,20 +161,33 @@ void IdComponent::setId( hid_t new_id )
    ref_count = new RefCounter;
 }
 
-// Gets the id of this object 
+//--------------------------------------------------------------------------
+// Function:	IdComponent::incRefCount
+///\brief	Returns the id of this object 
+///\return	HDF5 id
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 hid_t IdComponent::getId () const
 {
    return( id );
 }
 
-// Reset this object by deleting its RefCounter
+//--------------------------------------------------------------------------
+// Function:	IdComponent::reset
+///\brief	Reset the reference counter of this object.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void IdComponent::reset ()
 {
    delete ref_count;
    ref_count = NULL;
 }
 
-// Default destructor
+//--------------------------------------------------------------------------
+// Function:	IdComponent destructor
+///\brief	Noop destructor.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 IdComponent::~IdComponent() {
 
 /* uncomment this block and complete it when deciding to use dontAtExit 
@@ -156,7 +215,7 @@ IdComponent::~IdComponent() {
 }
 
 //
-// Implementation for HDF5 Reference Interface 
+// Implementation of protected functions for HDF5 Reference Interface.
 // 
 
 //--------------------------------------------------------------------------
diff --git a/c++/src/H5StrType.cpp b/c++/src/H5StrType.cpp
index 683fc0b..1961365 100644
--- a/c++/src/H5StrType.cpp
+++ b/c++/src/H5StrType.cpp
@@ -33,19 +33,45 @@
 namespace H5 {
 #endif
 
-// Default constructor
+//--------------------------------------------------------------------------
+// Function:	StrType default constructor
+///\brief	Default constructor: Creates a stub string datatype
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 StrType::StrType() : AtomType() {}
 
-// Creates a string type using a predefined type
+//--------------------------------------------------------------------------
+// Function:	StrType overloaded constructor
+///\brief	Creates a string datatype using a predefined type.
+///\param	pred_type - IN: Predefined datatype
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 StrType::StrType( const PredType& pred_type ) : AtomType()
 {
    // use DataType::copy to make a copy of this predefined type
    copy( pred_type );
 }
 
-// Creates a string type with a specified length - 1st argument could
-// have been skipped, but this constructor will collide with the one
-// that takes an existing id below
+//--------------------------------------------------------------------------
+// Function:	StrType overloaded constructor
+///\brief	Creates a string datatype with a specified length
+///\param	existing_id - IN: Id of an existing datatype
+///\exception	H5::DataTypeIException
+// Description
+// 		The 1st argument could have been skipped, but this 
+// 		constructor will collide with the one that takes an 
+// 		existing id.
+//
+// 		Update: by passing 'size' by reference will avoid the
+// 		clashing problem, so the 1st argument can actually be
+// 		omitted.  This constructor should be replaced by the 
+// 		other after announcing. - May, 2004
+///\note		
+///		This constructor will be obsolete in later releases,
+///		please use StrType( const size_t& size ) instead.
+// Programmer	Binh-Minh Ribler - 2000 
+//--------------------------------------------------------------------------
 StrType::StrType( const PredType& pred_type, const size_t size ) : AtomType()
 {
    // use DataType::copy to make a copy of the string predefined type
@@ -53,14 +79,37 @@ StrType::StrType( const PredType& pred_type, const size_t size ) : AtomType()
    copy(pred_type);
    setSize(size);
 }
+StrType::StrType( const size_t& size ) : AtomType()
+{
+   // use DataType::copy to make a copy of the string predefined type
+   // then set its length
+   copy(H5T_C_S1);
+   setSize(size);
+}
 
-// Creates a string datatype using an existing id
+//--------------------------------------------------------------------------
+// Function:	StrType overloaded constructor
+///\brief	Creates an StrType object using the id of an existing datatype.
+///\param	existing_id - IN: Id of an existing datatype
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 StrType::StrType( const hid_t existing_id ) : AtomType( existing_id ) {}
 
-// Copy constructor: makes copy of the original StrType object
+//--------------------------------------------------------------------------
+// Function:	StrType copy constructor
+///\brief	Copy constructor: makes a copy of the original StrType object.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 StrType::StrType( const StrType& original ) : AtomType ( original ) {}
 
-// Gets the string datatype of the specified dataset - will reimplement - BMR
+//--------------------------------------------------------------------------
+// Function:    EnumType overloaded constructor
+///\brief       Gets the string datatype of the specified dataset
+///\param       dataset - IN: Dataset that this string datatype associates with
+///\exception   H5::DataTypeIException
+// Programmer   Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 StrType::StrType( const DataSet& dataset ) : AtomType ()
 {
    // Calls C function H5Dget_type to get the id of the datatype
@@ -72,7 +121,14 @@ StrType::StrType( const DataSet& dataset ) : AtomType ()
    }
 }
 
-// Retrieves the character set type of a string datatype. 
+//--------------------------------------------------------------------------
+// Function:	StrType::getCset
+///\brief	Retrieves the character set type of this string datatype. 
+///\return	Character set type, which can be:
+///		\li \c H5T_CSET_ASCII (0) - Character set is US ASCII.
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 H5T_cset_t StrType::getCset() const
 {
    H5T_cset_t cset = H5Tget_cset( id );
@@ -85,7 +141,14 @@ H5T_cset_t StrType::getCset() const
    return( cset );
 }
 
-// Sets character set to be used. 
+//--------------------------------------------------------------------------
+// Function:	StrType::setCset
+///\brief	Sets character set to be used. 
+///\param	cset - IN: character set type
+///\exception	H5::DataTypeIException
+///		\li \c H5T_CSET_ASCII (0) - Character set is US ASCII.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void StrType::setCset( H5T_cset_t cset ) const
 {
    herr_t ret_value = H5Tset_cset( id, cset );
@@ -96,7 +159,16 @@ void StrType::setCset( H5T_cset_t cset ) const
    }
 }
 
-// Retrieves the string padding method for a string datatype. 
+//--------------------------------------------------------------------------
+// Function:	StrType::getCset
+///\brief	Retrieves the storage mechanism for of this string datatype. 
+///\return	String storage mechanism, which can be:
+///		\li \c H5T_STR_NULLTERM (0) - Null terminate (as C does)
+///		\li \c H5T_STR_NULLPAD (0) - Pad with zeros
+///		\li \c H5T_STR_SPACEPAD (0) - pad with spaces (as FORTRAN does)
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 H5T_str_t StrType::getStrpad() const
 {
    H5T_str_t strpad = H5Tget_strpad( id );
@@ -110,7 +182,16 @@ H5T_str_t StrType::getStrpad() const
    return( strpad );
 }
 
-// Defines the storage mechanism for character strings. 
+//--------------------------------------------------------------------------
+// Function:	StrType::setStrpad
+///\brief	Defines the storage mechanism for this string datatype.
+///\param	strpad - IN: String padding type
+///\exception	H5::DataTypeIException
+///\par Description
+///		For detail, please refer to the C layer Reference Manual at:
+/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5T.html#Datatype-SetStrpad
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void StrType::setStrpad( H5T_str_t strpad ) const
 {
    herr_t ret_value = H5Tset_strpad( id, strpad );
@@ -121,7 +202,11 @@ void StrType::setStrpad( H5T_str_t strpad ) const
    }
 }
 
-// This destructor terminates access to the datatype
+//--------------------------------------------------------------------------
+// Function:	StrType destructor
+///\brief	Properly terminates access to this string datatype.
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 StrType::~StrType() {}
 
 #ifndef H5_NO_NAMESPACE
diff --git a/c++/src/H5StrType.h b/c++/src/H5StrType.h
index 8d6070c..6ee6025 100644
--- a/c++/src/H5StrType.h
+++ b/c++/src/H5StrType.h
@@ -29,6 +29,9 @@ class H5_DLLCPP StrType : public AtomType {
 	StrType( const PredType& pred_type );
 
 	// Creates a string type with specified length
+	StrType( const size_t& size );
+
+	// Creates a string type with specified length - will be obsolete
 	StrType( const PredType& pred_type, const size_t size );
 
 	// Creates a string datatype using an existing id