Testing Doxygen code markup

include/atlex.h

@@ -26,66 +26,169 @@
 
 namespace ATL
 {
-    //
+    /**
-    // CObjectWithHandleT
+     * Base abstract template class to support generic object handle keeping
-    //
+     * It provides basic operators and methods to ease the replacement of native object handle type with this template class and its descendands.
-    template <class T>
+     */
-    class CObjectWithHandleT
+    template <class T> class CObjectWithHandleT
     {
     public:
+        /**
+         * Datatype of the object handle this template class handles
+         */
         typedef T HANDLE;
 
+        /**\name Constructors */
+        /**@{*/
+        /**
+         * The default constructor
+         * Sets the object handle to NULL.
+         */
         inline CObjectWithHandleT() throw() : m_h(NULL)
         {
         }
 
-        inline CObjectWithHandleT(HANDLE h) throw() : m_h(h)
+        /**
+         *\param h Initial object handle value
+         */
+        inline CObjectWithHandleT(_In_opt_ HANDLE h) throw() : m_h(h)
         {
         }
+        /**@}*/
 
+        /**\name Operators to allow transparent use of this class */
+        /**@{*/
+        /**
+         * Auto-typecasting operator
+         *\return Object handle
+         */
         inline operator HANDLE() const throw()
         {
             return m_h;
         }
 
+        /**
+         * Operator to return object handle value when the object handle is a pointer to a value (class, struct, etc.)
+         *\return Object handle value
+         */
         inline HANDLE*& operator*() const
         {
             ATLENSURE(m_h != NULL);
             return *m_h;
         }
 
+        /**
+         * Operator to return object handle reference
+         *\return Object handle reference
+         */
         inline HANDLE* operator&() throw()
         {
             ATLASSERT(m_h == NULL);
             return &m_h;
         }
 
+        /**
+         * Operator for object handle member access when the object handle is a pointer to a class or struct
+         *\return Object handle
+         */
         inline HANDLE operator->() const throw()
         {
             ATLASSERT(m_h != NULL);
             return m_h;
         }
+        /**@}*/
 
+        /**
+         * Test if the object handle is NULL
+         *\return
+         * - Non zero when object handle is NULL;
+         * - Zero otherwise.
+         */
         inline bool operator!() const throw()
         {
             return m_h == NULL;
         }
 
+        /**\name Comparison operators */
+        /**@{*/
+        /**
+         * Is less than
+         *\param h Object handle value to compare against
+         *\return
+         * - Non zero when object handle is less than h;
+         * - Zero otherwise.
+         */
         inline bool operator<(_In_opt_ HANDLE h) const throw()
         {
             return m_h < h;
         }
 
+        /**
+         * Is less than or equal to
+         *\param h Object handle value to compare against
+         *\return
+         * - Non zero when object handle is less than or equal to h;
+         * - Zero otherwise.
+         */
+        inline bool operator<=(_In_opt_ HANDLE h) const throw()
+        {
+            return m_h <= h;
+        }
+
+        /**
+         * Is greater than or equal to
+         *\param h Object handle value to compare against
+         *\return
+         * - Non zero when object handle is greater than or equal to h;
+         * - Zero otherwise.
+         */
+        inline bool operator>=(_In_opt_ HANDLE h) const throw()
+        {
+            return m_h >= h;
+        }
+
+        /**
+         * Is greater than
+         *\param h Object handle value to compare against
+         *\return
+         * - Non zero when object handle is greater than h;
+         * - Zero otherwise.
+         */
+        inline bool operator>(_In_opt_ HANDLE h) const throw()
+        {
+            return m_h > h;
+        }
+
+        /**
+         * Is not equal to
+         *\param h Object handle value to compare against
+         *\return
+         * - Non zero when object handle is not equal to h;
+         * - Zero otherwise.
+         */
         inline bool operator!=(_In_opt_ HANDLE h) const
         {
             return !operator==(h);
         }
 
+        /**
+         * Is equal to
+         *\param h Object handle value to compare against
+         *\return
+         * - Non zero when object handle is equal to h;
+         * - Zero otherwise.
+         */
         inline bool operator==(_In_opt_ HANDLE h) const throw()
         {
             return m_h == h;
         }
+        /**@}*/
 
+        /**
+         * Set a new object handle for the class
+         * When the current object handle of the class is non NULL, the object is destroyed first.
+         *\param h New object handle
+         */
         inline void Attach(_In_opt_ HANDLE h) throw()
         {
             if (m_h)
@@ -93,6 +196,10 @@ namespace ATL
             m_h = h;
         }
 
+        /**
+         * Dismiss the object handle from this class
+         *\return Object handle
+         */
         inline HANDLE Detach() throw()
         {
             HANDLE h = m_h;
@@ -100,6 +207,9 @@ namespace ATL
             return h;
         }
 
+        /**
+         * Destroys the object
+         */
         inline void Free() throw()
         {
             if (m_h) {
@@ -109,9 +219,13 @@ namespace ATL
         }
 
     protected:
+        /**
+         * Abstract method that must be implemented by child classes to do the actual object destruction
+         */
         virtual void InternalFree() = 0;
 
     protected:
+        /*** Object handle */
         HANDLE m_h;
     };