osl: conditin.h and conditin.hxx doxygen updates

Change-Id: Ibdfa34d2b3b93ba0b5d5211dd4f843d849375e64
Reviewed-on: https://gerrit.libreoffice.org/38100
Tested-by: Jenkins <ci@libreoffice.org>
Reviewed-by: Chris Sherlock <chris.sherlock79@gmail.com>

2 files changed, 84 insertions, 46 deletions

diff --git a/include/osl/conditn.h b/include/osl/conditn.h
index 26d2cb103d62..a087f3504a49 100644
--- a/include/osl/conditn.h
+++ b/include/osl/conditn.h
@@ -32,9 +32,9 @@ extern "C" {
 typedef void* oslCondition;
 
 typedef enum {
-    osl_cond_result_ok,         /* successful completion */
-    osl_cond_result_error,      /* error occurred, check osl_getLastSocketError() for details */
-    osl_cond_result_timeout,    /* blocking operation timed out */
+    osl_cond_result_ok,                              /*<! Successful completion.                        */
+    osl_cond_result_error,                           /*<! Error occurred. @see osl_getLastSocketError() */
+    osl_cond_result_timeout,                         /*<! Blocking operation timed out.                 */
     osl_cond_result_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 } oslConditionResult;
 
@@ -44,38 +44,55 @@ typedef enum {
                 for a more robust and helpful condition.
 
     The condition is in the reset-state.
-    @retval 0 if condition could not be created.
+
+    @relates Condition
+
+    @retval osl_cond_result_error Condition could not be created.
 */
 SAL_DLLPUBLIC oslCondition SAL_CALL osl_createCondition(void);
 
 /** Free the memory used by the condition.
+
+    @relates Condition
+
     @param Condition the condition handle.
 */
 SAL_DLLPUBLIC void SAL_CALL osl_destroyCondition(oslCondition Condition);
 
 /** Sets condition to True => wait() will not block, check() returns True.
-    NOTE: ALL threads waiting on this condition are unblocked!
+
+    @attention @em all threads waiting on this condition are unblocked!
+
+    @relates Condition
+
     @param Condition handle to a created condition.
     @retval False if system-call failed.
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setCondition(oslCondition Condition);
 
 /** Sets condition to False => wait() will block, check() returns False
+
+    @relates Condition
+
     @param Condition handle to a created condition.
     @retval False if system-call failed.
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_resetCondition(oslCondition Condition);
 
-/** Blocks if condition is not set
-    If condition has been destroyed prematurely, wait() will
-    return with False.
+/** Blocks if condition is not set.
+
+    @relates Condition
+
     @param Condition handle to a created condition.
     @param pTimeout Timeout value or NULL for infinite waiting
-    @return False if system-call failed.
+    @retval False Condition has been destroyed prematurely or system call has failed.
 */
 SAL_DLLPUBLIC oslConditionResult SAL_CALL osl_waitCondition(oslCondition Condition, const TimeValue* pTimeout);
 
 /** Queries the state of the condition without blocking.
+
+    @relates Condition
+
     @param Condition handle to a created condition.
     @retval True condition is set
     @retval False condition is not set
diff --git a/include/osl/conditn.hxx b/include/osl/conditn.hxx
index 07d697948077..ffc7cc6b5c82 100644
--- a/include/osl/conditn.hxx
+++ b/include/osl/conditn.hxx
@@ -20,12 +20,10 @@
 #ifndef INCLUDED_OSL_CONDITN_HXX
 #define INCLUDED_OSL_CONDITN_HXX
 
-#include <sal/config.h>
-
 #include <cstddef>
 
+#include <sal/config.h>
 #include <osl/time.h>
-
 #include <osl/conditn.h>
 
 #if defined(MACOSX) && defined(__ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES)
@@ -36,63 +34,78 @@
 
 namespace osl
 {
-    /**
-     * A deprecated condition.
-     *
-     * @deprecated use C++11's std::condition_variable instead
-     *             for a more robust and helpful condition.
-     *
-     * Warning: the Condition abstraction is inadequate for any
-     * situation where there may be multiple threads setting,
-     * waiting, and resetting the same condition. It can only be
-     * used to synchronise interactions between two threads
-     * cf. lost wakeups in:
-     *    http://www.cs.wustl.edu/~schmidt/win32-cv-1.html
-     */
+    /** Condition variable
+
+       A condition variable is essentially an object that is initially
+       cleared which a thread waits on until it is "set". It allows a
+       thread to synchronize execution by allowing other threads to wait
+       for the condition to change before that thread then continues
+       execution.
+
+       @deprecated use C++11's std::condition_variable instead
+            for a more robust and helpful condition.
+
+       @attention Warning: the Condition abstraction is inadequate for
+            any situation where there may be multiple threads setting,
+            waiting, and resetting the same condition. It can only be
+            used to synchronise interactions between two threads
+            cf. lost wakeups in http://www.cs.wustl.edu/~schmidt/win32-cv-1.html
+    */
     class Condition
     {
     public:
-
         enum Result
         {
-            result_ok      = osl_cond_result_ok,
-            result_error   = osl_cond_result_error,
-            result_timeout = osl_cond_result_timeout
+            result_ok      = osl_cond_result_ok,        /*!< Succesful completion.                         */
+            result_error   = osl_cond_result_error,     /*!< Error occurred. @see osl_getLastSocketError() */
+            result_timeout = osl_cond_result_timeout    /*!< Blocking operation timed out.                 */
         };
 
-        /**
-         * Create a condition.
-         *
-         * @deprecated use C++11's std::condition_variable instead
-         *             for a more robust and helpful condition.
-         */
+        /** Create a condition.
+
+            @deprecated use C++11's std::condition_variable instead
+                for a more robust and helpful condition.
+        */
         Condition()
         {
             condition = osl_createCondition();
         }
 
-        /* Release the OS-structures and free condition data-structure.
-         */
+        /** Release the OS-structures and free condition data-structure.
+
+            @deprecated use C++11's std::condition_variable instead
+                for a more robust and helpful condition.
+        */
         ~Condition()
         {
             osl_destroyCondition(condition);
         }
 
-        /* Release all waiting threads, check returns true.
-         */
+        /** Release all waiting threads, check returns true.
+
+            @deprecated use C++11's std::condition_variable instead
+                for a more robust and helpful condition.
+        */
         void set()
         {
             osl_setCondition(condition);
         }
 
-        /* Reset condition to false: wait() will block, check() returns false.
-         */
+        /** Reset condition to false: wait() will block, check() returns
+            false.
+
+            @deprecated use C++11's std::condition_variable instead
+                        for a more robust and helpful condition.
+        */
         void reset() {
             osl_resetCondition(condition);
         }
 
         /** Blocks the calling thread until condition is set.
-         */
+
+            @deprecated use C++11's std::condition_variable instead
+                for a more robust and helpful condition.
+        */
         Result wait(const TimeValue *pTimeout = NULL)
         {
             return (Result) osl_waitCondition(condition, pTimeout);
@@ -103,7 +116,10 @@ namespace osl
 #endif
 
         /** Checks if the condition is set without blocking.
-         */
+
+            @deprecated use C++11's std::condition_variable instead
+                for a more robust and helpful condition.
+        */
         bool check()
         {
             return osl_checkCondition(condition);
@@ -115,18 +131,23 @@ namespace osl
 
         /** The underlying oslCondition has no reference count.
 
-        Since the underlying oslCondition is not a reference counted object, copy
-        constructed Condition may work on an already destructed oslCondition object.
+            Since the underlying oslCondition is not a reference counted
+            object, copy constructed Condition may work on an already
+            destructed oslCondition object.
 
+            @deprecated use C++11's std::condition_variable instead
+                for a more robust and helpful condition.
         */
         Condition(const Condition&) SAL_DELETED_FUNCTION;
 
         /** This assignment operator is deleted for the same reason as
             the copy constructor.
+
+            @deprecated use C++11's std::condition_variable instead
+                for a more robust and helpful condition.
         */
         Condition& operator= (const Condition&) SAL_DELETED_FUNCTION;
     };
-
 }
 
 #endif // INCLUDED_OSL_CONDITN_HXX