doc improvement

diff --git a/include/simgrid/kernel/resource/Action.hpp b/include/simgrid/kernel/resource/Action.hpp
index 95a5947..c8e20eb 100644 (file)
--- 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 feb9d7b..e3da5b2 100644 (file)
--- 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;