From: Gabriel Corona <gabriel.corona@loria.fr>
Date: Sat, 30 Jul 2016 22:51:26 +0000 (+0200)
Subject: [simix] Fix some documentation
X-Git-Tag: v3_14~691
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/f6ea9d672be1e8c695c1757126f00ece5b5cf790

[simix] Fix some documentation
---

diff --git a/include/simgrid/kernel/future.hpp b/include/simgrid/kernel/future.hpp
index 7d94a97364..9a57f8b6a1 100644
--- a/include/simgrid/kernel/future.hpp
+++ b/include/simgrid/kernel/future.hpp
@@ -390,8 +390,6 @@ public:
   }
 
   /** 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
diff --git a/include/simgrid/simix/blocking_simcall.hpp b/include/simgrid/simix/blocking_simcall.hpp
index 7fa0b25d6d..5389d8fce5 100644
--- 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);
 
-/** 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.
  *
- * 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
- * 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>`
@@ -141,7 +144,7 @@ private:
 /** 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)
@@ -149,11 +152,11 @@ auto kernelAsync(F code)
 {
   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));
 
-  // Wrap tyhe kernel simcall in a user simcall:
+  // Wrap the kernel future in a actor future:
   return simgrid::simix::Future<T>(std::move(future));
 }
 
diff --git a/include/xbt/future.hpp b/include/xbt/future.hpp
index 578e7b2942..a374bec117 100644
--- a/include/xbt/future.hpp
+++ b/include/xbt/future.hpp
@@ -20,10 +20,10 @@ namespace xbt {
 
 /** 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.
  *
- *  Also the name it not so great.
+ *  Also the name is not so great.
  **/
 template<class T>
 class Result {
@@ -118,7 +118,7 @@ public:
 
   /** Extract the value from the future
    *
-   *  After this the value is invalid.
+   *  After this, the value is invalid.
    **/
   T get()
   {
@@ -185,7 +185,7 @@ public:
  *  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).
@@ -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:
  *