Many tiny documentation improvements

- Fix links now that signals are hidden but *_cb functions provided
- Add some links from functions to examples
- Reference some previously unreferenced examples
- Fix some Doxygen errors

diff --git a/docs/source/Plugins.rst b/docs/source/Plugins.rst
index dc475e5..08c454e 100644 (file)
--- a/docs/source/Plugins.rst
+++ b/docs/source/Plugins.rst
@@ -69,48 +69,48 @@ kind of objects, please let us now.
 
 Partial list of existing signals in s4u:
 
-- :cpp:member:`Actor::on_creation <simgrid::s4u::Actor::on_creation>`
-  :cpp:member:`Actor::on_suspend <simgrid::s4u::Actor::on_suspend>`
-  :cpp:member:`Actor::on_resume <simgrid::s4u::Actor::on_resume>`
-  :cpp:member:`Actor::on_sleep <simgrid::s4u::Actor::on_sleep>`
-  :cpp:member:`Actor::on_wake_up <simgrid::s4u::Actor::on_wake_up>`
-  :cpp:member:`Actor::on_host_change <simgrid::s4u::Actor::on_host_change>`
-  :cpp:member:`Actor::on_termination <simgrid::s4u::Actor::on_termination>`
-  :cpp:member:`Actor::on_destruction <simgrid::s4u::Actor::on_destruction>`
-- :cpp:member:`Comm::on_send <simgrid::s4u::Comm::on_send>`
-  :cpp:member:`Comm::on_recv <simgrid::s4u::Comm::on_recv>`
-  :cpp:member:`Comm::on_completion <simgrid::s4u::Comm::on_completion>`
-- :cpp:member:`CommImpl::on_start <simgrid::kernel::actiivty::CommImpl::on_start>`
-  :cpp:member:`CommImpl::on_completion <simgrid::kernel::activity::CommImpl::on_completion>`
-- :cpp:member:`Disk::on_creation <simgrid::s4u::Disk::on_creation>`
-  :cpp:member:`Disk::on_destruction <simgrid::s4u::Disk::on_destruction>`
-  :cpp:member:`Disk::on_state_change <simgrid::s4u::Disk::on_state_change>`
-- :cpp:member:`Engine::on_platform_creation <simgrid::s4u::Engine::on_platform_creation>`
-  :cpp:member:`Engine::on_platform_created <simgrid::s4u::Engine::on_platform_created>`
-  :cpp:member:`Engine::on_time_advance <simgrid::s4u::Engine::on_time_advance>`
-  :cpp:member:`Engine::on_simulation_end <simgrid::s4u::Engine::on_simulation_end>`
-  :cpp:member:`Engine::on_deadlock <simgrid::s4u::Engine::on_deadlock>`
-- :cpp:member:`Exec::on_start <simgrid::s4u::Exec::on_start>`
-  :cpp:member:`Exec::on_completion <simgrid::s4u::Exec::on_completion>`
-- :cpp:member:`Host::on_creation <simgrid::s4u::Host::on_creation>`
-  :cpp:member:`Host::on_destruction <simgrid::s4u::Host::on_destruction>`
-  :cpp:member:`Host::on_state_change <simgrid::s4u::Host::on_state_change>`
-  :cpp:member:`Host::on_speed_change <simgrid::s4u::Host::on_speed_change>`
-- :cpp:member:`Io::on_start <simgrid::s4u::Io::on_start>`
-  :cpp:member:`Io::on_completion <simgrid::s4u::Io::on_completion>`
-- :cpp:member:`Link::on_creation <simgrid::s4u::Link::on_creation>`
-  :cpp:member:`Link::on_destruction <simgrid::s4u::Link::on_destruction>`
-  :cpp:member:`Link::on_state_change <simgrid::s4u::Link::on_state_change>`
-  :cpp:member:`Link::on_speed_change <simgrid::s4u::Link::on_bandwidth_change>`
-  :cpp:member:`Link::on_communication_state_change <simgrid::s4u::Link::on_communication_state_change>`
-- :cpp:member:`NetZone::on_creation <simgrid::s4u::NetZone::on_creation>`
-  :cpp:member:`NetZone::on_seal <simgrid::s4u::NetZone::on_seal>`
-- :cpp:member:`VirtualMachine::on_start <simgrid::s4u::VirtualMachine::on_start>`
-  :cpp:member:`VirtualMachine::on_started <simgrid::s4u::VirtualMachine::on_started>`
-  :cpp:member:`VirtualMachine::on_suspend <simgrid::s4u::VirtualMachine::on_suspend>`
-  :cpp:member:`VirtualMachine::on_resume <simgrid::s4u::VirtualMachine::on_resume>`
-  :cpp:member:`VirtualMachine::on_migration_start <simgrid::s4u::VirtualMachine::on_migration_start>`
-  :cpp:member:`VirtualMachine::on_migration_end <simgrid::s4u::VirtualMachine::on_migration_end>`
+- :cpp:member:`Actor::on_creation <simgrid::s4u::Actor::on_creation_cb>`
+  :cpp:member:`Actor::on_suspend <simgrid::s4u::Actor::on_suspend_cb>`
+  :cpp:member:`Actor::on_resume <simgrid::s4u::Actor::on_resume_cb>`
+  :cpp:member:`Actor::on_sleep <simgrid::s4u::Actor::on_sleep_cb>`
+  :cpp:member:`Actor::on_wake_up <simgrid::s4u::Actor::on_wake_up_cb>`
+  :cpp:member:`Actor::on_host_change <simgrid::s4u::Actor::on_host_change_cb>`
+  :cpp:member:`Actor::on_termination <simgrid::s4u::Actor::on_termination_cb>`
+  :cpp:member:`Actor::on_destruction <simgrid::s4u::Actor::on_destruction_cb>`
+- :cpp:member:`Comm::on_send <simgrid::s4u::Comm::on_send_cb>`
+  :cpp:member:`Comm::on_recv <simgrid::s4u::Comm::on_recv_cb>`
+  :cpp:member:`Comm::on_completion <simgrid::s4u::Comm::on_completion_cb>`
+- :cpp:member:`CommImpl::on_start <simgrid::kernel::actiivty::CommImpl::on_start_cb>`
+  :cpp:member:`CommImpl::on_completion <simgrid::kernel::activity::CommImpl::on_completion_cb>`
+- :cpp:member:`Disk::on_creation <simgrid::s4u::Disk::on_creation_cb>`
+  :cpp:member:`Disk::on_destruction <simgrid::s4u::Disk::on_destruction_cb>`
+  :cpp:member:`Disk::on_state_change <simgrid::s4u::Disk::on_state_change_cb>`
+- :cpp:member:`Engine::on_platform_creation <simgrid::s4u::Engine::on_platform_creation_cb>`
+  :cpp:member:`Engine::on_platform_created <simgrid::s4u::Engine::on_platform_created_cb>`
+  :cpp:member:`Engine::on_time_advance <simgrid::s4u::Engine::on_time_advance_cb>`
+  :cpp:member:`Engine::on_simulation_end <simgrid::s4u::Engine::on_simulation_end_cb>`
+  :cpp:member:`Engine::on_deadlock <simgrid::s4u::Engine::on_deadlock_cb>`
+- :cpp:member:`Exec::on_start <simgrid::s4u::Exec::on_start_cb>`
+  :cpp:member:`Exec::on_completion <simgrid::s4u::Exec::on_completion_cb>`
+- :cpp:member:`Host::on_creation <simgrid::s4u::Host::on_creation_cb>`
+  :cpp:member:`Host::on_destruction <simgrid::s4u::Host::on_destruction_cb>`
+  :cpp:member:`Host::on_state_change <simgrid::s4u::Host::on_state_change_cb>`
+  :cpp:member:`Host::on_speed_change <simgrid::s4u::Host::on_speed_change_cb>`
+- :cpp:member:`Io::on_start <simgrid::s4u::Io::on_start_cb>`
+  :cpp:member:`Io::on_completion <simgrid::s4u::Io::on_completion_cb>`
+- :cpp:member:`Link::on_creation <simgrid::s4u::Link::on_creation_cb>`
+  :cpp:member:`Link::on_destruction <simgrid::s4u::Link::on_destruction_cb>`
+  :cpp:member:`Link::on_state_change <simgrid::s4u::Link::on_state_change_cb>`
+  :cpp:member:`Link::on_speed_change <simgrid::s4u::Link::on_bandwidth_change_cb>`
+  :cpp:member:`Link::on_communication_state_change <simgrid::s4u::Link::on_communication_state_change_cb>`
+- :cpp:member:`NetZone::on_creation <simgrid::s4u::NetZone::on_creation_cb>`
+  :cpp:member:`NetZone::on_seal <simgrid::s4u::NetZone::on_seal_cb>`
+- :cpp:member:`VirtualMachine::on_start <simgrid::s4u::VirtualMachine::on_start_cb>`
+  :cpp:member:`VirtualMachine::on_started <simgrid::s4u::VirtualMachine::on_started_cb>`
+  :cpp:member:`VirtualMachine::on_suspend <simgrid::s4u::VirtualMachine::on_suspend_cb>`
+  :cpp:member:`VirtualMachine::on_resume <simgrid::s4u::VirtualMachine::on_resume_cb>`
+  :cpp:member:`VirtualMachine::on_migration_start <simgrid::s4u::VirtualMachine::on_migration_start_cb>`
+  :cpp:member:`VirtualMachine::on_migration_end <simgrid::s4u::VirtualMachine::on_migration_end_cb>`
 
 Existing Plugins
 ****************

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index c865743..b98b49a 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -453,6 +453,8 @@ Basic management
 Creating actors
 ---------------
 
+See also :ref:`the relevant example <s4u_ex_actors_create>`.
+
 .. tabs::
 
    .. group-tab:: C++
@@ -958,11 +960,11 @@ Signals
 
    .. group-tab:: C++
 
-      .. doxygenvariable:: simgrid::s4u::Engine::on_deadlock
-      .. doxygenvariable:: simgrid::s4u::Engine::on_platform_created
-      .. doxygenvariable:: simgrid::s4u::Engine::on_platform_creation
-      .. doxygenvariable:: simgrid::s4u::Engine::on_simulation_end
-      .. doxygenvariable:: simgrid::s4u::Engine::on_time_advance
+      .. doxygenfunction:: simgrid::s4u::Engine::on_deadlock_cb
+      .. doxygenfunction:: simgrid::s4u::Engine::on_platform_created_cb
+      .. doxygenfunction:: simgrid::s4u::Engine::on_platform_creation_cb
+      .. doxygenfunction:: simgrid::s4u::Engine::on_simulation_end_cb
+      .. doxygenfunction:: simgrid::s4u::Engine::on_time_advance_cb
 
 .. _API_s4u_Mailbox:
 
@@ -1439,7 +1441,7 @@ using :cpp:func:`Comm::sendto() <simgrid::s4u::Comm::sendto()>`.
       .. doxygenfunction:: simgrid::s4u::Host::get_englobing_zone() const
       .. doxygenfunction:: simgrid::s4u::Host::get_netpoint() const
       .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< Link * > &links, double *latency) const
-      .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::LinkImpl * > &links, double *latency) const
+      .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::StandardLinkImpl * > &links, double *latency) const
       .. doxygenfunction:: simgrid::s4u::Host::create_disk(const std::string& name, double read_bandwidth, double write_bandwidth)
       .. doxygenfunction:: simgrid::s4u::Host::create_disk(const std::string& name, const std::string& read_bandwidth, const std::string& write_bandwidth)
 
@@ -1462,10 +1464,10 @@ Signals
 
    .. group-tab:: C++
 
-      .. doxygenvariable:: simgrid::s4u::Host::on_creation
-      .. doxygenvariable:: simgrid::s4u::Host::on_destruction
-      .. doxygenvariable:: simgrid::s4u::Host::on_speed_change
-      .. doxygenvariable:: simgrid::s4u::Host::on_state_change
+      .. doxygenfunction:: simgrid::s4u::Host::on_creation_cb
+      .. doxygenfunction:: simgrid::s4u::Host::on_destruction_cb
+      .. doxygenfunction:: simgrid::s4u::Host::on_speed_change_cb
+      .. doxygenfunction:: simgrid::s4u::Host::on_state_change_cb
 
 .. _API_s4u_Link:
 
@@ -1652,11 +1654,11 @@ Signals
 
    .. group-tab:: C++
 
-      .. doxygenvariable:: simgrid::s4u::Link::on_bandwidth_change
-      .. doxygenvariable:: simgrid::s4u::Link::on_communication_state_change
-      .. doxygenvariable:: simgrid::s4u::Link::on_creation
-      .. doxygenvariable:: simgrid::s4u::Link::on_destruction
-      .. doxygenvariable:: simgrid::s4u::Link::on_state_change
+      .. doxygenfunction:: simgrid::s4u::Link::on_bandwidth_change_cb
+      .. doxygenfunction:: simgrid::s4u::Link::on_communication_state_change_cb
+      .. doxygenfunction:: simgrid::s4u::Link::on_creation_cb
+      .. doxygenfunction:: simgrid::s4u::Link::on_destruction_cb
+      .. doxygenfunction:: simgrid::s4u::Link::on_state_change_cb
 
 .. _API_s4u_NetZone:
 
@@ -1810,8 +1812,8 @@ Signals
 
   .. group-tab:: C++
 
-     .. doxygenvariable:: simgrid::s4u::NetZone::on_creation
-     .. doxygenvariable:: simgrid::s4u::NetZone::on_seal
+     .. doxygenfunction:: simgrid::s4u::NetZone::on_creation_cb
+     .. doxygenfunction:: simgrid::s4u::NetZone::on_seal_cb
 
 Creating resources
 ------------------
@@ -2190,9 +2192,9 @@ Signals
 
    .. group-tab:: C++
 
-      .. doxygenvariable:: simgrid::s4u::Comm::on_completion
-      .. doxygenvariable:: simgrid::s4u::Comm::on_recv
-      .. doxygenvariable:: simgrid::s4u::Comm::on_send
+      .. doxygenfunction:: simgrid::s4u::Comm::on_completion_cb
+      .. doxygenfunction:: simgrid::s4u::Comm::on_recv_cb
+      .. doxygenfunction:: simgrid::s4u::Comm::on_send_cb
 
 .. _API_s4u_Exec:
 
@@ -2310,8 +2312,8 @@ Signals
 
    .. group-tab:: C++
 
-      .. doxygenvariable:: simgrid::s4u::Exec::on_start
-      .. doxygenvariable:: simgrid::s4u::Exec::on_completion
+      .. doxygenfunction:: simgrid::s4u::Exec::on_start_cb
+      .. doxygenfunction:: simgrid::s4u::Exec::on_completion_cb
 
 .. _API_s4u_Io:
 

diff --git a/examples/README.rst b/examples/README.rst
index 8b45393..8645aff 100644 (file)
--- a/examples/README.rst
+++ b/examples/README.rst
@@ -32,6 +32,8 @@ Actors: the Active Entities
 Starting and Stopping Actors
 ----------------------------
 
+.. _s4u_ex_actors_create:
+
 Creating actors
 ^^^^^^^^^^^^^^^
 
@@ -387,7 +389,7 @@ The ``wait_all()`` function is useful when you want to block until all activitie
 Waiting for the first completed communication in a set
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``wait_any()`` function is useful when you want to block until one activity of the set completes, no matter which terminates first.
+The ``wait_any()`` blocks until one activity of the set completes, no matter which terminates first.
 
 .. tabs::
 
@@ -403,6 +405,18 @@ The ``wait_any()`` function is useful when you want to block until one activity
 
       See also :cpp:func:`sg_comm_wait_any`.
 
+Testing whether at least one communication completed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``test_any()`` returns whether at least one activity of the set has completed, or -1.
+
+.. tabs::
+
+   .. example-tab:: examples/cpp/comm-testany/s4u-comm-testany.cpp
+
+      See also :cpp:func:`simgrid::s4u::Comm::test_any()`.
+
+
 .. _s4u_ex_execution:
 
 Executions on the CPU
@@ -770,6 +784,17 @@ This example shows how to retrieve the amount of energy consumed by the CPU duri
 
    .. example-tab:: examples/c/energy-exec/energy-exec.c
 
+Virtual machines consumption
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example is very similar to the previous one, adding VMs to the picture.
+
+.. tabs::
+
+   .. example-tab:: examples/cpp/energy-vm/s4u-energy-vm.cpp
+
+   .. example-tab:: examples/c/energy-vm/energy-vm.c
+
 Wired network energy consumption
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1170,7 +1195,7 @@ The model-checker can be used to exhaustively search for issues in the tested ap
 mode is rather experimental in SimGrid (as of v3.25). We are working on it :)
 
 Failing assert
-^^^^^^^^^^^^^^
+--------------
 
 In this example, two actors send some data to a central server, which asserts that the messages are always received in the same order.
 This is wrong, and the model-checker correctly finds a counter-example to that assertion.

diff --git a/include/simgrid/s4u/Activity.hpp b/include/simgrid/s4u/Activity.hpp
index 4319dcb..639bd51 100644 (file)
--- a/include/simgrid/s4u/Activity.hpp
+++ b/include/simgrid/s4u/Activity.hpp
@@ -103,7 +103,7 @@ public:
   /*! Add a callback fired each time that the activity fails to start because of a veto (e.g., unsolved dependency or no
    * resource assigned) */
   static void on_veto_cb(const std::function<void(Activity&)>& cb) { on_veto.connect(cb); }
-  /*! Add a callback fired when theactivity completes (either normally, cancelled or failed) */
+  /*! Add a callback fired when the activity completes (either normally, cancelled or failed) */
   static void on_completion_cb(const std::function<void(Activity&)>& cb) { on_completion.connect(cb); }
 
   void vetoable_start()

diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp
index 84d9345..9e25315 100644 (file)
--- a/include/simgrid/s4u/Actor.hpp
+++ b/include/simgrid/s4u/Actor.hpp
@@ -251,8 +251,9 @@ public:
    *  If you want to register to the termination of a given actor, use this_actor::on_exit() instead.*/
   static void on_destruction_cb(const std::function<void(Actor const&)>& cb) { on_destruction.connect(cb); }
 
-  /** Create an actor from a std::function<void()>.
-   *  If the actor is restarted, it gets a fresh copy of the function. */
+  /** Create an actor from a @c std::function<void()>.
+   *  If the actor is restarted, it gets a fresh copy of the function. 
+   *  @verbatim embed:rst:inline See the :ref:`example <s4u_ex_actors_create>`. @endverbatim */
   static ActorPtr create(const std::string& name, s4u::Host* host, const std::function<void()>& code);
   /** Create an actor, but don't start it yet.
    *
@@ -277,7 +278,8 @@ public:
 
   ActorPtr start(const std::function<void()>& code, std::vector<std::string> args);
 
-  /** Create an actor from a callable thing. */
+  /** Create an actor from a callable thing. 
+   *  @verbatim embed:rst:inline See the :ref:`example <s4u_ex_actors_create>`. @endverbatim */
   template <class F> static ActorPtr create(const std::string& name, s4u::Host* host, F code)
   {
     return create(name, host, std::function<void()>(std::move(code)));
@@ -285,7 +287,8 @@ public:
 
   /** Create an actor using a callable thing and its arguments.
    *
-   * Note that the arguments will be copied, so move-only parameters are forbidden */
+   * Note that the arguments will be copied, so move-only parameters are forbidden. 
+   * @verbatim embed:rst:inline See the :ref:`example <s4u_ex_actors_create>`. @endverbatim */
 
   template <class F, class... Args,
             // This constructor is enabled only if the call code(args...) is valid:
@@ -298,7 +301,8 @@ public:
     return create(name, host, std::bind(std::move(code), std::move(args)...));
   }
 
-  /** Create actor from function name and a vector of strings as arguments. */
+  /** Create actor from function name and a vector of strings as arguments. 
+   *  @verbatim embed:rst:inline See the :ref:`example <s4u_ex_actors_create>`. @endverbatim */
   static ActorPtr create(const std::string& name, s4u::Host* host, const std::string& function,
                          std::vector<std::string> args);
 

diff --git a/include/simgrid/s4u/Comm.hpp b/include/simgrid/s4u/Comm.hpp
index b900be0..5c746e1 100644 (file)
--- a/include/simgrid/s4u/Comm.hpp
+++ b/include/simgrid/s4u/Comm.hpp
@@ -66,7 +66,7 @@ public:
   static void on_send_cb(const std::function<void(Comm const&)>& cb) { on_send.connect(cb); }
   static void on_recv_cb(const std::function<void(Comm const&)>& cb) { on_recv.connect(cb); }
   static void on_start_cb(const std::function<void(Comm const&)>& cb) { on_start.connect(cb); }
-  static void on_completion_cb(const std::function<void(Comm const&)>& cb) { on_completion.connect(cb); }
+  static void on_completion_cb(const std::function<void(Activity const&)>& cb) { on_completion.connect(cb); }
 #ifndef DOXYGEN
   /* FIXME signals should be private */
   static xbt::signal<void(Comm const&)> on_send;

diff --git a/include/simgrid/s4u/Engine.hpp b/include/simgrid/s4u/Engine.hpp
index 43be0eb..f989f39 100644 (file)
--- a/include/simgrid/s4u/Engine.hpp
+++ b/include/simgrid/s4u/Engine.hpp
@@ -60,13 +60,17 @@ public:
   void load_platform(const std::string& platf) const;
   void seal_platform() const;
 
+  /** @verbatim embed:rst:inline Bind an actor name that could be found in :ref:`pf_tag_actor` tag to a function taking classical argc/argv parameters. See the :ref:`example <s4u_ex_actors_create>`. @endverbatim */
   void register_function(const std::string& name, const std::function<void(int, char**)>& code);
+  /** @verbatim embed:rst:inline Bind an actor name that could be found in :ref:`pf_tag_actor` tag to a function taking a vector of strings as a parameter. See the :ref:`example <s4u_ex_actors_create>`. @endverbatim */
   void register_function(const std::string& name, const std::function<void(std::vector<std::string>)>& code);
   void register_function(const std::string& name, const kernel::actor::ActorCodeFactory& factory);
 
+  /** @verbatim embed:rst:inline Provide a default function to be used when the name used in a :ref:`pf_tag_actor` tag was not binded with ``register_function`` nor ``register_actor``. @endverbatim */
   void register_default(const std::function<void(int, char**)>& code);
   void register_default(const kernel::actor::ActorCodeFactory& factory);
 
+  /** @verbatim embed:rst:inline Bind an actor name that could be found in :ref:`pf_tag_actor` tag to a class name passed as a template parameter. See the :ref:`example <s4u_ex_actors_create>`. @endverbatim */
   template <class F> void register_actor(const std::string& name)
   {
     kernel::actor::ActorCodeFactory code_factory = [](std::vector<std::string> args) {
@@ -77,6 +81,7 @@ public:
     };
     register_function(name, code_factory);
   }
+  /** @verbatim embed:rst:inline Bind an actor name that could be found in :ref:`pf_tag_actor` tag to a function name passed as a parameter. See the :ref:`example <s4u_ex_actors_create>`. @endverbatim */
   template <class F> void register_actor(const std::string& name, F code)
   {
     kernel::actor::ActorCodeFactory code_factory = [code](std::vector<std::string> args) {
@@ -88,6 +93,7 @@ public:
   /** If non-null, the provided set will be filled with all activities that fail to start because of a veto */
   void track_vetoed_activities(std::set<Activity*>* vetoed_activities) const;
 
+  /** @verbatim embed:rst:inline Load a deployment file. See:ref:`deploy` and the :ref:`example <s4u_ex_actors_create>`. @endverbatim */
   void load_deployment(const std::string& deploy) const;
 
 protected:

diff --git a/include/simgrid/s4u/Host.hpp b/include/simgrid/s4u/Host.hpp
index 000ed7e..9ed6cc2 100644 (file)
--- a/include/simgrid/s4u/Host.hpp
+++ b/include/simgrid/s4u/Host.hpp
@@ -152,13 +152,19 @@ public:
   /** @brief Get the peak computing speed in flops/s at the current pstate, NOT taking the external load into account.
    *
    *  The amount of flops per second available for computing depends on several things:
-   *    - The current pstate determines the maximal peak computing speed (use @ref get_pstate_speed() to retrieve the
-   *      computing speed you would get at another pstate)
-   *    - If you declared an external load (with @ref set_speed_profile()), you must multiply the
-   * result of get_speed() by get_available_speed() to retrieve what a new computation would get.
+   *    - The current pstate determines the maximal peak computing speed (use
+   *      @verbatim embed:rst:inline :cpp:func:`get_pstate_speed() <simgrid::s4u::Host::get_pstate_speed>` @endverbatim
+   *      to retrieve the computing speed you would get at another pstate)
+   *    - If you declared an external load (with
+   *      @verbatim embed:rst:inline :cpp:func:`set_speed_profile() <simgrid::s4u::Host::set_speed_profile>`
+   * @endverbatim ), you must multiply the result of
+   *      @verbatim embed:rst:inline :cpp:func:`get_speed() <simgrid::s4u::Host::get_speed>` @endverbatim by
+   *      @verbatim embed:rst:inline :cpp:func:`get_available_speed() <simgrid::s4u::Host::get_available_speed>`
+   * @endverbatim to retrieve what a new computation would get.
    *
    *  The remaining speed is then shared between the executions located on this host.
-   *  You can retrieve the amount of tasks currently running on this host with @ref get_load().
+   *  You can retrieve the amount of tasks currently running on this host with
+   *  @verbatim embed:rst:inline :cpp:func:`get_load() <simgrid::s4u::Host::get_load>` @endverbatim .
    *
    *  The host may have multiple cores, and your executions may be able to use more than a single core.
    *
@@ -167,7 +173,8 @@ public:
   double get_speed() const;
   /** @brief Get the available speed ratio, between 0 and 1.
    *
-   * This accounts for external load (see @ref set_speed_profile()).
+   * This accounts for external load (see
+   * @verbatim embed:rst:inline :cpp:func:`set_speed_profile() <simgrid::s4u::Host::set_speed_profile>` @endverbatim ).
    */
   double get_available_speed() const;
 

diff --git a/include/xbt/dynar.h b/include/xbt/dynar.h
index 817b737..8ef3368 100644 (file)
--- a/include/xbt/dynar.h
+++ b/include/xbt/dynar.h
@@ -18,7 +18,8 @@ SG_BEGIN_DECL
 /** @brief Dynar data type (opaque type)
  *
  * These are the SimGrid version of the DYNamically sized ARays, which all C programmer recode one day or another.
- * For performance concerns, the content of dynars must be homogeneous (in contrary to @ref xbt_dict_t).
+ * For performance concerns, the content of dynars must be homogeneous (in contrary to
+ * @verbatim embed:rst:inline :cpp:type:`xbt_dict_t` @endverbatim ).
  * You thus have to provide the function which will be used to free the content at
  * structure creation (of type void_f_pvoid_t).
  */

diff --git a/src/bindings/python/simgrid_python.cpp b/src/bindings/python/simgrid_python.cpp
index 0bf8598..47c669a 100644 (file)
--- a/src/bindings/python/simgrid_python.cpp
+++ b/src/bindings/python/simgrid_python.cpp
@@ -502,7 +502,7 @@ PYBIND11_MODULE(simgrid, m)
               }
             });
           },
-          py::call_guard<py::gil_scoped_release>(), "Create an actor from a function or an object.")
+          py::call_guard<py::gil_scoped_release>(), "Create an actor from a function or an object. See the :ref:`example <s4u_ex_actors_create>`.")
       .def_property(
           "host", &Actor::get_host,
           [](Actor* a, Host* h) {

diff --git a/src/s4u/s4u_Host.cpp b/src/s4u/s4u_Host.cpp
index 17b7f43..aa56f77 100644 (file)
--- a/src/s4u/s4u_Host.cpp
+++ b/src/s4u/s4u_Host.cpp
@@ -28,10 +28,12 @@ template class xbt::Extendable<s4u::Host>;
 
 namespace s4u {
 
+#ifndef DOXYGEN
 xbt::signal<void(Host&)> Host::on_creation;
 xbt::signal<void(Host const&)> Host::on_destruction;
 xbt::signal<void(Host const&)> Host::on_state_change;
 xbt::signal<void(Host const&)> Host::on_speed_change;
+#endif
 
 Host* Host::set_cpu(kernel::resource::CpuImpl* cpu)
 {