Merge pull request #522 from dmcdougall/fix_smartptr_docs

Add docs for ScopedPtr and SmartPtr

Author: dmcdougall

src/core/inc/ScopedPtr.h

@@ -35,6 +35,38 @@
 #include <memory>
 #endif
 
+/*!
+ * \file ScopedPtr.h
+ * \brief This file declares and defines a scoped pointer
+ */
+
+/*!
+ * \class ScopedPtr
+ * \brief Definition of a scoped pointer.
+ *
+ * Scoped pointers are smart pointers that clean up after themselves when they
+ * go out of scope, with no shared ownership, and with no transfer of
+ * ownership regardless of the underlying implementation.
+ *
+ * If QUESO detects C++11 functionality at configure-time, then the underlying
+ * implementation of ScopedPtr is that of std::unique_ptr.  Even when this is
+ * the case, please note that shared ownership and transfer of ownership are
+ * not supported.
+ *
+ * If QUESO does not detect C++11 functionality then QUESO will check if boost
+ * is present and, if so, will use boost::scoped_ptr as the underlying
+ * implementation.  It should now be clear why shared ownership and transfer
+ * of ownership are not permitted.
+ *
+ * If QUESO fails to detect both C++11 functionality and boost then QUESO's
+ * last resort is to fall back on the C++03's std::auto_ptr.  If std::auto_ptr
+ * isn't detected, QUESO will fail to configure.
+ *
+ * ScopedPtr is implemented as a template typedef pattern.  That is, one
+ * declares a ScopedPtr like so:
+ *
+ * QUESO::ScopedPtr< name_of_type >::Type name_of_variable;
+ */
 namespace QUESO
 {
 #ifdef QUESO_HAVE_CXX11_UNIQUE_PTR

src/core/inc/SharedPtr.h

@@ -33,6 +33,33 @@
 #include <boost/shared_ptr.hpp>
 #endif
 
+/*!
+ * \file SharedPtr.h
+ * \brief This file declares and defines a shared pointer
+ */
+
+/*!
+ * \class SharedPtr
+ * \brief Definition of a shared pointer.
+ *
+ * Shared pointers may share ownership of some dynamically allocated object.
+ * The object pointed to is guaranteed to be deleted when the last underlying
+ * implementation of SharedPtr is destroyed or reset.
+ *
+ * If QUESO detects C++11 functionality ot configure-time, then the underlying
+ * implementation of SharedPtr is that of std::shared_ptr.
+ *
+ * If QUESO does not detect C++11 functionality, boost is required.  In that
+ * case, the underlying implementation is that of boost::shared_ptr.
+ *
+ * If QUESO does not detect C++11 functionality and does not detect boost then
+ * QUESO will fail to configure.
+ *
+ * SharedPtr is implemented as a template typdef pattern.  That is, one
+ * declares a SharedPtr like so:
+ *
+ * QUESO::SharedPtr< name_of_type >::Type name_of_variable;
+ */
 namespace QUESO
 {
 #ifdef QUESO_HAVE_CXX11_SHARED_PTR