[simix] Fix some documentation

diff --git a/include/simgrid/kernel/future.hpp b/include/simgrid/kernel/future.hpp
index 7d94a97..9a57f8b 100644 (file)
--- a/include/simgrid/kernel/future.hpp
+++ b/include/simgrid/kernel/future.hpp
@@ -390,8 +390,6 @@ public:
   }
 
   /** Get the value from the future
   }
 
   /** Get the value from the future

-   *
-   *  This is expected to be called

    *
    *  The future must be valid and ready in order to make this call.
    *  @ref std::future blocks when the future is not ready but we are
    *
    *  The future must be valid and ready in order to make this call.
    *  @ref std::future blocks when the future is not ready but we are

diff --git a/include/simgrid/simix/blocking_simcall.hpp b/include/simgrid/simix/blocking_simcall.hpp
index 7fa0b25..5389d8f 100644 (file)
--- a/include/simgrid/simix/blocking_simcall.hpp
+++ b/include/simgrid/simix/blocking_simcall.hpp
@@ -26,17 +26,20 @@ namespace simix {
 
 XBT_PUBLIC(void) unblock(smx_process_t process);
 
 
 XBT_PUBLIC(void) unblock(smx_process_t process);
 

-/** Execute some code in kernel mode and wakes up the process when
+/** Execute some code in kernel mode and wakes up the actor when

  *  the result is available.
  *
  *  the result is available.
  *

- * It is given a callback which is executed in the kernel SimGrid and
- * returns a simgrid::kernel::Future<T>. The kernel blocks the process
- * until the Future is ready and either the value wrapped in the future
- * to the process or raises the exception stored in the Future in the process.
+ * It is given a callback which is executed in the SimGrid kernel and
+ * returns a `simgrid::kernel::Future<T>`. The kernel blocks the actor
+ * until the Future is ready and:
+ *
+ *  - either returns the value wrapped in the future to the actor;
+ *
+ *  - or raises the exception stored in the future in the actor.

  *
  * This can be used to implement blocking calls without adding new simcalls.
  * One downside of this approach is that we don't have any semantic on what
  *
  * This can be used to implement blocking calls without adding new simcalls.
  * One downside of this approach is that we don't have any semantic on what

- * the process is waiting. This might be a problem for the model-checker and
+ * the actor is waiting. This might be a problem for the model-checker and

  * we'll have to devise a way to make it work.
  *
  * @param     code Kernel code returning a `simgrid::kernel::Future<T>`
  * we'll have to devise a way to make it work.
  *
  * @param     code Kernel code returning a `simgrid::kernel::Future<T>`


@@ -141,7 +144,7 @@ private:
 /** Start some asynchronous work
  *
  *  @param code SimGrid kernel code which returns a simgrid::kernel::Future
 /** Start some asynchronous work
  *
  *  @param code SimGrid kernel code which returns a simgrid::kernel::Future

- *  @return     User future
+ *  @return     Actor future

  */
 template<class F>
 auto kernelAsync(F code)
  */
 template<class F>
 auto kernelAsync(F code)


@@ -149,11 +152,11 @@ auto kernelAsync(F code)
 {
   typedef decltype(code().get()) T;
 
 {
   typedef decltype(code().get()) T;
 

-  // Execute the code in the kernel and get the kernel simcall:
+  // Execute the code in the kernel and get the kernel future:

   simgrid::kernel::Future<T> future =
     simgrid::simix::kernelImmediate(std::move(code));
 
   simgrid::kernel::Future<T> future =
     simgrid::simix::kernelImmediate(std::move(code));
 

-  // Wrap tyhe kernel simcall in a user simcall:
+  // Wrap the kernel future in a actor future:

   return simgrid::simix::Future<T>(std::move(future));
 }
 
   return simgrid::simix::Future<T>(std::move(future));
 }
 

diff --git a/include/xbt/future.hpp b/include/xbt/future.hpp
index 578e7b2..a374bec 100644 (file)
--- a/include/xbt/future.hpp
+++ b/include/xbt/future.hpp
@@ -20,10 +20,10 @@ namespace xbt {
 
 /** A value or an exception (or nothing)
  *
 
 /** A value or an exception (or nothing)
  *

- *  This is similar to optional<expected<T>> but it with a Future/Promise
+ *  This is similar to `optional<expected<T>>`` but it with a Future/Promise

  *  like API.
  *
  *  like API.
  *

- *  Also the name it not so great.
+ *  Also the name is not so great.

  **/
 template<class T>
 class Result {
  **/
 template<class T>
 class Result {


@@ -118,7 +118,7 @@ public:
 
   /** Extract the value from the future
    *
 
   /** Extract the value from the future
    *

-   *  After this the value is invalid.
+   *  After this, the value is invalid.

    **/
   T get()
   {
    **/
   T get()
   {


@@ -185,7 +185,7 @@ public:
  *  promise.set_value(code());
  *  </pre>
  *
  *  promise.set_value(code());
  *  </pre>
  *

- *  but it takes care of exceptions and works with void.
+ *  but it takes care of exceptions and works with `void`.

  *
  *  We might need this when working with generic code because
  *  the trivial implementation does not work with `void` (before C++1z).
  *
  *  We might need this when working with generic code because
  *  the trivial implementation does not work with `void` (before C++1z).


@@ -218,7 +218,7 @@ auto fulfillPromise(P& promise, F&& code)
   }
 }
 
   }
 }
 

-/** Set a promise/result from a future/resul
+/** Set a promise/result from a future/result

  *
  *  Roughly this does:
  *
  *
  *  Roughly this does:
  *