Add doxygen annotations for epicsGuard.h

modules/libcom/src/cxxTemplates/epicsGuard.h

@@ -8,6 +8,12 @@
 * in file LICENSE that is included with this distribution.
 \*************************************************************************/
 
+/*!
+ * \file epicsGuard.h
+ * \brief Provides classes for RAII style locking and unlocking of mutexes
+ *
+ **/
+
 #ifndef epicsGuardh
 #define epicsGuardh
 
@@ -21,13 +27,35 @@
 
 template < class T > class epicsGuardRelease;
 
-// Automatically applies and releases the mutex.
-// This class is also useful in situations where
-// C++ exceptions are possible.
+/*!
+ * \brief Provides an RAII style lock/unlock of a mutex.
+ *
+ * When this object is created, it attempts to lock the mutex it was given.
+ * When control leaves the scope where this was created, the destructor unlocks
+ * the mutex.
+ *
+ * This class is also useful in situations where C++ exceptions are possible.
+ *
+ * \section Example
+ * \code{.cpp}
+ * epicsMutex mutex;
+ * {
+ *     epicsGuard guard(mutex);
+ *     printf("mutex is locked")
+ * }
+ * printf("mutex is unlocked\n");
+ * \endcode
+ **/
 template < class T >
 class epicsGuard {
 public:
     typedef epicsGuardRelease<T> release_t;
+
+    /*!
+     * Constructs an epicsGuard, locking the mutex for the scope of this object.
+     *
+     * @param T A mutex-like object to be lock()'ed and unlock()'ed
+     */
     epicsGuard ( T & );
     void assertIdenticalMutex ( const T & ) const;
     ~epicsGuard ();
@@ -38,13 +66,43 @@ private:
     friend class epicsGuardRelease < T >;
 };
 
-// Automatically releases and reapplies the mutex.
-// This class is also useful in situations where
-// C++ exceptions are possible.
+
+/*!
+ * \brief RAII style unlocking of an epicsGuard object
+ *
+ * This class can be used while a epicsGuard is active to temporarily release
+ * the mutex and automatically re-apply the lock when this object goes out of
+ * scope.
+ *
+ * This class is also useful in situations where C++ exceptions are possible.
+ *
+ * \section Example
+ * \code{.cpp}
+ * epicsMutex mutex;
+ * {
+ *     epicsGuard guard(mutex);
+ *     printf("mutex is locked");
+ *     {
+ *         epicsGuardRelease grelease(guard);
+ *         printf("mutex is unlocked");
+ *
+ *     }
+       printf("mutex is locked");
+
+       }
+ * printf("mutex is unlocked");
+ * }
+ * \endcode
+ *
+ */
 template < class T >
 class epicsGuardRelease {
 public:
     typedef epicsGuard<T> guard_t;
+        /*!
+         * \brief Constructs an epicsGuardRelease, unlocking the given epicsGuard
+         * \param guardIn The epicsGuard object to be temporarily released.
+         */
     epicsGuardRelease ( epicsGuard < T > & );
     ~epicsGuardRelease ();
 private:
@@ -55,11 +113,20 @@ private:
 };
 
 // same interface as epicsMutex
+/*!
+ * \brief Mutex-like object that does nothing.
+ *
+ * This object can be passed into an epicsGuard or similar interface when no actual locking is needed.
+ */
 class epicsMutexNOOP {
 public:
+    //! Does nothing
     void lock ();
+    //! Does nothing, always returns true.
     bool tryLock ();
+    //! Does nothing
     void unlock ();
+    //! Does nothing
     void show ( unsigned level ) const;
 };