From: Martin Quinson <martin.quinson@loria.fr>
Date: Thu, 17 May 2018 20:01:44 +0000 (+0200)
Subject: doc improvement
X-Git-Tag: v3.20~215^2~3
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/4634214e18b847f6346048fa12179d3d99ae82c9

doc improvement
---

diff --git a/include/simgrid/kernel/resource/Action.hpp b/include/simgrid/kernel/resource/Action.hpp
index 95a5947f53..c8e20eb4bd 100644
--- a/include/simgrid/kernel/resource/Action.hpp
+++ b/include/simgrid/kernel/resource/Action.hpp
@@ -44,7 +44,11 @@ public:
   bool empty() const { return heap_type::empty(); }
 };
 
-/** @details An action is a consumption on a resource (e.g.: a communication for the network) */
+/** @details An action is a consumption on a resource (e.g.: a communication for the network).
+ *
+ * It is related (but still different) from activities, that are the stuff on which an actor can be blocked.
+ * See simgrid::s4u::Activity for more details.
+ */
 class XBT_PUBLIC Action {
   friend ActionHeap;
 
diff --git a/include/simgrid/s4u/Activity.hpp b/include/simgrid/s4u/Activity.hpp
index feb9d7b6de..e3da5b28f4 100644
--- a/include/simgrid/s4u/Activity.hpp
+++ b/include/simgrid/s4u/Activity.hpp
@@ -14,7 +14,17 @@ namespace s4u {
 /** @brief Activities
  *
  * This class is the ancestor of every activities that an actor can undertake.
- * That is, of the actions that do take time in the simulated world.
+ * That is, activities are all the things that do take time to the actor in the simulated world.
+ *
+ * They are somewhat linked but not identical to simgrid::kernel::resource::Action,
+ * that are stuff occurring on a resource:
+ *
+ * - A sequential execution activity encompasses 2 actions: one for the exec itself,
+ *   and a time-limited sleep used as timeout detector.
+ * - A point-to-point communication activity encompasses 3 actions: one for the comm itself
+ *   (which spans on all links of the path), and one infinite sleep used as failure detector
+ *   on both sender and receiver hosts.
+ * - Synchronization activities may possibly be connected to no action.
  */
 class XBT_PUBLIC Activity {
   friend Comm;