From 85ff720d0c889f98e05692ac02533d99d798a094 Mon Sep 17 00:00:00 2001 From: Binh-Minh Ribler Date: Thu, 20 May 2004 15:54:30 -0500 Subject: [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: --- c++/src/H5AbstractDs.cpp | 127 ++++++++++++++++++++++++++++------------------- c++/src/H5Group.cpp | 102 +++++++++++++++++++++++++++++++------ c++/src/H5IntType.cpp | 1 - 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 -- cgit v0.12