philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation clean-up

Browse Source 
Description:
    - Rearranged public/non-public functions relative to the
      DOXYGEN_SHOULD_SKIP_THIS blocks to display them correctly in the RM
    - Moved internal comments outside of the \brief blocks so they will
      not be displayed in the RM
    - Updated RELEASE.txt about the changes in PR#466
Platforms tested:
    Verified document on Windows 10.
    Linux/64 (platypus)
    Darwin (osx1010test)
This commit is contained in:
Binh-Minh Ribler
2017-04-26 00:10:24 -05:00
parent 4bc55bbf94
commit 89f9d69d8d
29 changed files with 137 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
c++/src/H5ArrayType.h
View File

@@ -20,9 +20,8 @@ namespace H5 {
/*! \class ArrayType
\brief Class ArrayType inherits from DataType and provides wrappers for
the HDF5's Array Datatypes.
Inheritance: DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP ArrayType : public DataType {
public:
// Constructor that creates a new array data type based on the

6
c++/src/H5AtomType.h
View File

@@ -20,12 +20,8 @@ namespace H5 {
/*! \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.
Inheritance: DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP AtomType : public DataType {
public:
// Returns the byte order of an atomic datatype.

3
c++/src/H5Attribute.h
View File

@@ -24,9 +24,8 @@ namespace H5 {
Attribute and DataSet are derivatives of AbstractDs. Attribute also
inherits from H5Location because an attribute can be used to specify
a location.
Inheritance: multiple H5Location/AbstractDs -> IdComponent
*/
// Inheritance: multiple H5Location/AbstractDs -> IdComponent
class H5_DLLCPP Attribute : public AbstractDs, public H5Location {
public:

5
c++/src/H5CommonFG.h
View File

@@ -24,9 +24,8 @@ class ArrayType;
class VarLenType;
/*! \class CommonFG
\brief \a CommonFG is an abstract base class of H5File and H5Group.
It provides common operations of H5File and H5Group.
\brief CommonFG will be deprecated in future releases.
In 1.10.1, most member functions are moved to H5Location.
*/
class H5_DLLCPP CommonFG {
public:

3
c++/src/H5CompType.h
View File

@@ -20,9 +20,8 @@ namespace H5 {
/*! \class CompType
\brief CompType is a derivative of a DataType and operates on HDF5
compound datatypes.
Inheritance: DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP CompType : public DataType {
public:
// Default constructor

5
c++/src/H5DataSet.h
View File

@@ -20,12 +20,11 @@ namespace H5 {
/*! \class DataSet
\brief Class DataSet operates on HDF5 datasets.
An datasets has many characteristics similar to an attribute, thus both
A dataset 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.
Inheritance: multiple H5Object/AbstractDs -> H5Location -> IdComponent
*/
// Inheritance: multiple H5Object/AbstractDs -> H5Location -> IdComponent
class H5_DLLCPP DataSet : public H5Object, public AbstractDs {
public:

2
c++/src/H5DataSpace.h
View File

@@ -20,8 +20,6 @@ namespace H5 {
/*! \class DataSpace
\brief Class DataSpace inherits from IdComponent and provides wrappers for
the HDF5's dataspaces.
Inheritance: IdComponent
*/
class H5_DLLCPP DataSpace : public IdComponent {
public:

5
c++/src/H5DataType.h
View File

@@ -21,11 +21,10 @@ namespace H5 {
\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,
object, and is a base class of ArrayType, AtomType, CompType, EnumType,
and VarLenType.
Inheritance: DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP DataType : public H5Object {
public:
// Creates a datatype given its class and size

4
c++/src/H5DcreatProp.h
View File

@@ -17,15 +17,15 @@
namespace H5 {
// Class forwarding
class DataType;
class DataSpace;
/*! \class DSetCreatPropList
\brief Class DSetCreatPropList inherits from ObjCreatPropList and provides
wrappers for the HDF5 dataset creation property functions.
Inheritance: ObjCreatPropList -> PropList -> IdComponent
*/
// Inheritance: ObjCreatPropList -> PropList -> IdComponent
class H5_DLLCPP DSetCreatPropList : public ObjCreatPropList {
public:
///\brief Default dataset creation property list.

3
c++/src/H5DxferProp.h
View File

@@ -20,9 +20,8 @@ namespace H5 {
/*! \class DSetMemXferPropList
\brief Class DSetCreatPropList inherits from PropList and provides
wrappers for the HDF5 dataset memory and transfer property list.
Inheritance: ObjCreatPropList -> PropList -> IdComponent
*/
// Inheritance: PropList -> IdComponent
class H5_DLLCPP DSetMemXferPropList : public PropList {
public:
///\brief Default dataset memory and transfer property list.

6
c++/src/H5EnumType.h
View File

@@ -18,13 +18,11 @@
namespace H5 {
/*! \class EnumType
\brief EnumType is a derivative of a DataType and operates on HDF5
\brief EnumType is derived from a DataType and operates on HDF5
enum datatypes.
Inheritance: DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP EnumType : public DataType {
public:
// Creates an empty enumeration datatype based on a native signed
// integer type, whose size is given by size.

3
c++/src/H5FaccProp.h
View File

@@ -20,9 +20,8 @@ namespace H5 {
/*! \class FileAccPropList
\brief Class FileAccPropList inherits from PropList and provides
wrappers for the HDF5 file access property list.
Inheritance: PropList -> IdComponent
*/
// Inheritance: PropList -> IdComponent
class H5_DLLCPP FileAccPropList : public PropList {
public:
///\brief Default file access property list.

3
c++/src/H5FcreatProp.h
View File

@@ -20,9 +20,8 @@ namespace H5 {
/*! \class FileCreatPropList
\brief Class FileCreatPropList inherits from PropList and provides
wrappers for the HDF5 file create property list.
Inheritance: PropList -> IdComponent
*/
// Inheritance: PropList -> IdComponent
class H5_DLLCPP FileCreatPropList : public PropList {
public:
///\brief Default file creation property list.

3
c++/src/H5File.h
View File

@@ -20,9 +20,8 @@ namespace H5 {
/*! \class H5File
\brief Class H5File represents an HDF5 file and inherits from class Group
as file is a root group.
Inheritance: Group -> CommonFG/H5Object -> H5Location -> IdComponent
*/
// Inheritance: Group -> CommonFG/H5Object -> H5Location -> IdComponent
class H5_DLLCPP H5File : public Group {
public:
// Creates or opens an HDF5 file.

3
c++/src/H5FloatType.h
View File

@@ -20,9 +20,8 @@ namespace H5 {
/*! \class FloatType
\brief FloatType is a derivative of a DataType and operates on HDF5
floating point datatype.
Inheritance: AtomType -> DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: AtomType -> DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP FloatType : public AtomType {
public:
// Creates a floating-point type using a predefined type.

1
c++/src/H5Group.cpp
View File

@@ -102,6 +102,7 @@ hid_t Group::getObjId(const H5std_string& obj_name, const PropList& plist) const
//--------------------------------------------------------------------------
// Function: Group::closeObjId
///\brief Closes an object, which was opened with Group::getObjId
///
///\exception H5::FileIException or H5::GroupIException
// Programmer Binh-Minh Ribler - March, 2017
//--------------------------------------------------------------------------

3
c++/src/H5Group.h
View File

@@ -19,13 +19,12 @@ namespace H5 {
/*! \class Group
\brief Class Group represents an HDF5 group.
Inheritance: H5Object -> H5Location -> IdComponent
*/
// Class forwarding
class ArrayType;
class VarLenType;
// Inheritance: CommonFG/H5Object -> IdComponent
class H5_DLLCPP Group : public H5Object, public CommonFG {
public:
// Close this group.

5
c++/src/H5IntType.h
View File

@@ -18,11 +18,10 @@
namespace H5 {
/*! \class IntType
\brief IntType is a derivative of a DataType and operates on HDF5
\brief IntType is derived from a DataType and operates on HDF5
integer datatype.
Inheritance: AtomType -> DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: AtomType -> DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP IntType : public AtomType {
public:
// Creates an integer type using a predefined type

3
c++/src/H5LaccProp.h
View File

@@ -23,9 +23,8 @@ namespace H5 {
/*! \class LinkAccPropList
\brief Class LinkAccPropList inherits from PropList and provides
wrappers for the HDF5 file access property list.
Inheritance: PropList -> IdComponent
*/
// Inheritance: PropList -> IdComponent
class H5_DLLCPP LinkAccPropList : public PropList {
public:
///\brief Default file access property list.

189
c++/src/H5Location.cpp
View File

@@ -373,6 +373,38 @@ void H5Location::p_reference(void* ref, const char* name, hid_t space_id, H5R_ty
}
}
//--------------------------------------------------------------------------
// Function: H5Location::p_dereference (protected)
// Purpose Dereference a ref into an hdf5 object.
// Parameters
// loc_id - IN: An hdf5 identifier specifying the location of the
// referenced object
// ref - IN: Reference pointer
// ref_type - IN: Reference type
// plist - IN: Property list - default to PropList::DEFAULT
// from_func - IN: Name of the calling function
// Exception H5::ReferenceException
// Programmer Binh-Minh Ribler - Oct, 2006
// Modification
// May 2008 - BMR
// Moved from IdComponent.
//--------------------------------------------------------------------------
hid_t H5Location::p_dereference(hid_t loc_id, const void* ref, H5R_type_t ref_type, const PropList& plist, const char* from_func)
{
hid_t plist_id;
if (p_valid_id(plist.getId()))
plist_id = plist.getId();
else
plist_id = H5P_DEFAULT;
hid_t temp_id = H5Rdereference2(loc_id, plist_id, ref_type, ref);
if (temp_id < 0)
{
throw ReferenceException(inMemFunc(from_func), "H5Rdereference failed");
}
return(temp_id);
}
#endif // DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
@@ -467,41 +499,6 @@ void H5Location::reference(void* ref, const H5std_string& name, H5R_type_t ref_t
reference(ref, name.c_str(), ref_type);
}
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
// Function: H5Location::p_dereference (protected)
// Purpose Dereference a ref into an hdf5 object.
// Parameters
// loc_id - IN: An hdf5 identifier specifying the location of the
// referenced object
// ref - IN: Reference pointer
// ref_type - IN: Reference type
// plist - IN: Property list - default to PropList::DEFAULT
// from_func - IN: Name of the calling function
// Exception H5::ReferenceException
// Programmer Binh-Minh Ribler - Oct, 2006
// Modification
// May 2008 - BMR
// Moved from IdComponent.
//--------------------------------------------------------------------------
hid_t H5Location::p_dereference(hid_t loc_id, const void* ref, H5R_type_t ref_type, const PropList& plist, const char* from_func)
{
hid_t plist_id;
if (p_valid_id(plist.getId()))
plist_id = plist.getId();
else
plist_id = H5P_DEFAULT;
hid_t temp_id = H5Rdereference2(loc_id, plist_id, ref_type, ref);
if (temp_id < 0)
{
throw ReferenceException(inMemFunc(from_func), "H5Rdereference failed");
}
return(temp_id);
}
#endif // DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
// Function: H5Location::dereference
///\brief Dereferences a reference into an HDF5 object, given an HDF5 object.
@@ -542,64 +539,6 @@ void H5Location::dereference(const H5Location& loc, const void* ref, H5R_type_t
}
*/
#ifndef H5_NO_DEPRECATED_SYMBOLS
//--------------------------------------------------------------------------
// Function: H5Location::getObjType
///\brief Retrieves the type of object that an object reference points to.
///\param ref_type - IN: Type of reference to query, valid values are:
/// \li \c H5R_OBJECT - Reference is an object reference.
/// \li \c H5R_DATASET_REGION - Reference is a dataset region reference.
///\param ref - IN: Reference to query
///\return An object type, which can be one of the following:
/// \li \c H5G_UNKNOWN - A failure occurs. (-1)
/// \li \c H5G_GROUP - Object is a group.
/// \li \c H5G_DATASET - Object is a dataset.
/// \li \c H5G_TYPE Object - is a named datatype
/// \li \c H5G_LINK - Object is a symbolic link.
/// \li \c H5G_UDLINK - Object is a user-defined link.
///\exception H5::ReferenceException
// Programmer Binh-Minh Ribler - May, 2004
// Modification
// Sep 2012: Moved up from H5File, Group, DataSet, and DataType
//--------------------------------------------------------------------------
H5G_obj_t H5Location::getObjType(void *ref, H5R_type_t ref_type) const
{
try {
return(p_get_obj_type(ref, ref_type));
}
catch (ReferenceException& E) {
throw ReferenceException(inMemFunc("getObjType"), E.getDetailMsg());
}
}
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
// Function: H5Location::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_UNKNOWN \tFailure occurs (-1)
// H5G_GROUP \tObject is a group.
// H5G_DATASET \tObject is a dataset.
// H5G_TYPE Object \tis a named datatype.
// H5G_LINK \tObject is a symbolic link.
// H5G_UDLINK \tObject is a user-defined link.
// Exception H5::ReferenceException
// Programmer Binh-Minh Ribler - May, 2004
//--------------------------------------------------------------------------
H5G_obj_t H5Location::p_get_obj_type(void *ref, H5R_type_t ref_type) const
{
H5G_obj_t obj_type = H5Rget_obj_type1(getId(), ref_type, ref);
if (obj_type == H5G_UNKNOWN)
{
throw ReferenceException(inMemFunc("getObjType"), "H5Rget_obj_type1 failed");
}
return(obj_type);
}
#endif // DOXYGEN_SHOULD_SKIP_THIS
#endif /* H5_NO_DEPRECATED_SYMBOLS */
//--------------------------------------------------------------------------
// Function: H5Location::getRefObjType
@@ -657,7 +596,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
@@ -1564,7 +1503,35 @@ unsigned H5Location::childObjVersion(const H5std_string& objname) const
}
#ifndef H5_NO_DEPRECATED_SYMBOLS
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
// Function: H5Location::getObjType
///\brief Retrieves the type of object that an object reference points to.
///\param ref_type - IN: Type of reference to query, valid values are:
/// \li \c H5R_OBJECT - Reference is an object reference.
/// \li \c H5R_DATASET_REGION - Reference is a dataset region reference.
///\param ref - IN: Reference to query
///\return An object type, which can be one of the following:
/// \li \c H5G_UNKNOWN - A failure occurs. (-1)
/// \li \c H5G_GROUP - Object is a group.
/// \li \c H5G_DATASET - Object is a dataset.
/// \li \c H5G_TYPE Object - is a named datatype
/// \li \c H5G_LINK - Object is a symbolic link.
/// \li \c H5G_UDLINK - Object is a user-defined link.
///\exception H5::ReferenceException
// Programmer Binh-Minh Ribler - May, 2004
// Modification
// Sep 2012: Moved up from H5File, Group, DataSet, and DataType
//--------------------------------------------------------------------------
H5G_obj_t H5Location::getObjType(void *ref, H5R_type_t ref_type) const
{
try {
return(p_get_obj_type(ref, ref_type));
}
catch (ReferenceException& E) {
throw ReferenceException(inMemFunc("getObjType"), E.getDetailMsg());
}
}
//--------------------------------------------------------------------------
// Function: H5Location::getObjTypeByIdx
///\brief Returns the type of an object in this group, given the
@@ -1632,9 +1599,37 @@ H5G_obj_t H5Location::getObjTypeByIdx(hsize_t idx, H5std_string& type_name) cons
return (obj_type);
}
#endif // DOXYGEN_SHOULD_SKIP_THIS
#endif /* H5_NO_DEPRECATED_SYMBOLS */
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
// Function: H5Location::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_UNKNOWN \tFailure occurs (-1)
// H5G_GROUP \tObject is a group.
// H5G_DATASET \tObject is a dataset.
// H5G_TYPE Object \tis a named datatype.
// H5G_LINK \tObject is a symbolic link.
// H5G_UDLINK \tObject is a user-defined link.
// Exception H5::ReferenceException
// Programmer Binh-Minh Ribler - May, 2004
//--------------------------------------------------------------------------
H5G_obj_t H5Location::p_get_obj_type(void *ref, H5R_type_t ref_type) const
{
H5G_obj_t obj_type = H5Rget_obj_type1(getId(), ref_type, ref);
if (obj_type == H5G_UNKNOWN)
{
throw ReferenceException(inMemFunc("getObjType"), "H5Rget_obj_type1 failed");
}
return(obj_type);
}
#endif // DOXYGEN_SHOULD_SKIP_THIS
#endif // H5_NO_DEPRECATED_SYMBOLS
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
// Function: H5Location::throwException
///\brief Invokes subclass' throwException

4
c++/src/H5Location.h
View File

@@ -26,13 +26,13 @@ namespace H5 {
location identifier to specify the HDF5 object. The location identifier
can be either file, group, dataset, attribute, or named datatype.
Wrappers for H5A functions stay in H5Object.
Inheritance: IdComponent
*/
// Class forwarding
class ArrayType;
class LinkAccPropList;
class VarLenType;
// Inheritance: IdComponent
class H5_DLLCPP H5Location : public IdComponent {
public:
// Checks if a link of a given name exists in a location

4
c++/src/H5Object.cpp
View File

@@ -98,7 +98,7 @@ void f_Attribute_setId(Attribute* attr, hid_t new_id)
{
attr->p_setId(new_id);
}
#endif
#endif // DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
// Function: H5Object::createAttribute
@@ -373,7 +373,6 @@ void H5Object::renameAttr(const H5std_string& oldname, const H5std_string& newna
renameAttr (oldname.c_str(), newname.c_str());
}
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
// Function: getObjName
///\brief Given an id, returns the type of the object.
@@ -485,6 +484,7 @@ ssize_t H5Object::getObjName(H5std_string& obj_name, size_t len) const
return(name_size);
}
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//--------------------------------------------------------------------------
// Function: H5Object destructor
///\brief Noop destructor.

6
c++/src/H5Object.h
View File

@@ -20,7 +20,8 @@ namespace H5 {
/*! \class H5Object
\brief Class H5Object is a bridge between H5Location and DataSet, DataType,
and Group.
*/
/*
Modification:
Sept 18, 2012: Added class H5Location in between IdComponent and
H5Object. An H5File now inherits from H5Location. All HDF5
@@ -36,8 +37,6 @@ namespace H5 {
into H5Object. This way, C functions that takes attribute id
can be in H5Location and those that cannot take attribute id
can be in H5Object.
Inheritance: H5Location -> IdComponent
*/
// Class forwarding
class H5Object;
@@ -56,6 +55,7 @@ class UserData4Aiterate {
H5Object* location;
};
// Inheritance: H5Location -> IdComponent
class H5_DLLCPP H5Object : public H5Location {
public:
// Creates an attribute for the specified object

5
c++/src/H5OcreatProp.h
View File

@@ -19,10 +19,9 @@ namespace H5 {
/*! \class ObjCreatPropList
\brief Class ObjCreatPropList inherits from PropList and provides
wrappers for the HDF5 file create property list.
Inheritance: PropList -> IdComponent
wrappers for the HDF5 object create property list.
*/
// Inheritance: PropList -> IdComponent
class H5_DLLCPP ObjCreatPropList : public PropList {
public:
///\brief Default object creation property list.

3
c++/src/H5PredType.h
View File

@@ -23,9 +23,8 @@ namespace H5 {
These types can only be made copy of, not created by H5Tcreate or
closed by H5Tclose. They are treated as constants.
Inheritance: AtomType -> DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: AtomType -> DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP PredType : public AtomType {
public:
///\brief Returns this class name.

3
c++/src/H5PropList.h
View File

@@ -17,12 +17,9 @@
namespace H5 {
//! Class PropList provides operations for generic property lists.
/*! \class PropList
\brief Class PropList inherits from IdComponent and provides wrappers for
the HDF5 generic property list.
Inheritance: IdComponent
*/
class H5_DLLCPP PropList : public IdComponent {
public:

5
c++/src/H5StrType.h
View File

@@ -18,11 +18,10 @@
namespace H5 {
/*! \class StrType
\brief StrType is a derivative of a DataType and operates on HDF5
\brief StrType is derived from a DataType and operates on HDF5
string datatype.
Inheritance: AtomType -> DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: AtomType -> DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP StrType : public AtomType {
public:
// Creates a string type using a predefined type

5
c++/src/H5VarLenType.h
View File

@@ -18,11 +18,10 @@
namespace H5 {
/*! \class VarLenType
\brief VarLenType is a derivative of a DataType and operates on HDF5
\brief VarLenType is derived from a DataType and operates on HDF5
C's Variable-length Datatypes.
Inheritance: DataType -> H5Object -> H5Location -> IdComponent
*/
// Inheritance: DataType -> H5Object -> H5Location -> IdComponent
class H5_DLLCPP VarLenType : public DataType {
public:
// Constructor that creates a variable-length datatype based

7
release_docs/RELEASE.txt
View File

@@ -486,6 +486,13 @@ Bug Fixes since HDF5-1.10.0-patch1 release
C++ APIs
--------
- The member function H5Location::getNumObjs() is moved to
class Group because the objects are in a group or a file only,
and H5Object::getNumAttrs to H5Location to get the number of
attributes at a given location.
(BMR, 2017/03/17, PR#466)
- Due to the change in the C API, the overloaded functions of
PropList::setProperty now need const for some arguments. They are
planned for deprecation and are replaced by new versions with proper