document ConditionVariables in the new way

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 8508821..a30d969 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -956,12 +956,60 @@ Synchronization Objects
 ⁣  class ConditionVariable
 ==========================
 
-.. doxygentypedef:: ConditionVariablePtr
+.. autodoxyclass:: simgrid::s4u::ConditionVariable
 
-.. doxygenclass:: simgrid::s4u::ConditionVariable
-   :members:
-   :protected-members:
-   :undoc-members:
+Basic management
+----------------
+
+   .. tabs::
+
+      .. group-tab:: C++
+
+         .. code-block:: C
+
+            #include <simgrid/s4u/ConditionVariable.hpp>
+
+         .. doxygentypedef:: ConditionVariablePtr
+
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::create()
+
+      .. group-tab:: C
+
+         .. code-block:: C
+
+            #include <simgrid/cond.h>
+
+         .. doxygentypedef:: sg_cond_t
+         .. doxygenfunction:: sg_cond_init
+         .. doxygenfunction:: sg_cond_destroy
+
+Waiting and notifying
+---------------------
+
+   .. tabs::
+
+      .. group-tab:: C++
+
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::notify_all()
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::notify_one()
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(MutexPtr lock)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< Mutex > &lock)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< Mutex > &lock, P pred)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< Mutex > &lock, double duration)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< Mutex > &lock, double duration, P pred)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< Mutex > &lock, std::chrono::duration< Rep, Period > duration)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< Mutex > &lock, std::chrono::duration< Rep, Period > duration, P pred)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time, P pred)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< Mutex > &lock, double timeout_time)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< Mutex > &lock, double timeout_time, P pred)
+
+      .. group-tab:: C
+
+         .. doxygenfunction:: sg_cond_notify_all
+         .. doxygenfunction:: sg_cond_notify_one
+         .. doxygenfunction:: sg_cond_wait
+         .. doxygenfunction:: sg_cond_wait_for
 
 .. _API_s4u_Mutex:
 
@@ -989,22 +1037,6 @@ Synchronization Objects
    :protected-members:
    :undoc-members:
 
-
-C API Reference
-***************
-
-==================
-Condition Variable
-==================
-
-See also the :ref:`C++ API <API_s4u_ConditionVariable>`.
-
-.. doxygenfunction:: sg_cond_init
-.. doxygenfunction:: sg_cond_notify_all
-.. doxygenfunction:: sg_cond_notify_one
-.. doxygenfunction:: sg_cond_wait
-.. doxygenfunction:: sg_cond_wait_for
-
 Python API Reference
 ********************
 
@@ -1018,13 +1050,6 @@ this_actor
 .. automodule:: simgrid.this_actor
    :members:
 
-===========
-Class Actor
-===========
-
-.. autoclass:: simgrid.Actor
-   :members:
-
 ==========
 Class Comm
 ==========
@@ -1032,13 +1057,6 @@ Class Comm
 .. autoclass:: simgrid.Comm
    :members:
 
-============
-Class Engine
-============
-
-.. autoclass:: simgrid.Engine
-   :members:
-
 ==========
 Class Exec
 ==========

diff --git a/include/simgrid/cond.h b/include/simgrid/cond.h
index 464c6c8..b798624 100644 (file)
--- a/include/simgrid/cond.h
+++ b/include/simgrid/cond.h
@@ -18,11 +18,11 @@ XBT_PUBLIC void sg_cond_wait(sg_cond_t cond, sg_mutex_t mutex);
 /** @brief Blocks onto the given condition variable, but only for the given amount of time.
  *  @return 0 on success, 1 on timeout */
 XBT_PUBLIC int sg_cond_wait_for(sg_cond_t cond, sg_mutex_t mutex, double delay);
-/** @brief Signals the given mutex variable */
+/** @brief Signals the given condition variable */
 XBT_PUBLIC void sg_cond_notify_one(sg_cond_t cond);
-/** @brief Broadcasts the given mutex variable */
+/** @brief Broadcasts the given condition variable */
 XBT_PUBLIC void sg_cond_notify_all(sg_cond_t cond);
-/** @brief Destroys the given mutex variable */
+/** @brief Destroys the given condition variable */
 XBT_PUBLIC void sg_cond_destroy(const_sg_cond_t cond);
 
 SG_END_DECL

diff --git a/include/simgrid/forward.h b/include/simgrid/forward.h
index 607810d..517c473 100644 (file)
--- a/include/simgrid/forward.h
+++ b/include/simgrid/forward.h
@@ -36,7 +36,10 @@ XBT_PUBLIC void intrusive_ptr_release(Comm* c);
 XBT_PUBLIC void intrusive_ptr_add_ref(Comm* c);
 
 class ConditionVariable;
-/** Smart pointer to a simgrid::s4u::ConditionVariable */
+/** @beginrst
+ * Smart pointer to a :cpp:type:`simgrid::s4u::ConditionVariable`
+ * @endrst
+ */
 typedef boost::intrusive_ptr<ConditionVariable> ConditionVariablePtr;
 XBT_PUBLIC void intrusive_ptr_release(const ConditionVariable* c);
 XBT_PUBLIC void intrusive_ptr_add_ref(const ConditionVariable* c);

diff --git a/include/simgrid/s4u/ConditionVariable.hpp b/include/simgrid/s4u/ConditionVariable.hpp
index f10780c..d33ee9a 100644 (file)
--- a/include/simgrid/s4u/ConditionVariable.hpp
+++ b/include/simgrid/s4u/ConditionVariable.hpp
@@ -16,12 +16,12 @@
 namespace simgrid {
 namespace s4u {
 
-/** @brief A condition variable
- *  @ingroup s4u_api
- *
- *  This is a drop-in replacement of `std::condition_variable` and should respect the same
- *  semantic. But we currently use (only) double for both durations and
- *  timestamp timeouts.
+/**
+ * @rst
+ * SimGrid's Condition Variables are meant to be drop-in replacements of
+ * `std::condition_variable <https://en.cppreference.com/w/cpp/thread/condition_variable>`_
+ * and should respect the same semantic.
+ * @endrst
  */
 class XBT_PUBLIC ConditionVariable {
 private:
@@ -29,9 +29,9 @@ private:
   kernel::activity::ConditionVariableImpl* const cond_;
 
 public:
+#ifndef DOXYGEN
   explicit ConditionVariable(kernel::activity::ConditionVariableImpl* cond) : cond_(cond) {}
 
-#ifndef DOXYGEN
   ConditionVariable(ConditionVariable const&) = delete;
   ConditionVariable& operator=(ConditionVariable const&) = delete;
 
@@ -39,6 +39,12 @@ public:
   friend XBT_PUBLIC void intrusive_ptr_release(const ConditionVariable* cond);
 #endif
 
+  /** Create a new condition variable and return a smart pointer
+   *
+   * @rst
+   * You should only manipulate :cpp:type:`simgrid::s4u::ConditionVariablePtr`, as created by this function (see also :ref:`s4u_raii`).
+   * @endrst
+   */
   static ConditionVariablePtr create();
 
   //  Wait functions without time: