From 26713999ba25815466ccc8368322f340c4c45119 Mon Sep 17 00:00:00 2001 From: Binh-Minh Ribler Date: Mon, 14 Oct 2013 17:05:22 -0500 Subject: [svn-r24290] Description: - Added a lot of documentation to classes for Reference Manual. - Fixed some format inconsistencies Platforms tested: Linux/ppc64 (ostrich) Linux/32 2.6 (jam) Linux/64 2.6 (koala)/PGI compilers --- c++/src/H5AbstractDs.h | 13 ++++++++----- c++/src/H5ArrayType.h | 7 ++++--- c++/src/H5AtomType.h | 12 +++++++----- c++/src/H5Attribute.h | 8 ++++++++ c++/src/H5CommonFG.h | 11 +++++++---- c++/src/H5CompType.h | 7 ++++--- c++/src/H5CppDoc.h | 22 +++++++++++----------- c++/src/H5DataSet.h | 9 +++++++-- c++/src/H5DataSpace.h | 1 + c++/src/H5DataType.cpp | 34 ++++------------------------------ c++/src/H5DataType.h | 16 ++++++++++++---- c++/src/H5DcreatProp.h | 7 +++++++ c++/src/H5DxferProp.h | 7 +++++++ c++/src/H5EnumType.h | 1 + c++/src/H5Exception.h | 5 +++++ c++/src/H5FaccProp.h | 5 ++++- c++/src/H5FcreatProp.h | 2 +- c++/src/H5File.cpp | 28 +++++++++++++++------------- c++/src/H5File.h | 16 ++++++++++++---- c++/src/H5FloatType.h | 1 + c++/src/H5Group.cpp | 2 +- c++/src/H5Group.h | 5 +++++ c++/src/H5IdComponent.h | 7 +++++++ c++/src/H5IntType.h | 1 + c++/src/H5Library.h | 6 ++++++ c++/src/H5Location.cpp | 13 ++++++------- c++/src/H5Location.h | 17 ++++++++++------- c++/src/H5Object.h | 6 ++++++ c++/src/H5PredType.cpp | 14 ++------------ c++/src/H5PredType.h | 33 +++++++++++++++++++-------------- c++/src/H5PropList.h | 1 + c++/src/H5StrType.h | 1 + c++/src/H5VarLenType.h | 1 + 33 files changed, 192 insertions(+), 127 deletions(-) diff --git a/c++/src/H5AbstractDs.h b/c++/src/H5AbstractDs.h index e1e78e9..6904d76 100644 --- a/c++/src/H5AbstractDs.h +++ b/c++/src/H5AbstractDs.h @@ -14,11 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class AbstractDs is an abstract base class, from which Attribute and -// DataSet inherit. It provides the services that are common to both -// Attribute and DataSet. It also inherits from H5Object and passes down -// the services that H5Object provides. - #ifndef __AbstractDs_H #define __AbstractDs_H @@ -33,6 +28,14 @@ class FloatType; class IntType; class StrType; class VarLenType; + +/*! \class AbstractDs + \brief AbstractDs is an abstract base class, inherited by Attribute + and DataSet. + + It provides a collection of services that are common to both Attribute + and DataSet. AbstractDs inherits from H5Object. +*/ class H5_DLLCPP AbstractDs { public: // Gets a copy the datatype of that this abstract dataset uses. diff --git a/c++/src/H5ArrayType.h b/c++/src/H5ArrayType.h index d2e3c29..511126e 100644 --- a/c++/src/H5ArrayType.h +++ b/c++/src/H5ArrayType.h @@ -14,9 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class ArrayType inherits from DataType and provides wrappers for the -// HDF5 C's Array Datatypes. - #ifndef __H5ArrayType_H #define __H5ArrayType_H @@ -24,6 +21,10 @@ namespace H5 { #endif +/*! \class ArrayType + \brief Class ArrayType inherits from DataType and provides wrappers for + the HDF5's Array Datatypes. +*/ class H5_DLLCPP ArrayType : public DataType { public: // Constructor that creates a new array data type based on the diff --git a/c++/src/H5AtomType.h b/c++/src/H5AtomType.h index e8d6513..792312a 100644 --- a/c++/src/H5AtomType.h +++ b/c++/src/H5AtomType.h @@ -14,11 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class AtomType is a base class, from which IntType, FloatType, StrType, -// and PredType inherit. It provides the services that are common to these -// subclasses. It also inherits from DataType and passes down the -// services that are common to all the datatypes. - #ifndef __H5AtomType_H #define __H5AtomType_H @@ -26,6 +21,13 @@ namespace H5 { #endif +/*! \class AtomType + \brief AtomType is a base class, inherited by IntType, FloatType, + StrType, and PredType. + + AtomType provides operations on HDF5 atomic datatypes. It also inherits + from DataType. +*/ class H5_DLLCPP AtomType : public DataType { public: // Returns the byte order of an atomic datatype. diff --git a/c++/src/H5Attribute.h b/c++/src/H5Attribute.h index f9637fd..2c1ccf7 100644 --- a/c++/src/H5Attribute.h +++ b/c++/src/H5Attribute.h @@ -21,6 +21,14 @@ namespace H5 { #endif +/*! \class Attribute + \brief Class Attribute operates on HDF5 attributes. + + An attribute has many characteristics similar to a dataset, thus both + Attribute and DataSet are derivatives of AbstractDs. Attribute also + inherits from IdComponent because an attribute is an HDF5 component that + is identified by an identifier. +*/ class H5_DLLCPP Attribute : public AbstractDs, public IdComponent { public: // Closes this attribute. diff --git a/c++/src/H5CommonFG.h b/c++/src/H5CommonFG.h index 1748d1d..3b20f5c 100644 --- a/c++/src/H5CommonFG.h +++ b/c++/src/H5CommonFG.h @@ -14,10 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// CommonFG is a protocol class. Its existence is simply to provide the -// common services that are provided by H5File and Group. The file or -// group in the context of this class is referred to as 'location'. - #ifndef __CommonFG_H #define __CommonFG_H @@ -25,10 +21,17 @@ namespace H5 { #endif +// Class forwarding class Group; class H5File; class ArrayType; class VarLenType; + +/*! \class CommonFG + \brief \i CommonFG is an abstract base class of H5File and H5Group. + + It provides common operations of H5File and H5Group. +*/ class H5_DLLCPP CommonFG { public: // Creates a new group at this location which can be a file diff --git a/c++/src/H5CompType.h b/c++/src/H5CompType.h index 16ae839..3d6a62f 100644 --- a/c++/src/H5CompType.h +++ b/c++/src/H5CompType.h @@ -14,9 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class CompType inherits from DataType and provides accesses to a compound -// datatype. - #ifndef __H5CompType_H #define __H5CompType_H @@ -24,6 +21,10 @@ namespace H5 { #endif +/*! \class CompType + \brief CompType is a derivative of a DataType and operates on HDF5 + compound datatypes. +*/ class H5_DLLCPP CompType : public DataType { public: // Default constructor diff --git a/c++/src/H5CppDoc.h b/c++/src/H5CppDoc.h index baeca64..8ab2531 100644 --- a/c++/src/H5CppDoc.h +++ b/c++/src/H5CppDoc.h @@ -37,17 +37,17 @@ * closely represent the interfaces of the HDF5 APIs, as followed: * * \verbatim - HDF5 C APIs C++ Classes - ----------- ----------- - Attribute Interface (H5A) Attribute - Datasets Interface (H5D) DataSet - Error Interface (H5E) Exception - File Interface (H5F) H5File - Group Interface (H5G) Group - Identifier Interface (H5I) IdComponent - Property List Interface (H5P) PropList and subclasses - Dataspace Interface (H5S) DataSpace - Datatype Interface (H5T) DataType and subclasses + HDF5 C APIs C++ Classes + ----------- ----------- + Attribute Interface (H5A) Attribute + Datasets Interface (H5D) DataSet + Error Interface (H5E) Exception + File Interface (H5F) H5File + Group Interface (H5G) Group + Identifier Interface (H5I) IdComponent + Property List Interface (H5P) PropList and subclasses + Dataspace Interface (H5S) DataSpace + Datatype Interface (H5T) DataType and subclasses \endverbatim * \section install_sec Installation * diff --git a/c++/src/H5DataSet.h b/c++/src/H5DataSet.h index 8fdc47e..c407727 100644 --- a/c++/src/H5DataSet.h +++ b/c++/src/H5DataSet.h @@ -14,8 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class DataSet inherits from AbstractDs and provides accesses to a dataset. - #ifndef __H5DataSet_H #define __H5DataSet_H @@ -23,6 +21,13 @@ namespace H5 { #endif +/*! \class DataSet + \brief Class DataSet operates on HDF5 datasets. + + An datasets has many characteristics similar to an attribute, thus both + Attribute and DataSet are derivatives of AbstractDs. DataSet also + inherits from H5Object because a dataset is an HDF5 object. +*/ class H5_DLLCPP DataSet : public H5Object, public AbstractDs { public: // Close this dataset. diff --git a/c++/src/H5DataSpace.h b/c++/src/H5DataSpace.h index 1ea7188..01d6f56 100644 --- a/c++/src/H5DataSpace.h +++ b/c++/src/H5DataSpace.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class DataSpace operates on HDF5 dataspaces. class H5_DLLCPP DataSpace : public IdComponent { public: // Default DataSpace objects diff --git a/c++/src/H5DataType.cpp b/c++/src/H5DataType.cpp index 3d147c6..9e5b76e 100644 --- a/c++/src/H5DataType.cpp +++ b/c++/src/H5DataType.cpp @@ -95,7 +95,7 @@ DataType::DataType( const H5T_class_t type_class, size_t size ) : H5Object() // Function: DataType overload constructor - dereference ///\brief Given a reference, ref, to an hdf5 group, creates a /// DataType object -///\param h5file - IN: Location referenced object is in +///\param loc - IN: Location referenced object is in ///\param ref - IN: Reference pointer ///\param ref_type - IN: Reference type - default to H5R_OBJECT ///\exception H5::ReferenceException @@ -259,38 +259,12 @@ void DataType::p_commit(hid_t loc_id, const char* name) // Function: DataType::commit ///\brief Commits a transient datatype to a file, creating a new /// named datatype -///\param loc - IN: A file +///\param loc - IN: A location (file, dataset, datatype, or group) ///\param name - IN: Name of the datatype ///\exception H5::DataTypeIException // Programmer Binh-Minh Ribler - 2000 //-------------------------------------------------------------------------- -void DataType::commit(H5File& loc, const char* name) -{ - p_commit(loc.getLocId(), name); -} - -//-------------------------------------------------------------------------- -// Function: DataType::commit -///\brief This is an overloaded member function, provided for convenience. -/// It differs from the above function only in the type of the -/// argument \a name. -// Programmer Binh-Minh Ribler - 2000 -//-------------------------------------------------------------------------- -void DataType::commit(H5File& loc, const H5std_string& name) -{ - p_commit(loc.getLocId(), name.c_str()); -} - -//-------------------------------------------------------------------------- -// Function: DataType::commit -///\brief Commits a transient datatype to a file, creating a new -/// named datatype -///\param loc - IN: Either a group, dataset, named datatype, or attribute. -///\param name - IN: Name of the datatype -///\exception H5::DataTypeIException -// Programmer Binh-Minh Ribler - Jan, 2007 -//-------------------------------------------------------------------------- -void DataType::commit(H5Object& loc, const char* name) +void DataType::commit(H5Location& loc, const char* name) { p_commit(loc.getId(), name); } @@ -302,7 +276,7 @@ void DataType::commit(H5Object& loc, const char* name) /// argument \a name. // Programmer Binh-Minh Ribler - 2000 //-------------------------------------------------------------------------- -void DataType::commit(H5Object& loc, const H5std_string& name) +void DataType::commit(H5Location& loc, const H5std_string& name) { p_commit(loc.getId(), name.c_str()); } diff --git a/c++/src/H5DataType.h b/c++/src/H5DataType.h index 4071a2c..ca04548 100644 --- a/c++/src/H5DataType.h +++ b/c++/src/H5DataType.h @@ -14,6 +14,9 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +// Class DataType inherits from H5Object and has several subclasses for +// specific HDF5 data types. + #ifndef __H5DataType_H #define __H5DataType_H @@ -21,6 +24,13 @@ namespace H5 { #endif +/*! \class DataType + \brief Class DataType provides generic operations on HDF5 datatypes. + + DataType inherits from H5Object because a named datatype is an HDF5 + object and is a base class of ArrayType, AtomType, CompType, EnumType, + and VarLenType. +*/ class H5_DLLCPP DataType : public H5Object { public: // Creates a datatype given its class and size @@ -47,10 +57,8 @@ class H5_DLLCPP DataType : public H5Object { // Commits a transient datatype to a file; this datatype becomes // a named datatype which can be accessed from the location. - void commit( H5File& loc, const char* name); - void commit( H5File& loc, const H5std_string& name); - void commit( H5Object& loc, const char* name); - void commit( H5Object& loc, const H5std_string& name); + void commit( H5Location& loc, const char* name); + void commit( H5Location& loc, const H5std_string& name); // Determines whether this datatype is a named datatype or // a transient datatype. diff --git a/c++/src/H5DcreatProp.h b/c++/src/H5DcreatProp.h index 385bc61..c643ace 100644 --- a/c++/src/H5DcreatProp.h +++ b/c++/src/H5DcreatProp.h @@ -14,6 +14,9 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +// Class DSetCreatPropList represents the HDF5 dataset creation property list +// and inherits from PropList. + #ifndef __H5DSCreatPropList_H #define __H5DSCreatPropList_H @@ -21,6 +24,10 @@ namespace H5 { #endif +/*! \class DSetCreatPropList + \brief Class DSetCreatPropList represents the dataset creation property + list. +*/ class H5_DLLCPP DSetCreatPropList : public PropList { public: // Default dataset creation property list. diff --git a/c++/src/H5DxferProp.h b/c++/src/H5DxferProp.h index 723603c..846082d 100644 --- a/c++/src/H5DxferProp.h +++ b/c++/src/H5DxferProp.h @@ -14,6 +14,9 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +// Class DSetMemXferPropList represents the HDF5 dataset transfer property list +// and inherits from PropList. + #ifndef __H5DSetMemXferPropList_H #define __H5DSetMemXferPropList_H @@ -21,6 +24,10 @@ namespace H5 { #endif +/*! \class DSetMemXferPropList + \brief Class DSetMemXferPropList represents the dataset memory and + transfer property list. +*/ class H5_DLLCPP DSetMemXferPropList : public PropList { public: static const DSetMemXferPropList DEFAULT; diff --git a/c++/src/H5EnumType.h b/c++/src/H5EnumType.h index 71e36c3..fe36e8b 100644 --- a/c++/src/H5EnumType.h +++ b/c++/src/H5EnumType.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class EnumType operates on HDF5 enum datatypes. class H5_DLLCPP EnumType : public DataType { public: diff --git a/c++/src/H5Exception.h b/c++/src/H5Exception.h index 8b12abc..ee6496e 100644 --- a/c++/src/H5Exception.h +++ b/c++/src/H5Exception.h @@ -28,6 +28,11 @@ namespace H5 { #endif #endif +/*! \class Exception + \brief Exception provides wrappers of HDF5 error handling functions. + + Many classes are derived from Exception for specific HDF5 C interfaces. +*/ class H5_DLLCPP Exception { public: // Creates an exception with a function name where the failure occurs diff --git a/c++/src/H5FaccProp.h b/c++/src/H5FaccProp.h index 040b3e9..4688440 100644 --- a/c++/src/H5FaccProp.h +++ b/c++/src/H5FaccProp.h @@ -14,6 +14,9 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +// Class FileAccPropList represents the HDF5 file access property list and +// inherits from DataType. + #ifndef __H5FileAccPropList_H #define __H5FileAccPropList_H @@ -21,7 +24,7 @@ namespace H5 { #endif -// class for file access properties +//! Class FileAccPropList represents the HDF5 file access property list. class H5_DLLCPP FileAccPropList : public PropList { public: static const FileAccPropList DEFAULT; diff --git a/c++/src/H5FcreatProp.h b/c++/src/H5FcreatProp.h index de7d414..4149880 100644 --- a/c++/src/H5FcreatProp.h +++ b/c++/src/H5FcreatProp.h @@ -21,7 +21,7 @@ namespace H5 { #endif -// class for file access properties +//! Class FileCreatPropList represents the HDF5 file create property list. class H5_DLLCPP FileCreatPropList : public PropList { public: // Default file creation property list. diff --git a/c++/src/H5File.cpp b/c++/src/H5File.cpp index 48c3513..0b319cb 100644 --- a/c++/src/H5File.cpp +++ b/c++/src/H5File.cpp @@ -274,19 +274,6 @@ void H5File::reOpen() } //-------------------------------------------------------------------------- -// Function: H5File::reopen -// Purpose: Reopens this file. -// Exception H5::FileIException -// Description -// This function is replaced by the above function reOpen. -// Programmer Binh-Minh Ribler - 2000 -//-------------------------------------------------------------------------- -void H5File::reopen() -{ - H5File::reOpen(); -} - -//-------------------------------------------------------------------------- // Function: H5File::getCreatePlist ///\brief Returns the creation property list of this file ///\return FileCreatPropList object @@ -505,6 +492,20 @@ hsize_t H5File::getFileSize() const return (file_size); } +#ifndef DOXYGEN_SHOULD_SKIP_THIS +//-------------------------------------------------------------------------- +// Function: H5File::reopen +// Purpose: Reopens this file. +// Exception H5::FileIException +// Description +// This function is replaced by the above function reOpen. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void H5File::reopen() +{ + H5File::reOpen(); +} + //-------------------------------------------------------------------------- // Function: H5File::getLocId // Purpose: Get the id of this file @@ -517,6 +518,7 @@ hid_t H5File::getLocId() const { return( getId() ); } +#endif // DOXYGEN_SHOULD_SKIP_THIS //-------------------------------------------------------------------------- // Function: H5File::getId diff --git a/c++/src/H5File.h b/c++/src/H5File.h index 830dda0..06b4fec 100644 --- a/c++/src/H5File.h +++ b/c++/src/H5File.h @@ -21,6 +21,11 @@ namespace H5 { #endif +/*! \class H5File + \brief Class H5File represents an HDF5 file. + + It inherits from H5Location and CommonFG. +*/ class H5_DLLCPP H5File : public H5Location, public CommonFG { public: // Creates or opens an HDF5 file. @@ -71,7 +76,13 @@ class H5_DLLCPP H5File : public H5Location, public CommonFG { // Reopens this file. void reOpen(); // added for better name - void reopen(); +#ifndef DOXYGEN_SHOULD_SKIP_THIS + void reopen(); // obsolete in favor of reOpen() + + // Gets the file id + virtual hid_t getLocId() const; + +#endif // DOXYGEN_SHOULD_SKIP_THIS ///\brief Returns this class name. virtual H5std_string fromClass () const { return("H5File"); } @@ -79,9 +90,6 @@ class H5_DLLCPP H5File : public H5Location, public CommonFG { // Throw file exception. virtual void throwException(const H5std_string& func_name, const H5std_string& msg) const; - // Gets the file id - virtual hid_t getLocId() const; - // Default constructor H5File(); diff --git a/c++/src/H5FloatType.h b/c++/src/H5FloatType.h index 13074ba..4d5de17 100644 --- a/c++/src/H5FloatType.h +++ b/c++/src/H5FloatType.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class FloatType operates on HDF5 floating point datatype. class H5_DLLCPP FloatType : public AtomType { public: // Creates a floating-point type using a predefined type. diff --git a/c++/src/H5Group.cpp b/c++/src/H5Group.cpp index d0231e3..38f8b9f 100644 --- a/c++/src/H5Group.cpp +++ b/c++/src/H5Group.cpp @@ -90,7 +90,7 @@ Group::Group(const hid_t existing_id) : H5Object() //-------------------------------------------------------------------------- // Function: Group overload constructor - dereference ///\brief Given a reference, ref, to an hdf5 group, creates a Group object -///\param obj - IN: Specifying location referenced object is in +///\param loc - IN: Specifying location referenced object is in ///\param ref - IN: Reference pointer ///\param ref_type - IN: Reference type - default to H5R_OBJECT ///\exception H5::ReferenceException diff --git a/c++/src/H5Group.h b/c++/src/H5Group.h index e3f1ddb..8194344 100644 --- a/c++/src/H5Group.h +++ b/c++/src/H5Group.h @@ -21,6 +21,11 @@ namespace H5 { #endif +/*! \class Group + \brief Class Group represents an HDF5 group. + + It inherits many operations from H5Location and CommonFG. +*/ class H5_DLLCPP Group : public H5Object, public CommonFG { public: // Close this group. diff --git a/c++/src/H5IdComponent.h b/c++/src/H5IdComponent.h index 5a61947..6877cb6 100644 --- a/c++/src/H5IdComponent.h +++ b/c++/src/H5IdComponent.h @@ -24,6 +24,13 @@ namespace H5 { #endif class DataSpace; +/*! \class IdComponent + \brief Class IdComponent provides wrappers of the C functions that + operate on an HDF5 identifier. + + In most cases, the C library handles these operations and an application + rarely needs them. +*/ class H5_DLLCPP IdComponent { public: // Increment reference counter. diff --git a/c++/src/H5IntType.h b/c++/src/H5IntType.h index 02efb64..95fa642 100644 --- a/c++/src/H5IntType.h +++ b/c++/src/H5IntType.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class IntType operates on HDF5 integer datatype. class H5_DLLCPP IntType : public AtomType { public: // Creates a integer type using a predefined type diff --git a/c++/src/H5Library.h b/c++/src/H5Library.h index c92a943..e5365f9 100644 --- a/c++/src/H5Library.h +++ b/c++/src/H5Library.h @@ -29,6 +29,12 @@ namespace H5 { // calling H5close #endif // DOXYGEN_SHOULD_SKIP_THIS +/*! \class H5Library + \brief Class H5Library operates the HDF5 library globably. + + It is not neccessary to construct an instance of H5Library to use the + methods. +*/ class H5_DLLCPP H5Library { public: #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/c++/src/H5Location.cpp b/c++/src/H5Location.cpp index 19e9e04..88c56ee 100644 --- a/c++/src/H5Location.cpp +++ b/c++/src/H5Location.cpp @@ -567,7 +567,7 @@ void H5Location::p_reference(void* ref, const char* name, hid_t space_id, H5R_ty /// \li \c H5R_DATASET_REGION - Reference is a dataset region /// reference. (default) ///\exception H5::ReferenceException -///\notes This method is more suitable for a dataset region reference. +///\note This method is more suitable for a dataset region reference. // Programmer Binh-Minh Ribler - May, 2004 //-------------------------------------------------------------------------- void H5Location::reference(void* ref, const char* name, const DataSpace& dataspace, H5R_type_t ref_type) const @@ -593,7 +593,7 @@ void H5Location::reference(void* ref, const char* name, const DataSpace& dataspa /// \li \c H5R_DATASET_REGION - Reference is a dataset region /// reference. (default) ///\exception H5::ReferenceException -///\notes This method is more suitable for a dataset region reference. +///\note This method is more suitable for a dataset region reference. // Programmer Binh-Minh Ribler - May, 2004 //-------------------------------------------------------------------------- void H5Location::reference(void* ref, const H5std_string& name, const DataSpace& dataspace, H5R_type_t ref_type) const @@ -617,7 +617,7 @@ void H5Location::reference(void* ref, const H5std_string& name, const DataSpace& /// \li \c H5R_OBJECT - Reference is an object reference (default) /// \li \c H5R_DATASET_REGION - Reference is a dataset region ///\exception H5::ReferenceException -///\notes This method is more suitable for an object reference. +///\note This method is more suitable for an object reference. // Programmer Binh-Minh Ribler - May, 2004 //-------------------------------------------------------------------------- void H5Location::reference(void* ref, const char* name, H5R_type_t ref_type) const @@ -640,7 +640,7 @@ void H5Location::reference(void* ref, const char* name, H5R_type_t ref_type) con ///\param ref_type - IN: Type of reference to query, valid values are: /// \li \c H5R_OBJECT - Reference is an object reference (default) /// \li \c H5R_DATASET_REGION - Reference is a dataset region -///\notes This method is more suitable for an object reference. +///\note This method is more suitable for an object reference. // Programmer Binh-Minh Ribler - May, 2004 //-------------------------------------------------------------------------- void H5Location::reference(void* ref, const H5std_string& name, H5R_type_t ref_type) const @@ -678,7 +678,7 @@ hid_t H5Location::p_dereference(hid_t loc_id, const void* ref, H5R_type_t ref_ty //-------------------------------------------------------------------------- // Function: H5Location::dereference ///\brief Dereferences a reference into an HDF5 object, given an HDF5 object. -///\param obj - IN: Object specifying the location of the referenced object +///\param loc - IN: Location of the referenced object ///\param ref - IN: Reference pointer ///\param ref_type - IN: Reference type ///\exception H5::ReferenceException @@ -823,6 +823,7 @@ H5O_type_t H5Location::p_get_ref_obj_type(void *ref, H5R_type_t ref_type) const return(obj_type); } +#endif // DOXYGEN_SHOULD_SKIP_THIS //-------------------------------------------------------------------------- // Function: H5Location::getRegion @@ -858,8 +859,6 @@ DataSpace H5Location::getRegion(void *ref, H5R_type_t ref_type) const //-------------------------------------------------------------------------- H5Location::~H5Location() {} -#endif // DOXYGEN_SHOULD_SKIP_THIS - #ifndef H5_NO_NAMESPACE } // end namespace #endif diff --git a/c++/src/H5Location.h b/c++/src/H5Location.h index 3aadd50..db22bff 100644 --- a/c++/src/H5Location.h +++ b/c++/src/H5Location.h @@ -19,10 +19,6 @@ #include "H5Classes.h" // constains forward class declarations -// H5Location is an abstract class. It provides a collection of wrappers -// of C functions which take location IDs. Most of these were in H5Object -// but are now moved here for H5File's access. - #ifndef H5_NO_NAMESPACE namespace H5 { #endif @@ -41,8 +37,15 @@ class UserData4Aiterate { // user data for attribute iteration H5Location* location; }; -// An H5Location can be a file, group, dataset, or committed datatype. +/*! \class H5Location + \brief H5Location is an abstract base class, added in version 1.8.12. + It provides a collection of wrappers for the C functions that take a + location identifier to specify the HDF5 object. The location identifier + can be either file, group, dataset, or named datatype. +*/ +// Most of these methods were in H5Object but are now moved here because +// a location can be a file, group, dataset, or named datatype. -BMR, 2013-10-1 class H5_DLLCPP H5Location : public IdComponent { public: // Creates an attribute for the specified object at this location @@ -154,11 +157,11 @@ class H5_DLLCPP H5Location : public IdComponent { // Retrieves the type of object that an object reference points to. H5O_type_t p_get_ref_obj_type(void *ref, H5R_type_t ref_type) const; +#endif // DOXYGEN_SHOULD_SKIP_THIS + // Noop destructor. virtual ~H5Location(); -#endif // DOXYGEN_SHOULD_SKIP_THIS - }; /* end class H5Location */ #ifndef H5_NO_NAMESPACE diff --git a/c++/src/H5Object.h b/c++/src/H5Object.h index 3f9c343..5c2ef98 100644 --- a/c++/src/H5Object.h +++ b/c++/src/H5Object.h @@ -38,6 +38,12 @@ namespace H5 { #endif +/*! \class H5Object + \brief Class H5Object is a bridge between H5Location and DataSet, DataType, + and Group. + + All the wrappers in H5Object were moved to H5Location. +*/ class H5_DLLCPP H5Object : public H5Location { public: #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/c++/src/H5PredType.cpp b/c++/src/H5PredType.cpp index 27cfd3a..6dbee98 100644 --- a/c++/src/H5PredType.cpp +++ b/c++/src/H5PredType.cpp @@ -272,22 +272,12 @@ PredType& PredType::operator=( const PredType& rhs ) #ifndef DOXYGEN_SHOULD_SKIP_THIS // These dummy functions do not inherit from DataType - they'll // throw an DataTypeIException if invoked. -void PredType::commit( H5File& loc, const char* name ) +void PredType::commit(H5Location& loc, const char* name ) { throw DataTypeIException("PredType::commit", "Error: Attempted to commit a predefined datatype. Invalid operation!" ); } -void PredType::commit( H5File& loc, const H5std_string& name ) -{ - commit( loc, name.c_str()); -} - -void PredType::commit( H5Object& loc, const char* name ) -{ - throw DataTypeIException("PredType::commit", "Error: Attempted to commit a predefined datatype. Invalid operation!" ); -} - -void PredType::commit( H5Object& loc, const H5std_string& name ) +void PredType::commit(H5Location& loc, const H5std_string& name ) { commit( loc, name.c_str()); } diff --git a/c++/src/H5PredType.h b/c++/src/H5PredType.h index 65e1c07..c929a70 100644 --- a/c++/src/H5PredType.h +++ b/c++/src/H5PredType.h @@ -14,11 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// PredType holds the definition of all the HDF5 predefined datatypes. -// These types can only be made copy of, not created by H5Tcreate or -// closed by H5Tclose. They are treated as constants. -///////////////////////////////////////////////////////////////////// - #ifndef __H5PredType_H #define __H5PredType_H @@ -36,6 +31,13 @@ namespace H5 { #define H5CPP_EXITED -3 // -3 is less likely to be used elsewhere #endif // DOXYGEN_SHOULD_SKIP_THIS +/*! \class PredType + \brief Class PredType holds the definition of all the HDF5 predefined + datatypes. + + These types can only be made copy of, not created by H5Tcreate or + closed by H5Tclose. They are treated as constants. +*/ class H5_DLLCPP PredType : public AtomType { public: ///\brief Returns this class name. @@ -228,16 +230,20 @@ class H5_DLLCPP PredType : public AtomType { static const PredType NATIVE_UINT_FAST64; #endif /* H5_SIZEOF_UINT_FAST64_T */ -#ifndef DOXYGEN_SHOULD_SKIP_THIS - // These dummy functions do not inherit from DataType - they'll - // throw a DataTypeIException if invoked. - void commit( H5File& loc, const H5std_string& name ); - void commit( H5File& loc, const char* name ); - void commit( H5Object& loc, const H5std_string& name ); - void commit( H5Object& loc, const char* name ); + /*! \brief This dummy function do not inherit from DataType - it will + throw a DataTypeIException if invoked. + */ + void commit(H5Location& loc, const H5std_string& name ); + /*! \brief This dummy function do not inherit from DataType - it will + throw a DataTypeIException if invoked. + */ + void commit(H5Location& loc, const char* name ); + /*! \brief This dummy function do not inherit from DataType - it will + throw a DataTypeIException if invoked. + */ bool committed(); -#endif // DOXYGEN_SHOULD_SKIP_THIS +#ifndef DOXYGEN_SHOULD_SKIP_THIS private: // Added this to work around the atexit/global destructor problem. // It'll help to terminate the library after other PredType instances @@ -245,7 +251,6 @@ class H5_DLLCPP PredType : public AtomType { static const PredType AtExit; protected: -#ifndef DOXYGEN_SHOULD_SKIP_THIS // Default constructor PredType(); diff --git a/c++/src/H5PropList.h b/c++/src/H5PropList.h index b2c50d4..f26201d 100644 --- a/c++/src/H5PropList.h +++ b/c++/src/H5PropList.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class PropList provides operations for generic property lists. class H5_DLLCPP PropList : public IdComponent { public: // Default property list diff --git a/c++/src/H5StrType.h b/c++/src/H5StrType.h index 251b0b8..8b3a773 100644 --- a/c++/src/H5StrType.h +++ b/c++/src/H5StrType.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class StrType operates on HDF5 string datatypes. class H5_DLLCPP StrType : public AtomType { public: // Creates a string type using a predefined type diff --git a/c++/src/H5VarLenType.h b/c++/src/H5VarLenType.h index caa347a..9ad2b40 100644 --- a/c++/src/H5VarLenType.h +++ b/c++/src/H5VarLenType.h @@ -24,6 +24,7 @@ namespace H5 { #endif +//! VarLenType operates on the HDF5 C's Variable-length Datatypes. class H5_DLLCPP VarLenType : public DataType { public: // Constructor that creates a variable-length datatype based -- cgit v0.12