improve the doc of Actor::on_destruction()

Explain the difference with this_actor::on_exit()
This fixes https://github.com/simgrid/simgrid/issues/289

diff --git a/ChangeLog b/ChangeLog
index 3438268..a39a689 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -40,6 +40,7 @@ Fixed bugs:
  - #286: Pajé traces are not exposing the number of cores
  - #287: Command-line parsing should stop when encountering '--'
  - #288: MPI_Init(NULL, NULL)
  - #286: Pajé traces are not exposing the number of cores
  - #287: Command-line parsing should stop when encountering '--'
  - #288: MPI_Init(NULL, NULL)

+ - #289: Improve documentation of Actor::on_destruction and this_actor::on_exit()

  - #296: DTD too permissive
 
 ----------------------------------------------------------------------------
  - #296: DTD too permissive
 
 ----------------------------------------------------------------------------

diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp
index dcab10e..a951265 100644 (file)
--- a/include/simgrid/s4u/Actor.hpp
+++ b/include/simgrid/s4u/Actor.hpp
@@ -158,7 +158,10 @@ public:
   static simgrid::xbt::signal<void(simgrid::s4u::ActorPtr)> on_migration_start;
   /** Signal to others that an actor is has been migrated to another host **/
   static simgrid::xbt::signal<void(simgrid::s4u::ActorPtr)> on_migration_end;
   static simgrid::xbt::signal<void(simgrid::s4u::ActorPtr)> on_migration_start;
   /** Signal to others that an actor is has been migrated to another host **/
   static simgrid::xbt::signal<void(simgrid::s4u::ActorPtr)> on_migration_end;

-  /** Signal indicating that the given actor is about to disappear */
+  /** Signal indicating that an actor is about to disappear.
+   *  This signal is fired for any dying actor, which is mostly useful when
+   *  designing plugins and extensions. If you want to register to the
+   *  termination of a given actor, use this_actor::on_exit() instead.*/

   static simgrid::xbt::signal<void(simgrid::s4u::ActorPtr)> on_destruction;
 
   /** Create an actor from a std::function<void()>
   static simgrid::xbt::signal<void(simgrid::s4u::ActorPtr)> on_destruction;
 
   /** Create an actor from a std::function<void()>