[svn-r8744] Purpose:

    Add documentation with doxygen

Platforms:
    Linux 2.4 (eirene)
    I need to check in these files now to prevent loss of effort, but
        will check out and test on 2 more platforms asap.

1 files changed, 147 insertions, 25 deletions

diff --git a/c++/src/H5IdComponent.cpp b/c++/src/H5IdComponent.cpp
index 3140836..503fc2e 100644
--- a/c++/src/H5IdComponent.cpp
+++ b/c++/src/H5IdComponent.cpp
@@ -1,7 +1,7 @@
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
   * Copyright by the Board of Trustees of the University of Illinois.         *
-  * All rights reserved.                                                      *
-  *                                                                           *
+  * All rights reserved.		                                        *
+  *		                                                             *
   * This file is part of HDF5.  The full HDF5 copyright notice, including     *
   * terms governing use, modification, and redistribution, is contained in    *
   * the files COPYING and Copyright.html.  COPYING can be found at the root   *
@@ -25,22 +25,36 @@
 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,13 +62,26 @@ 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
@@ -66,13 +93,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 +127,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::setId
+///\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,7 +154,12 @@ void IdComponent::setId( hid_t new_id )
    ref_count = new RefCounter;
 }
 
-// Gets the id of this object 
+//--------------------------------------------------------------------------
+// Function:	IdComponent::getId
+///\brief	Returns the id of this object
+///\return	HDF5 id
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 hid_t IdComponent::getId () const
 {
    return( id );
@@ -128,7 +172,11 @@ void IdComponent::reset ()
    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 
@@ -155,6 +203,80 @@ IdComponent::~IdComponent() {
 */
 }
 
+//
+// Implementation of protected functions for HDF5 Reference Interface.
+// 
+
+//--------------------------------------------------------------------------
+// Function:	IdComponent::p_reference (protected)
+// Purpose	Creates a reference to an HDF5 object or a dataset region.
+// Parameters
+//		name - IN: Name of the object to be referenced
+//		dataspace - IN: Dataspace with selection
+//		ref_type - IN: Type of reference; default to \c H5R_DATASET_REGION
+// Return	A reference
+// Exception	H5::IdComponentException
+// Programmer	Binh-Minh Ribler - May, 2004
+//--------------------------------------------------------------------------
+void* IdComponent::p_reference(const char* name, hid_t space_id, H5R_type_t ref_type) const
+{
+   void *ref;
+   herr_t ret_value = H5Rcreate(ref, id, name, ref_type, space_id);
+   if (ret_value < 0)
+   {
+      throw IdComponentException("IdComponent::p_reference",
+		  "H5Rcreate failed");
+   }
+   return(ref);
+}
+
+//--------------------------------------------------------------------------
+// Function:	IdComponent::p_get_obj_type (protected)
+// Purpose	Retrieves the type of object that an object reference points to.
+// Parameters
+//		ref      - IN: Reference to query
+//		ref_type - IN: Type of reference to query
+// Return	An object type, which can be one of the following:
+//			H5G_LINK Object is a symbolic link.  
+//			H5G_GROUP Object is a group.  
+//			H5G_DATASET   Object is a dataset.  
+//			H5G_TYPE Object is a named datatype 
+// Exception	H5::IdComponentException
+// Programmer	Binh-Minh Ribler - May, 2004
+//--------------------------------------------------------------------------
+H5G_obj_t IdComponent::p_get_obj_type(void *ref, H5R_type_t ref_type) const
+{
+   H5G_obj_t obj_type = H5Rget_obj_type(id, ref_type, ref);
+   if (obj_type == H5G_UNKNOWN)
+   {
+      throw IdComponentException("IdComponent::p_get_obj_type",
+		  "H5R_get_obj_type failed");
+   }
+   return(obj_type);
+}
+
+//--------------------------------------------------------------------------
+// Function:	IdComponent::p_get_region (protected)
+// Purpose	Retrieves a dataspace with the region pointed to selected.
+// Parameters
+//		ref_type - IN: Type of reference to get region of - default
+//				to H5R_DATASET_REGION
+//		ref      - IN: Reference to get region of
+// Return	Dataspace id
+// Exception	H5::IdComponentException
+// Programmer	Binh-Minh Ribler - May, 2004
+//--------------------------------------------------------------------------
+hid_t IdComponent::p_get_region(void *ref, H5R_type_t ref_type) const
+{
+   hid_t space_id = H5Rget_region(id, ref_type, ref);
+   if (space_id < 0)
+   {
+      throw IdComponentException("IdComponent::p_get_region",
+		  "H5Rget_region failed");
+   }
+   return(space_id);
+}
+
 #ifndef H5_NO_NAMESPACE
 }
 #endif