[svn-r24291] 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

33 files changed, 210 insertions, 186 deletions

diff --git a/c++/src/H5AbstractDs.h b/c++/src/H5AbstractDs.h
index 6635f78..01d05b8 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 2d01205..dbfbbb2 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.
@@ -74,8 +82,10 @@ class H5_DLLCPP Attribute : public AbstractDs, public IdComponent {
 	virtual ~Attribute();
 
    protected:
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 	// Sets the attribute id.
 	virtual void p_setId(const hid_t new_id);
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
    private:
 	hid_t id;	// HDF5 attribute id
diff --git a/c++/src/H5CommonFG.h b/c++/src/H5CommonFG.h
index 1748d1d..2f10e8e 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
 
@@ -29,6 +25,12 @@ 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..f3ed040 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 a3a6a76..92c651c 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.
@@ -98,6 +103,12 @@ class H5_DLLCPP DataSet : public H5Object, public AbstractDs {
 	// Destructor: properly terminates access to this dataset.
 	virtual ~DataSet();
 
+   protected:
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+        // Sets the dataset id.
+        virtual void p_setId(const hid_t new_id);
+#endif // DOXYGEN_SHOULD_SKIP_THIS
+
    private:
 	hid_t id;       // HDF5 dataset id
 
@@ -110,12 +121,6 @@ class H5_DLLCPP DataSet : public H5Object, public AbstractDs {
 	// Reads variable or fixed len strings from this dataset.
 	void p_read_fixed_len(const hid_t mem_type_id, const hid_t mem_space_id, const hid_t file_space_id, const hid_t xfer_plist_id, H5std_string& strg) const;
 	void p_read_variable_len(const hid_t mem_type_id, const hid_t mem_space_id, const hid_t file_space_id, const hid_t xfer_plist_id, H5std_string& strg) const;
-
-   protected:
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
-        // Sets the dataset id.
-        virtual void p_setId(const hid_t new_id);
-#endif // DOXYGEN_SHOULD_SKIP_THIS
 };
 #ifndef H5_NO_NAMESPACE
 }
diff --git a/c++/src/H5DataSpace.h b/c++/src/H5DataSpace.h
index 1ea7188..05ee70c 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
@@ -118,15 +119,14 @@ class H5_DLLCPP DataSpace : public IdComponent {
 	// Destructor: properly terminates access to this dataspace.
 	virtual ~DataSpace();
 
-   private:
-	hid_t id;       // HDF5 dataspace id
-
    protected:
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 	// Sets the dataspace id.
 	virtual void p_setId(const hid_t new_id);
 #endif // DOXYGEN_SHOULD_SKIP_THIS
 
+   private:
+	hid_t id;       // HDF5 dataspace id
 };
 #ifndef H5_NO_NAMESPACE
 }
diff --git a/c++/src/H5DataType.cpp b/c++/src/H5DataType.cpp
index be05623..00aa5f4 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
@@ -106,8 +106,6 @@ DataType::DataType( const H5T_class_t type_class, size_t size ) : H5Object()
 //--------------------------------------------------------------------------
 DataType::DataType(const H5Location& loc, const void* ref, H5R_type_t ref_type, const PropList& plist) : H5Object(), id(0)
 {
- /*     H5Location::dereference(loc, ref, ref_type, plist);
- */ 
     id = H5Location::p_dereference(loc.getId(), ref, ref_type, plist, "constructor - by dereference");
 }
 
@@ -127,13 +125,6 @@ DataType::DataType(const H5Location& loc, const void* ref, H5R_type_t ref_type,
 DataType::DataType(const Attribute& attr, const void* ref, H5R_type_t ref_type, const PropList& plist) : H5Object(), id(0)
 {
     id = H5Location::p_dereference(attr.getId(), ref, ref_type, plist, "constructor - by dereference");
-     /* try {
-	id = p_dereference(attr.getId(), ref, ref_type, plist);
-    } catch (ReferenceException deref_error) {
-	throw ReferenceException("DataType constructor - located by an Attribute",
-		deref_error.getDetailMsg());
-    }
- */ 
 }
 
 //--------------------------------------------------------------------------
@@ -268,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	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	loc - IN: A location (file, dataset, datatype, or group)
 ///\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);
 }
@@ -311,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 104eed4..c5c8a7d 100644
--- a/c++/src/H5DataType.h
+++ b/c++/src/H5DataType.h
@@ -21,6 +21,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 +54,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..7434b9b 100644
--- a/c++/src/H5DcreatProp.h
+++ b/c++/src/H5DcreatProp.h
@@ -21,6 +21,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 b136ba4..3c2a616 100644
--- a/c++/src/H5DxferProp.h
+++ b/c++/src/H5DxferProp.h
@@ -21,6 +21,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..30fe537 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
@@ -78,13 +83,13 @@ class H5_DLLCPP Exception {
 	// virtual Destructor
 	virtual ~Exception();
 
-   private:
-	H5std_string detail_message;
-	H5std_string func_name;
-
    protected:
         // Default value for detail_message
         static const char DEFAULT_MSG[];
+
+   private:
+	H5std_string detail_message;
+	H5std_string func_name;
 };
 
 class H5_DLLCPP FileIException : public Exception {
diff --git a/c++/src/H5FaccProp.h b/c++/src/H5FaccProp.h
index 040b3e9..5b56f6e 100644
--- a/c++/src/H5FaccProp.h
+++ b/c++/src/H5FaccProp.h
@@ -21,7 +21,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 b11be62..4fe51a9 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 77dd7be..615c1cb 100644
--- a/c++/src/H5File.cpp
+++ b/c++/src/H5File.cpp
@@ -163,7 +163,7 @@ H5File::H5File(const H5File& original) : H5Location(original)
 }
 
 //--------------------------------------------------------------------------
-// Function:	H5File::isHdf5
+// Function:	H5File::isHdf5 (static)
 ///\brief	Determines whether a file in HDF5 format. (Static)
 ///\param	name - IN: Name of the file
 ///\return	true if the file is in HDF5 format, and false, otherwise
@@ -186,7 +186,7 @@ bool H5File::isHdf5(const char* name)
 }
 
 //--------------------------------------------------------------------------
-// Function:	H5File::isHdf5
+// Function:	H5File::isHdf5 (static)
 ///\brief	This is an overloaded member function, provided for convenience.
 ///		It takes an \c H5std_string for \a name. (Static)
 ///\param	name - IN: Name of the file - \c H5std_string
@@ -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
@@ -537,6 +524,19 @@ hid_t H5File::getId() const
 
 #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::p_setId (protected)
 ///\brief       Sets the identifier of this object to a new value.
 ///
diff --git a/c++/src/H5File.h b/c++/src/H5File.h
index 830dda0..5fdbcdc 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.
@@ -94,6 +99,12 @@ class H5_DLLCPP H5File : public H5Location, public CommonFG {
 	// H5File destructor.
 	virtual ~H5File();
 
+   protected:
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+	// Sets the HDF5 file id.
+	virtual void p_setId(const hid_t new_id);
+#endif // DOXYGEN_SHOULD_SKIP_THIS
+
    private:
 	hid_t id;	// HDF5 file id
 
@@ -101,13 +112,6 @@ class H5_DLLCPP H5File : public H5Location, public CommonFG {
 	// constructors taking a string or a char*
 	void p_get_file( const char* name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist );
 
-   protected:
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
-	// Sets the HDF5 file id.
-	virtual void p_setId(const hid_t new_id);
-
-#endif // DOXYGEN_SHOULD_SKIP_THIS
-
 };
 #ifndef H5_NO_NAMESPACE
 }
diff --git a/c++/src/H5FloatType.h b/c++/src/H5FloatType.h
index 06148d6..06a5450 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 6299ea3..5d5b124 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
@@ -101,8 +101,6 @@ Group::Group(const hid_t existing_id) : H5Object()
 //--------------------------------------------------------------------------
 Group::Group(const H5Location& loc, const void* ref, H5R_type_t ref_type, const PropList& plist) : H5Object(), id(0)
 {
-     /* H5Location::dereference(loc, ref, ref_type, plist);
- */ 
     id = H5Location::p_dereference(loc.getId(), ref, ref_type, plist, "constructor - by dereference");
 }
 
@@ -118,14 +116,6 @@ Group::Group(const H5Location& loc, const void* ref, H5R_type_t ref_type, const
 Group::Group(const Attribute& attr, const void* ref, H5R_type_t ref_type, const PropList& plist) : H5Object(), id(0)
 {
     id = H5Location::p_dereference(attr.getId(), ref, ref_type, plist, "constructor - by dereference");
-/*
-    try {
-	id = p_dereference(attr.getId(), ref, ref_type, plist);
-    } catch (ReferenceException deref_error) {
-	throw ReferenceException("Group constructor - located by an Attribute",
-		deref_error.getDetailMsg());
-    }
-*/
 }
 
 //--------------------------------------------------------------------------
diff --git a/c++/src/H5Group.h b/c++/src/H5Group.h
index a5e324c..78f5f17 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.
@@ -56,14 +61,14 @@ class H5_DLLCPP Group : public H5Object, public CommonFG {
 	// Creates a copy of an existing group using its id.
 	Group( const hid_t group_id );
 
-   private:
-	hid_t id;	// HDF5 group id
-
    protected:
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 	// Sets the group id.
 	virtual void p_setId(const hid_t new_id);
 #endif // DOXYGEN_SHOULD_SKIP_THIS
+
+   private:
+	hid_t id;	// HDF5 group id
 };
 #ifndef H5_NO_NAMESPACE
 }
diff --git a/c++/src/H5IdComponent.h b/c++/src/H5IdComponent.h
index 5a61947..ca9352d 100644
--- a/c++/src/H5IdComponent.h
+++ b/c++/src/H5IdComponent.h
@@ -17,13 +17,18 @@
 #ifndef __IdComponent_H
 #define __IdComponent_H
 
-// IdComponent represents an HDF5 object that has an identifier.
-
 #ifndef H5_NO_NAMESPACE
 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.
@@ -76,11 +81,10 @@ class H5_DLLCPP IdComponent {
 	virtual ~IdComponent();
 
    protected:
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
-
 	// Default constructor.
 	IdComponent();
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 	// Gets the name of the file, in which an HDF5 object belongs.
 	H5std_string p_get_file_name() const;
 
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 22db85c..b413a17 100644
--- a/c++/src/H5Location.cpp
+++ b/c++/src/H5Location.cpp
@@ -565,9 +565,9 @@ void H5Location::p_reference(void* ref, const char* name, hid_t space_id, H5R_ty
 ///\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. - this is the default
+///			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
@@ -591,9 +591,9 @@ void H5Location::reference(void* ref, const char* name, const DataSpace& dataspa
 ///\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. - this is the default
+///			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
@@ -614,10 +614,10 @@ void H5Location::reference(void* ref, const H5std_string& name, const DataSpace&
 ///\param	ref - IN: Reference pointer
 ///\param	name - IN: Name of the object to be referenced
 ///\param	ref_type - IN: Type of reference to query, valid values are:
-///		\li \c H5R_OBJECT         - Reference is an object reference.
+///		\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
@@ -638,9 +638,9 @@ void H5Location::reference(void* ref, const char* name, H5R_type_t ref_type) con
 ///\param	ref - IN: Reference pointer
 ///\param	name - IN: Name of the object to be referenced - \c H5std_string
 ///\param	ref_type - IN: Type of reference to query, valid values are:
-///		\li \c H5R_OBJECT         - Reference is an object reference.
+///		\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
@@ -684,7 +684,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
diff --git a/c++/src/H5Location.h b/c++/src/H5Location.h
index 4ea13cd..bbe86fc 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
@@ -34,15 +30,23 @@ typedef void (*attr_operator_t)( H5Location& loc/*in*/,
                                  const H5std_string attr_name/*in*/,
                                  void *operator_data/*in,out*/);
 
-class UserData4Aiterate { // user data for attribute iteration
+//! User data for attribute iteration
+class UserData4Aiterate {
    public:
 	attr_operator_t op;
 	void* opData;
 	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
@@ -112,7 +116,7 @@ class H5_DLLCPP H5Location : public IdComponent {
 	void reference(void* ref, const char* name, 
 			H5R_type_t ref_type = H5R_OBJECT) const;
 	void reference(void* ref, const H5std_string& name,
-			H5R_type_t ref_type = H5R_DATASET_REGION) const;
+			H5R_type_t ref_type = H5R_OBJECT) const;
 	void reference(void* ref, const char* name, const DataSpace& dataspace,
 			H5R_type_t ref_type = H5R_DATASET_REGION) const;
 	void reference(void* ref, const H5std_string& name, const DataSpace& dataspace,
@@ -130,8 +134,7 @@ class H5_DLLCPP H5Location : public IdComponent {
 	virtual hid_t getId() const = 0;
 
    protected:
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
-	// Default constructor,
+	// Default constructor
 	H5Location();
 
 	// Creates a copy of an existing object giving the location id.
@@ -140,6 +143,7 @@ class H5_DLLCPP H5Location : public IdComponent {
 	// Copy constructor.
 	H5Location(const H5Location& original);
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 	// Creates a reference to an HDF5 object or a dataset region.
 	void p_reference(void* ref, const char* name, hid_t space_id, H5R_type_t ref_type) const;
 
@@ -154,11 +158,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..a8ec0b8 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,21 +230,18 @@ 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 );
-	bool committed();
-#endif // 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
-	// are closed.  -BMR, Mar 30, 2012
-	static const PredType AtExit;
+        /*! \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();
 
    protected:
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
@@ -254,6 +253,12 @@ class H5_DLLCPP PredType : public AtomType {
 
 #endif // 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
+	// are closed.  -BMR, Mar 30, 2012
+	static const PredType AtExit;
+
 };
 #ifndef H5_NO_NAMESPACE
 }
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..40c597f 100644
--- a/c++/src/H5VarLenType.h
+++ b/c++/src/H5VarLenType.h
@@ -14,9 +14,6 @@
  * access to either file, you may request a copy from help@hdfgroup.org.     *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-// Class VarLenType inherits from DataType and provides wrappers for
-// the HDF5 C's Variable-length Datatypes.
-
 #ifndef __H5VarLenType_H
 #define __H5VarLenType_H
 
@@ -24,6 +21,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