a word in the doc about signal's API

diff --git a/docs/source/Plugins.rst b/docs/source/Plugins.rst
index 1b91547..9fe6949 100644 (file)
--- a/docs/source/Plugins.rst
+++ b/docs/source/Plugins.rst
@@ -37,12 +37,12 @@ objects.
 The host load plugin in 
 `src/plugins/host_load.cpp <https://framagit.org/simgrid/simgrid/tree/master/src/plugins/host_load.cpp>`_
 constitutes a good introductory example. It defines a class
-```HostLoad``` that is meant to be attached to each host. This class
-contains a ```EXTENSION_ID``` field that is mandatory to our extension
-mechanism. Then, the function ```sg_host_load_plugin_init```
+``HostLoad`` that is meant to be attached to each host. This class
+contains a ``EXTENSION_ID`` field that is mandatory to our extension
+mechanism. Then, the function ``sg_host_load_plugin_init``
 initializes the plugin. It first calls
 :cpp:func:`simgrid::s4u::Host::extension_create()` to register its
-extension to the ```s4u::Host``` objects, and then attaches some
+extension to the ``s4u::Host`` objects, and then attaches some
 callbacks to signals.
 
 You can attach your own extension to most kinds of s4u object:
@@ -52,6 +52,20 @@ You can attach your own extension to most kinds of s4u object:
 :cpp:class:`Links <simgrid::s4u::Link>`. If you need to extend another
 kind of objects, please let us now.
 
+.. cpp:class:: template<class R, class... P> simgrid::xbt::signal<R(P...)>
+
+  A signal/slot mechanism, where you can attach callbacks to a given signal, and then fire the signal. 
+
+  The template parameter is the function signature of the signal (the return value currently ignored).
+
+.. cpp:function::: template<class R, class... P, class U>  unsigned int simgrid::xbt::signal<R(P...)>::connect(U slot)
+
+  Add a new callback to this signal.
+
+.. cpp:function:: template<class R, class... P> simgrid::xbt::signal<R(P...)>::operator()(P... args)
+
+  Fire that signal, invoking all callbacks.
+
 Partial list of existing signals in s4u:
 
 - :cpp:member:`Actor::on_creation <simgrid::s4u::Actor::on_creation>`

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 1b87d29..432ece9 100644 (file)
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -117,6 +117,7 @@ nitpick_ignore = [
   ('cpp:identifier', 'simgrid::xbt'),
   ('cpp:identifier', 'this_actor'),
   ('cpp:identifier', 's4u'),
+  ('cpp:identifier', 's4u_Actor'),
   ('cpp:identifier', 's4u_Barrier'),
   ('cpp:identifier', 's4u_ConditionVariable'),
   ('cpp:identifier', 's4u_Host'),

diff --git a/include/xbt/signal.hpp b/include/xbt/signal.hpp
index 1f53eaa..6824eee 100644 (file)
--- a/include/xbt/signal.hpp
+++ b/include/xbt/signal.hpp
@@ -16,11 +16,10 @@ namespace xbt {
   template<class S> class signal;
 
   /** A signal/slot mechanism
-  *
-  *  S is expected to be the function signature of the signal.
-  *  I'm not sure we need a return value (it is currently ignored).
-  *  If we don't we might use `signal<P1, P2, ...>` instead.
-  */
+   *
+   *  The template parameter is the function signature of the signal.
+   *  The return value currently ignored.
+   */
   template<class R, class... P>
   class signal<R(P...)> {
     using callback_type = std::function<R(P...)>;
@@ -28,18 +27,23 @@ namespace xbt {
     unsigned int callback_sequence_id = 0;
 
   public:
+    /** Add a new callback to this signal */
     template <class U> unsigned int connect(U slot)
     {
       handlers_.insert({callback_sequence_id, std::move(slot)});
       return callback_sequence_id++;
     }
+    /** Fire that signal, invoking all callbacks */
     R operator()(P... args) const
     {
       for (auto const& handler : handlers_)
         handler.second(args...);
     }
+    /** Remove a callback */
     void disconnect(unsigned int id) { handlers_.erase(id); }
+    /** Remove all callbacks */
     void disconnect_slots() { handlers_.clear(); }
+    /** Get the amount of callbacks */
     int get_slot_count() { return handlers_.size(); }
   };