ENH: Add class level documentation across the project. Remove a couple methods that

unnecessarily duplicated functionality.

XdmfArray.hpp

-/*
- * XdmfArray.hpp
- *
- *  Created on: Jan 25, 2010
- *      Author: kleiter
- */
-
 #ifndef XDMFARRAY_HPP_
 #define XDMFARRAY_HPP_
 
@@ -18,7 +11,7 @@ template<typename T>
 class XdmfArrayCopyValues : public boost::static_visitor <void> {
 public:
 
-	XdmfArrayCopyValues(int startIndex, T* valuesPointer, int numValues = 1, int arrayStride = 1, int valuesStride = 1) :
+	XdmfArrayCopyValues(int startIndex, T * valuesPointer, int numValues = 1, int arrayStride = 1, int valuesStride = 1) :
 		mStartIndex(startIndex),
 		mValuesPointer(valuesPointer),
 		mNumValues(numValues),
@@ -27,7 +20,7 @@ public:
 	{
 	}
 
-	template<typename U> void operator()(boost::shared_ptr<std::vector<U> > array) const
+	template<typename U> void operator()(boost::shared_ptr<std::vector<U> > & array) const
 	{
 		int size = mStartIndex + mNumValues;
 		if(mArrayStride > 1)
@@ -61,13 +54,13 @@ public:
     {
     }
 
-    boost::shared_ptr<std::vector<T> > operator()(const boost::shared_ptr<std::vector<T> > array) const
+    boost::shared_ptr<std::vector<T> > operator()(const boost::shared_ptr<std::vector<T> > & array) const
     {
         return array;
     }
 
     template <typename U>
-    boost::shared_ptr<std::vector<T> > operator()(const boost::shared_ptr<std::vector<U> > array) const
+    boost::shared_ptr<std::vector<T> > operator()(const boost::shared_ptr<std::vector<U> > & array) const
     {
         return boost::shared_ptr<std::vector<T> >();
     }
@@ -81,18 +74,53 @@ public:
     {
     }
 
-    const boost::shared_ptr<const std::vector<T> > operator()(const boost::shared_ptr<const std::vector<T> > array) const
+    const boost::shared_ptr<const std::vector<T> > operator()(const boost::shared_ptr<const std::vector<T> > & array) const
     {
         return array;
     }
 
     template <typename U>
-    const boost::shared_ptr<const std::vector<T> > operator()(const boost::shared_ptr<const std::vector<U> > array) const
+    const boost::shared_ptr<const std::vector<T> > operator()(const boost::shared_ptr<const std::vector<U> > & array) const
     {
         return boost::shared_ptr<std::vector<T> >();
     }
 };
 
+/**
+ * @brief Provides a single interface for storing a wide variety of data types.
+ *
+ * XdmfArray stores data values that are read in or will be written to heavy data on disk. The
+ * data type stored is determined by the type initially inserted into the XdmfArray.  XdmfArray
+ * allows for insertion and retrieval of data in two fundamental ways:
+ *
+ * By Copy:
+ *
+ *  copyValues
+ * 	getCopyValues
+ *
+ * 	XdmfArray stores its own copy of the data.  Modifications to the data stored in the XdmfArray will
+ * 	not change values stored in the original array.
+ *
+ * By Shared Reference:
+ *
+ * 	setValues
+ * 	getValues
+ *
+ * 	XdmfArray shares a reference to the data.  No copy is made. XdmfArray holds a shared pointer to the original
+ * 	data.  Modifications to the data stored in the XdmfArray also causes modification to values stored in the original
+ * 	array.
+ *
+ * Xdmf supports the following datatypes:
+ * 	Char
+ * 	Short
+ * 	Int
+ * 	Long
+ * 	Float
+ * 	Double
+ * 	Unsigned Char
+ * 	Unsigned Short
+ * 	Unsigned Int
+ */
 class XdmfArray : public XdmfItem {
 public:
 
@@ -103,6 +131,7 @@ public:
 	 *
 	 * @param startIndex the index in this array to begin insertion.
 	 * @param values a shared pointer to an XdmfArray to copy into this array.
+	 * @param valuesStartIndex the index in the XdmfArray to begin copying.
 	 * @param numValues the number of values to copy into this array.
 	 * @param arrayStride number of values to stride in this array between each copy.
 	 * @param valuesStride number of values to stride in the XdmfArray between each copy.
@@ -118,7 +147,7 @@ public:
 	 * @param arrayStride number of values to stride in this array between each copy.
 	 * @param valuesStride number of values to stride in the pointer between each copy.
 	 */
-	template<typename T> void copyValues(int startIndex, T* valuesPointer, int numValues = 1, int arrayStride = 1, int valuesStride = 1)
+	template<typename T> void copyValues(int startIndex, T * valuesPointer, int numValues = 1, int arrayStride = 1, int valuesStride = 1)
 	{
 		if(!mInitialized)
 		{
@@ -131,7 +160,7 @@ public:
 	}
 
 	/**
-	 * Clears all values from this array
+	 * Remove all values from this array
 	 */
 	virtual void clear();
 
@@ -153,14 +182,14 @@ public:
 	/**
 	 * Get the precision, in bytes, of the data type of this array.
 	 *
-	 * @return a int containing the precision, in bytes, of the data type of this array.
+	 * @return an int containing the precision, in bytes, of the data type of this array.
 	 */
 	virtual int getPrecision() const;
 
 	/**
 	 * Get the number of values stored in this array.
 	 *
-	 * @return a int containing the number of values stored in this array.
+	 * @return an int containing the number of values stored in this array.
 	 */
 	virtual int getSize() const;
 
@@ -187,7 +216,7 @@ public:
 	}
 
 	/**
-	 * Get a pointer to the values stored in this array (const version).
+	 * Get a pointer to the values stored in this array.
 	 *
 	 * @return a void pointer to the first value stored in this array.
 	 */
@@ -206,7 +235,7 @@ public:
 	 * Sets the values of this array to the values stored in the vector.  No copy is made.  This array shares ownership with
 	 * other references to the smart pointer.
 	 *
-	 * @param a smart pointer to a vector to store in this array.
+	 * @param array a smart pointer to a vector to store in this array.
 	 */
 	template<typename T> void setValues(boost::shared_ptr<std::vector<T> > array)
 	{

XdmfAttribute.cpp

@@ -21,42 +21,37 @@ XdmfAttribute::~XdmfAttribute()
 	std::cout << "Deleted Attribute " << this << std::endl;
 }
 
-XdmfAttributeType XdmfAttribute::getAttributeType() const
+XdmfAttributeCenter XdmfAttribute::getAttributeCenter() const
 {
-	return mAttributeType;
+	return mAttributeCenter;
 }
 
-void XdmfAttribute::setAttributeType(const XdmfAttributeType& attributeType)
+XdmfAttributeType XdmfAttribute::getAttributeType() const
 {
-	mAttributeType = attributeType;
+	return mAttributeType;
 }
 
-std::string XdmfAttribute::getAttributeTypeAsString() const
+std::string XdmfAttribute::getName() const
 {
-	return mAttributeType.getName();
+	return mName;
 }
 
-XdmfAttributeCenter XdmfAttribute::getAttributeCenter() const
+std::string XdmfAttribute::printSelf() const
 {
-	return mAttributeCenter;
+	return "<XdmfAttribute>";
 }
 
-void XdmfAttribute::setAttributeCenter(const XdmfAttributeCenter& attributeCenter)
+void XdmfAttribute::setAttributeCenter(const XdmfAttributeCenter & attributeCenter)
 {
 	mAttributeCenter = attributeCenter;
 }
 
-std::string XdmfAttribute::getAttributeCenterAsString() const
-{
-	return mAttributeCenter.getName();
-}
-
-std::string XdmfAttribute::getName() const
+void XdmfAttribute::setAttributeType(const XdmfAttributeType & attributeType)
 {
-	return mName;
+	mAttributeType = attributeType;
 }
 
-void XdmfAttribute::setName(const std::string& name)
+void XdmfAttribute::setName(const std::string & name)
 {
 	mName= name;
 }
@@ -65,8 +60,3 @@ void XdmfAttribute::write(boost::shared_ptr<XdmfVisitor> visitor) const
 {
 	visitor->visit(this, visitor);
 }
-
-std::string XdmfAttribute::printSelf() const
-{
-	return "<XdmfAttribute>";
-}

XdmfAttribute.hpp

-/*
- * XdmfAttribute.hpp
- *
- *  Created on: Jan 25, 2010
- *      Author: kleiter
- */
-
 #ifndef XDMFATTRIBUTE_HPP_
 #define XDMFATTRIBUTE_HPP_
 
@@ -13,6 +6,12 @@
 #include "XdmfAttributeType.hpp"
 #include "XdmfDataItem.hpp"
 
+/**
+ * @brief Handles computed values attached to an XdmfGrid.
+ *
+ * XdmfAttribute contains two properties that should be set, XdmfAttributeCenter and XdmfAttributeType.
+ * XdmfAttribute is a subclass of XdmfDataItem, meaning it contains an XdmfArray to store values.
+ */
 class XdmfAttribute : public XdmfDataItem {
 
 public:
@@ -20,65 +19,51 @@ public:
 	XdmfNewMacro(XdmfAttribute);
 
 	/**
-	 * Get the name of the attribute.
-	 *
-	 * @return a string containing the name of the attribute.
-	 */
-	std::string getName() const;
-
-	/**
-	 * Set the name of the attribute.
+	 * Get the XdmfAttributeCenter associated with this attribute.
 	 *
-	 * @param a string containing the name to set.
+	 * @return XdmfAttributeCenter of the attribute.
 	 */
-	void setName(const std::string&);
+	XdmfAttributeCenter getAttributeCenter() const;
 
 	/**
-	 * Get the XdmfAttributeType associated with this Attribute.
+	 * Get the XdmfAttributeType associated with this attribute.
 	 *
-	 * @return XdmfAttributeType.
+	 * @return XdmfAttributeType of the attribute.
 	 */
 	XdmfAttributeType getAttributeType() const;
 
 	/**
-	 * Set the XdmfAttributeType associated with this Attribute.
+	 * Get the name of the attribute.
 	 *
-	 * @param XdmfAttributeType to set.
+	 * @return a string containing the name of the attribute.
 	 */
-	void setAttributeType(const XdmfAttributeType& attributeType);
+	std::string getName() const;
 
-	/**
-	 * Get the name of the XdmfAttributeType associated with this Attribute.
-	 *
-	 * @return std::string containing name of the XdmfAttributeType.
-	 */
-	std::string getAttributeTypeAsString() const;
+	virtual std::string printSelf() const;
 
 	/**
-	 * Get the XdmfAttributeCenter associated with this Attribute.
+	 * Set the XdmfAttributeCenter associated with this attribute.
 	 *
-	 * @return XdmfAttributeCenter.
+	 * @param attributeCenter the XdmfAttributeCenter to set.
 	 */
-	XdmfAttributeCenter getAttributeCenter() const;
+	void setAttributeCenter(const XdmfAttributeCenter & attributeCenter);
 
 	/**
-	 * Set the XdmfAttributeCenter associated with this Attribute.
+	 * Set the XdmfAttributeType associated with this attribute.
 	 *
-	 * @param XdmfAttributeCenter to set.
+	 * @param attributeType XdmfAttributeType to set.
 	 */
-	void setAttributeCenter(const XdmfAttributeCenter& attributeCenter);
+	void setAttributeType(const XdmfAttributeType & attributeType);
 
 	/**
-	 * Get the name of the XdmfAttributeCenter associated with this Attribute.
+	 * Set the name of the attribute.
 	 *
-	 * @return std::string containing name of the XdmfAttributeCenter.
+	 * @param name a string containing the name to set.
 	 */
-	std::string getAttributeCenterAsString() const;
+	void setName(const std::string & name);
 
 	void write(boost::shared_ptr<XdmfVisitor> visitor) const;
 
-	virtual std::string printSelf() const;
-
 protected:
 
 	XdmfAttribute();
@@ -86,14 +71,12 @@ protected:
 
 private:
 
-	XdmfAttribute(const XdmfAttribute&);  // Not implemented.
-	void operator=(const XdmfAttribute&);  // Not implemented.
+	XdmfAttribute(const XdmfAttribute & attribute);  // Not implemented.
+	void operator=(const XdmfAttribute & attribute);  // Not implemented.
 
 	std::string mName;
 	XdmfAttributeType mAttributeType;
 	XdmfAttributeCenter mAttributeCenter;
-
 };
 
-
 #endif /* XDMFATTRIBUTE_HPP_ */

XdmfAttributeCenter.cpp

@@ -33,32 +33,32 @@ XdmfAttributeCenter XdmfAttributeCenter::Node()
 	return XdmfAttributeCenter("Node");
 }
 
-XdmfAttributeCenter::XdmfAttributeCenter(const std::string& name) :
+XdmfAttributeCenter::XdmfAttributeCenter(const std::string & name) :
 	mName(name)
 {};
 
-XdmfAttributeCenter::XdmfAttributeCenter(const XdmfAttributeCenter& attributeCenter):
-	mName(attributeCenter.mName)
+XdmfAttributeCenter::XdmfAttributeCenter(const XdmfAttributeCenter & attributeCenter):
+  mName(attributeCenter.mName)
 {
 }
 
-XdmfAttributeCenter& XdmfAttributeCenter::operator=(const XdmfAttributeCenter& attributeCenter)
+XdmfAttributeCenter& XdmfAttributeCenter::operator=(const XdmfAttributeCenter & attributeCenter)
 {
-	if(this != &attributeCenter)
-	{
-		mName = attributeCenter.mName;
-	}
-	return *this;
+  if(this != &attributeCenter)
+  {
+    mName = attributeCenter.mName;
+  }
+  return *this;
 }
 
-bool XdmfAttributeCenter::operator==(const XdmfAttributeCenter& attributeCenter) const
+bool XdmfAttributeCenter::operator==(const XdmfAttributeCenter & attributeCenter) const
 {
-	return mName.compare(attributeCenter.mName) == 0;
+  return mName.compare(attributeCenter.mName) == 0;
 }
 
-bool XdmfAttributeCenter::operator!=(const XdmfAttributeCenter& attributeCenter) const
+bool XdmfAttributeCenter::operator!=(const XdmfAttributeCenter & attributeCenter) const
 {
-	return !this->operator==(attributeCenter);
+  return !this->operator==(attributeCenter);
 }
 
 std::string XdmfAttributeCenter::getName() const

XdmfAttributeCenter.hpp

-/*
- * XdmfAttributeCenter.hpp
- *
- *  Created on: Jan 25, 2010
- *      Author: kleiter
- */
-
 #ifndef XDMFATTRIBUTECENTER_HPP_
 #define XDMFATTRIBUTECENTER_HPP_
 
+// Includes
 #include <string>
 
+/**
+ * @brief Property describing where XdmfAttribute values are centered.
+ *
+ * XdmfAttributeCenter is a property used by XdmfAttribute to specify where its values are centered
+ * on the XdmfGrid.  A specific XdmfAttributeCenter can be created by calling on of the static methods
+ * in the class, i.e. XdmfAttributeCenter::Cell().
+ *
+ * Xdmf supports the following attribute centers:
+ * 	Grid
+ * 	Cell
+ * 	Face
+ * 	Edge
+ * 	Node
+ */
 class XdmfAttributeCenter {
 
 public:
@@ -22,38 +30,42 @@ public:
 	static XdmfAttributeCenter Node();
 
 	/**
-	 * Get the name of this center type
+	 * Create the name of this attribute center.
 	 *
 	 * @return a string containing the name.
 	 */
 	std::string getName() const;
 
-	/*
+	/**
 	 * Compare two XdmfAttributeCenters for equality.
 	 *
-	 * @param an XdmfAttributeCenter to compare equality to.
-	 * @return true iff the XdmfAttributeCenters are equal.
+	 * @param attributeCenter an XdmfAttributeCenter to compare equality to.
+	 * @return true if the XdmfAttributeCenters are equal.
 	 */
-	bool operator==(const XdmfAttributeCenter& attributeCenter) const;
+	bool operator==(const XdmfAttributeCenter & attributeCenter) const;
 
 	/**
 	 * Compare two XdmfAttributeCenters for inequality.
 	 *
-	 * @param XdmfAttributeCenter to compare inequality to.
-	 * @return true iff the XdmfAttributeCenters are not equal.
+	 * @param attributeCenter an XdmfAttributeCenter to compare inequality to.
+	 * @return true if the XdmfAttributeCenters are not equal.
 	 */
-	bool operator!=(const XdmfAttributeCenter& attributeCenter) const;
+	bool operator!=(const XdmfAttributeCenter & attributeCenter) const;
+
+	XdmfAttributeCenter(const XdmfAttributeCenter & attributeCenter);
+	XdmfAttributeCenter& operator=(const XdmfAttributeCenter & attributeCenter);
 
-	XdmfAttributeCenter(const XdmfAttributeCenter& attributeCenter);
-	XdmfAttributeCenter& operator=(const XdmfAttributeCenter& attributeCenter);
 
 protected:
 
 	/**
 	 * Protected constructor for XdmfAttributeCenter.  The constructor is protected because all attribute centers supported
-	 * by Xdmf should be accessed through more specific static methods that construct XdmfAttributeCenters - i.e. XdmfAttributeCenter::Node().
+	 * by Xdmf should be accessed through more specific static methods that construct XdmfAttributeCenters - i.e.
+	 * XdmfAttributeCenter::Node().
+	 *
+	 * @param name the name of the XdmfAttributeCenter to construct.
 	 */
-	XdmfAttributeCenter(const std::string& name);
+	XdmfAttributeCenter(const std::string & name);
 
 private:
 

XdmfAttributeType.cpp

@@ -43,16 +43,16 @@ XdmfAttributeType XdmfAttributeType::GlobalId()
 	return XdmfAttributeType("GlobalId");
 }
 
-XdmfAttributeType::XdmfAttributeType(const std::string& name) :
+XdmfAttributeType::XdmfAttributeType(const std::string & name) :
 	mName(name)
 {};
 
-XdmfAttributeType::XdmfAttributeType(const XdmfAttributeType& attributeType):
+XdmfAttributeType::XdmfAttributeType(const XdmfAttributeType & attributeType):
 	mName(attributeType.mName)
 {
 }
 
-XdmfAttributeType& XdmfAttributeType::operator=(const XdmfAttributeType& attributeType)
+XdmfAttributeType& XdmfAttributeType::operator=(const XdmfAttributeType & attributeType)
 {
 	if(this != &attributeType)
 	{
@@ -61,12 +61,12 @@ XdmfAttributeType& XdmfAttributeType::operator=(const XdmfAttributeType& attribu
 	return *this;
 }
 
-bool XdmfAttributeType::operator==(const XdmfAttributeType& attributeType) const
+bool XdmfAttributeType::operator==(const XdmfAttributeType & attributeType) const
 {
 	return mName.compare(attributeType.mName) == 0;
 }
 
-bool XdmfAttributeType::operator!=(const XdmfAttributeType& attributeType) const
+bool XdmfAttributeType::operator!=(const XdmfAttributeType & attributeType) const
 {
 	return !this->operator==(attributeType);
 }

XdmfAttributeType.hpp

-/*
- * XdmfAttributeType.hpp
- *
- *  Created on: Jan 25, 2010
- *      Author: kleiter
- */
-
 #ifndef XDMFATTRIBUTETYPE_HPP_
 #define XDMFATTRIBUTETYPE_HPP_
 
+// Includes
 #include <string>
 
+/**
+ * @brief Property describing what types of values an XdmfAttribute contains.
+ *
+ * XdmfAttributeType is a property used by XdmfAttribute to specify what types of values the XdmfAttribute
+ * contains.  A specific XdmfAttributeType can be created by calling one of the static methods
+ * in the class, i.e. XdmfAttributeType::Scalar().
+ *
+ * Xdmf supports the following attribute types:
+ * 	NoAttributeType
+ * 	Scalar
+ * 	Vector
+ * 	Tensor
+ * 	Matrix
+ * 	Tensor6
+ * 	GlobalId
+ */
 class XdmfAttributeType {
 
 public:
@@ -33,29 +43,32 @@ public:
 	/*
 	 * Compare two XdmfAttributeTypes for equality.
 	 *
-	 * @param an XdmfAttributeType to compare equality to.
-	 * @return true iff the XdmfAttributeTypes are equal.
+	 * @param attributeType an XdmfAttributeType to compare equality to.
+	 * @return true if the XdmfAttributeTypes are equal.
 	 */
-	bool operator==(const XdmfAttributeType& attributeType) const;
+	bool operator==(const XdmfAttributeType & attributeType) const;
 
 	/**
 	 * Compare two XdmfAttributeTypes for inequality.
 	 *
-	 * @param XdmfAttributeType to compare inequality to.
-	 * @return true iff the XdmfAttributeTypes are not equal.
+	 * @param attributeType an XdmfAttributeType to compare inequality to.
+	 * @return true if the XdmfAttributeTypes are not equal.
 	 */
-	bool operator!=(const XdmfAttributeType& top) const;
+	bool operator!=(const XdmfAttributeType & attributeType) const;
 
-	XdmfAttributeType(const XdmfAttributeType& attributeType);
-	XdmfAttributeType& operator=(const XdmfAttributeType& attributeType);
+	XdmfAttributeType(const XdmfAttributeType & attributeType);
+	XdmfAttributeType& operator=(const XdmfAttributeType & attributeType);
 
 protected:
 
 	/**
 	 * Protected constructor for XdmfAttributeType.  The constructor is protected because all attribute types supported
-	 * by Xdmf should be accessed through more specific static methods that construct XdmfAttributeTypes - i.e. XdmfAttributeType::Scalar().
+	 * by Xdmf should be accessed through more specific static methods that construct XdmfAttributeTypes - i.e.
+	 * XdmfAttributeType::Scalar().
+	 *
+	 * @param name the name of the XdmfAttributeType to construct.
 	 */
-	XdmfAttributeType(const std::string& name);
+	XdmfAttributeType(const std::string & name);
 
 private:
 

XdmfDataItem.cpp

@@ -19,24 +19,24 @@ XdmfDataItem::~XdmfDataItem()
 	std::cout << "Deleted DataItem " << this << std::endl;
 }
 
-std::string XdmfDataItem::printSelf() const
+boost::shared_ptr<XdmfArray> XdmfDataItem::getArray()
 {
-	return "XdmfDataItem";
+	return mArray;
 }
 
-void XdmfDataItem::setArray(boost::shared_ptr<XdmfArray> array)
+boost::shared_ptr<const XdmfArray> XdmfDataItem::getArray() const
 {
-	mArray = array;
+	return mArray;
 }
 
-boost::shared_ptr<XdmfArray> XdmfDataItem::getArray()
+std::string XdmfDataItem::printSelf() const
 {
-	return mArray;
+	return "XdmfDataItem";
 }
 
-boost::shared_ptr<const XdmfArray> XdmfDataItem::getArray() const
+void XdmfDataItem::setArray(boost::shared_ptr<XdmfArray> array)
 {
-	return mArray;
+	mArray = array;
 }
 
 void XdmfDataItem::traverse(boost::shared_ptr<XdmfVisitor> visitor) const

XdmfDataItem.hpp

-/*
- * XdmfDataItem.hpp
- *
- *
- *  Created on: Jan 25, 2010
- *      Author: kleiter
- */
-
 #ifndef XDMFDATAITEM_HPP_
 #define XDMFDATAITEM_HPP_
 
@@ -15,34 +7,41 @@ class XdmfArray;
 // Includes
 #include "XdmfItem.hpp"
 
+/**
+ * @brief A type of XdmfItem that holds data values in an XdmfArray.
+ *
+ * XdmfDataItem is an abstract base class.  Any part of the Xdmf graph structure that holds values
+ * in an XdmfArray inherits from this.  XdmfDataItem imbues the ability to store and retrieve XdmfArrays.
+ */
 class XdmfDataItem : public XdmfItem {
 
 public:
 
 	/**
-	 * Attach an array to this dataitem.
-	 *
-	 * @param a smart pointer to the array.
-	 */
-	void setArray(boost::shared_ptr<XdmfArray> array);
-