document ConditionVariables in the new way

[simgrid.git] / include / simgrid / s4u / ConditionVariable.hpp

diff --git a/include/simgrid/s4u/ConditionVariable.hpp b/include/simgrid/s4u/ConditionVariable.hpp
index 8e8412757a1e06c941f60cd36716be73ad923d89..d33ee9ac1126c5ab0ba0385ba5a27d778154d72a 100644 (file)
--- a/include/simgrid/s4u/ConditionVariable.hpp
+++ b/include/simgrid/s4u/ConditionVariable.hpp
@@ -1,4 +1,4 @@
-/* Copyright (c) 2006-2019. The SimGrid Team. All rights reserved.          */
+/* Copyright (c) 2006-2020. The SimGrid Team. All rights reserved.          */
 
 /* This program is free software; you can redistribute it and/or modify it
  * under the terms of the license (GNU LGPL) which comes with this package. */
@@ -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:
@@ -55,7 +61,7 @@ public:
 
   std::cv_status wait_until(const std::unique_lock<Mutex>& lock, double timeout_time);
   std::cv_status wait_for(const std::unique_lock<Mutex>& lock, double duration);
-  template <class P> bool wait_until(std::unique_lock<Mutex> & lock, double timeout_time, P pred)
+  template <class P> bool wait_until(const std::unique_lock<Mutex>& lock, double timeout_time, P pred)
   {
     while (not pred())
       if (this->wait_until(lock, timeout_time) == std::cv_status::timeout)