Fix a bunch of issues with the documentation

Broken links, undocumented symbols, examples that were moved around,
undocumented examples...

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index be046e3..3cf6cdb 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -187,7 +187,7 @@ communications ongoing.  First, you have to declare a vector in which
 we will store the ongoing communications. It is also useful to have a
 vector of mailboxes.
 
-.. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
+.. literalinclude:: ../../examples/s4u/comm-waitall/s4u-comm-waitall.cpp
    :language: c++
    :start-after: init-begin
    :end-before: init-end
@@ -199,7 +199,7 @@ Finally, the actor waits for the completion of all of them at once
 with 
 :cpp:func:`s4u::Comm::wait_all() <simgrid::s4u::Comm::wait_all>`.  
      
-.. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
+.. literalinclude:: ../../examples/s4u/comm-waitall/s4u-comm-waitall.cpp
    :language: c++
    :start-after: put-begin
    :end-before: put-end
@@ -317,7 +317,7 @@ announced (it waits until both :cpp:func:`put() <simgrid::s4u::Mailbox::put()>`
 and :cpp:func:`get() <simgrid::s4u::Mailbox::get()>` are posted). 
 In TCP, since you establish connections beforehand, the data starts to
 flow as soon as the sender posts it, even if the receiver did not post
-its :cpp:func:`recv() <simgrid::s4u::Mailbox::recv()>` yet. 
+its :cpp:func:`put() <simgrid::s4u::Mailbox::put()>` yet. 
 
 To model this in SimGrid, you can declare a specific receiver to a
 given mailbox (with the function 
@@ -444,6 +444,7 @@ Creating actors
 
    .. group-tab:: C
 
+      .. autodoxymethod:: sg_actor_create(const char *name, sg_host_t host, xbt_main_func_t code, int argc, const char *const *argv)
       .. autodoxymethod:: sg_actor_init(const char *name, sg_host_t host)
       .. autodoxymethod:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, const char *const *argv)
 
@@ -635,7 +636,7 @@ Querying info
       .. autodoxymethod:: simgrid::s4u::this_actor::is_maestro()
 
       .. autodoxymethod:: simgrid::s4u::this_actor::get_host()
-      .. autodoxymethod:: simgrid::s4u::this_actor::set_host(simgrid::s4u::Host *new_host)
+      .. autodoxymethod:: simgrid::s4u::this_actor::set_host(Host *new_host)
 
    .. group-tab:: Python
 
@@ -667,6 +668,10 @@ Suspending and resuming
       .. autofunction:: simgrid.this_actor.suspend
       .. autofunction:: simgrid.this_actor.yield_
 
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_actor_yield()
+
 Logging messages
 ----------------
 
@@ -724,7 +729,10 @@ the execution, or start an asynchronous activity.
 
    .. group-tab:: C
 
-      .. autodoxymethod:: sg_actor_self_execute(double flops)
+      .. autodoxymethod:: sg_actor_execute(double flops)
+      .. autodoxymethod:: sg_actor_execute_with_priority(double flops, double priority)
+      .. autodoxymethod:: sg_actor_exec_init(double computation_amount)
+      .. autodoxymethod:: sg_actor_exec_async(double computation_amount)
 
 Exiting
 -------
@@ -769,9 +777,12 @@ Initialization
       .. autodoxymethod:: simgrid::s4u::Engine::load_platform
       .. autodoxymethod:: simgrid::s4u::Engine::register_actor(const std::string &name)
       .. autodoxymethod:: simgrid::s4u::Engine::register_actor(const std::string &name, F code)
-      .. autodoxymethod:: simgrid::s4u::Engine::register_default(void(*code)(int, char **))
-      .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, void(*code)(std::vector< std::string >))
-      .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, void(*code)(int, char **))
+      .. autodoxymethod:: simgrid::s4u::Engine::register_default(const std::function< void(int, char **)> &code)
+      .. autodoxymethod:: simgrid::s4u::Engine::register_default(const kernel::actor::ActorCodeFactory &factory)
+
+      .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, const std::function< void(int, char **)> &code)
+      .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, const std::function< void(std::vector< std::string >)> &code)
+      .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, const kernel::actor::ActorCodeFactory &factory)
 
    .. group-tab:: Python
    
@@ -917,6 +928,14 @@ Basic management
 
       .. automethod:: simgrid.Mailbox.by_name
 
+      .. code-block:: C
+
+         #include <simgrid/s4u/mailbox.h>
+      
+      .. autodoxymethod:: sg_mailbox_by_name(const char *alias)
+
+   .. group-tab:: C
+
 Querying info
 -------------
 
@@ -949,6 +968,12 @@ Sending data
       .. automethod:: simgrid.Mailbox.put
       .. automethod:: simgrid.Mailbox.put_async
 
+   .. group-tab: C
+
+      .. autodoxymethod:: sg_mailbox_put(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes)
+      .. autodoxymethod:: sg_mailbox_put_init(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes)
+      .. autodoxymethod:: sg_mailbox_put_async(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes)
+
 
 Receiving data
 --------------
@@ -961,7 +986,7 @@ Receiving data
       .. autodoxymethod:: simgrid::s4u::Mailbox::front
       .. autodoxymethod:: simgrid::s4u::Mailbox::get()
       .. autodoxymethod:: simgrid::s4u::Mailbox::get(double timeout)
-      .. autodoxymethod:: simgrid::s4u::Mailbox::get_async(void **data)
+      .. autodoxymethod:: simgrid::s4u::Mailbox::get_async(T **data)
       .. autodoxymethod:: simgrid::s4u::Mailbox::get_init()
       .. autodoxymethod:: simgrid::s4u::Mailbox::iprobe(int type, bool(*match_fun)(void *, void *, kernel::activity::CommImpl *), void *data)
       .. autodoxymethod:: simgrid::s4u::Mailbox::listen
@@ -973,6 +998,9 @@ Receiving data
 
    .. group-tab:: C
 
+      .. autodoxymethod:: sg_mailbox_get(sg_mailbox_t mailbox)
+      .. autodoxymethod:: sg_mailbox_get_async(sg_mailbox_t mailbox, void **data)
+      .. autodoxymethod:: sg_mailbox_get_name(const_sg_mailbox_t mailbox)
       .. autodoxymethod:: sg_mailbox_listen(const char *alias)
 
 Receiving actor
@@ -1169,7 +1197,7 @@ User data and properties
 
       .. autodoxymethod:: simgrid::s4u::Host::get_properties() const
       .. autodoxymethod:: simgrid::s4u::Host::get_property(const std::string &key) const
-      .. autodoxymethod:: simgrid::s4u::Host::set_properties(const std::map< std::string, std::string > &properties)
+      .. autodoxymethod:: simgrid::s4u::Host::set_properties(const std::unordered_map< std::string, std::string > &properties)
       .. autodoxymethod:: simgrid::s4u::Host::set_property(const std::string &key, const std::string &value)
 
    .. group-tab:: C
@@ -1187,7 +1215,7 @@ Retrieving components
 
    .. group-tab:: C++
 
-      .. autodoxymethod:: simgrid::s4u::Host::add_disk(const Disk* disk)
+      .. autodoxymethod:: simgrid::s4u::Host::add_disk(const Disk *disk)
       .. autodoxymethod:: simgrid::s4u::Host::get_actor_count() const
       .. autodoxymethod:: simgrid::s4u::Host::get_all_actors() const
       .. autodoxymethod:: simgrid::s4u::Host::get_disks() const
@@ -1377,8 +1405,8 @@ Modifying characteristics
 
    .. group-tab:: C
 
-      .. autodoxymethod:: sg_link_set_bandwidth(const_sg_link_t link, double value)
-      .. autodoxymethod:: sg_link_set_latency(const_sg_link_t link, double value)
+      .. autodoxymethod:: sg_link_set_bandwidth(sg_link_t link, double value)
+      .. autodoxymethod:: sg_link_set_latency(sg_link_t link, double value)
 
 User data and properties
 ------------------------
@@ -1790,7 +1818,6 @@ Querying info
       .. autodoxymethod:: simgrid::s4u::Comm::set_src_data(void *buff)
       .. autodoxymethod:: simgrid::s4u::Comm::set_src_data(void *buff, size_t size)
       .. autodoxymethod:: simgrid::s4u::Comm::set_src_data_size(size_t size)
-      .. autodoxymethod:: simgrid::s4u::Comm::set_tracing_category(const std::string &category)
 
 Life cycle
 ----------
@@ -1824,8 +1851,7 @@ Signals
    .. group-tab:: C++
 
       .. autodoxyvar:: simgrid::s4u::Comm::on_completion
-      .. autodoxyvar:: simgrid::s4u::Comm::on_receiver_start
-      .. autodoxyvar:: simgrid::s4u::Comm::on_sender_start
+      .. autodoxyvar:: simgrid::s4u::Comm::on_start
 
 .. _API_s4u_Exec:
 

diff --git a/examples/README.rst b/examples/README.rst
index 735ca8f..bb40b47 100644 (file)
--- a/examples/README.rst
+++ b/examples/README.rst
@@ -78,7 +78,7 @@ Starting and Stopping Actors
 
           This example shows how to attach a callback to:
 
-          - the end of a specific actor: :cpp:func:`simgrid::s4u::this_actor::on_exit()`
+          - the end of a specific actor: :cpp:func:`simgrid::s4u::Actor::on_exit()`
           - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()`
           - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()`
 
@@ -95,7 +95,7 @@ Starting and Stopping Actors
        .. example-tab:: examples/s4u/actor-kill/s4u-actor-kill.cpp
 
           See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`,
-          :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::this_actor::on_exit`.
+          :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::Actor::on_exit`.
 
        .. example-tab:: examples/python/actor-kill/actor-kill.py
 
@@ -282,6 +282,18 @@ Activities: what Actors do
 Communications on the Network
 -----------------------------
 
+  - **Basic communications:**
+    This simple example just sends one message back and forth.
+    The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to 
+    the simulators (as detailed in Section :ref:`options`).
+
+    .. tabs::
+
+       .. example-tab:: examples/s4u/comm-pingpong/s4u-comm-pingpong.cpp
+
+       .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c
+
+
  - **Basic asynchronous communications:**
    Illustrates how to have non-blocking communications, that are
    communications running in the background leaving the process free
@@ -301,6 +313,15 @@ Communications on the Network
 
          See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm__wait()`.
 
+ - **Waiting communications with timeouts:**
+   This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication.
+
+   .. tabs::
+
+      .. example-tab:: examples/s4u/comm-waituntil/s4u-comm-waituntil.cpp
+
+         See also :cpp:func:`simgrid::s4u::Mailbox::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`.
+
  - **Suspending communications:**
    The ``suspend()`` and ``resume()`` functions allow to block the
    progression of a given communication for a while and then unblock it.
@@ -532,13 +553,20 @@ Classical synchronization objects
 
       .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp
 
- - **Condition variable:**
+ - **Condition variable: basic usage**
    Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
 
    .. tabs::
 
       .. example-tab:: examples/s4u/synchro-condition-variable/s4u-synchro-condition-variable.cpp
 
+ - **Condition variable: timeouts**
+   Shows how to specify timeouts when blocking on condition variables.
+
+   .. tabs::
+
+      .. example-tab:: examples/s4u/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp
+
  - **Mutex:**
    Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
 
@@ -553,6 +581,8 @@ Classical synchronization objects
 
       .. example-tab:: examples/s4u/synchro-semaphore/s4u-synchro-semaphore.cpp
 
+      .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
+
 =============================
 Interacting with the Platform
 =============================
@@ -796,17 +826,6 @@ Larger SimGrid Examplars
 This section contains application examples that are somewhat larger
 than the previous examples.
 
-  - **Ping Pong:**
-    This simple example just sends one message back and forth.
-    The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to 
-    the simulators (as detailed in Section :ref:`options`).
-
-    .. tabs::
-
-       .. example-tab:: examples/s4u/app-pingpong/s4u-app-pingpong.cpp
-
-       .. example-tab:: examples/c/app-pingpong/app-pingpong.c
-
   - **Token ring:**
     Shows how to implement a classical communication pattern, where a
     token is exchanged along a ring to reach every participant.

diff --git a/include/simgrid/s4u/Engine.hpp b/include/simgrid/s4u/Engine.hpp
index f92b9a3..8e7a74b 100644 (file)
--- a/include/simgrid/s4u/Engine.hpp
+++ b/include/simgrid/s4u/Engine.hpp
@@ -48,18 +48,20 @@ public:
 
   void load_platform(const std::string& platf) const;
 
+#ifndef DOXYGEN
   XBT_ATTRIB_DEPRECATED_v330("Please change the return code of your actors to void") void register_function(
       const std::string& name, int (*code)(int, char**));
+  XBT_ATTRIB_DEPRECATED_v330("Please change the return code of your actors to void") void register_default(
+      int (*code)(int, char**));
+#endif
 
   void register_function(const std::string& name, const std::function<void(int, char**)>& code);
   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);
 
-  XBT_ATTRIB_DEPRECATED_v330("Please change the return code of your actors to void") void register_default(
-      int (*code)(int, char**));
   void register_default(const std::function<void(int, char**)>& code);
   void register_default(const kernel::actor::ActorCodeFactory& factory);
 
-  void register_function(const std::string& name, const kernel::actor::ActorCodeFactory& factory);
   template <class F> void register_actor(const std::string& name)
   {
     kernel::actor::ActorCodeFactory code_factory = [](std::vector<std::string> args) {