- * An actor may be defined as a code executing in a location (host).
- *
- * All actors should be started from the XML deployment file (using the @link{s4u::Engine::loadDeployment()}),
- * even if you can also start new actors directly.
- * Separating the deployment in the XML from the logic in the code is a good habit as it makes your simulation easier
- * to adapt to new settings.
- *
- * The code that you define for a given actor should be placed in the main method that is virtual.
- * For example, a Worker actor should be declared as follows:
- *
- * \verbatim
+ * You can think of an actor as a process in your distributed application, or as a thread in a multithreaded program.
+ * This is the only component in SimGrid that actually does something on its own, executing its own code.
+ * A resource will not get used if you don't schedule activities on them. This is the code of Actors that create and schedule these activities.
+ *
+ * An actor is located on a (simulated) host, but it can interact
+ * with the whole simulated platform.
+ *
+ * The s4u::Actor API is strongly inspired from the C++11 threads.
+ * The <a href="http://en.cppreference.com/w/cpp/thread">documentation
+ * of this standard</a> may help to understand the philosophy of the S4U
+ * Actors.
+ *
+ * (back to the @ref s4u_api "S4U documentation")
+ *
+ * @section s4u_actor_def Defining the skeleton of an Actor
+ *
+ * %As in the <a href="http://en.cppreference.com/w/cpp/thread">C++11
+ * standard</a>, you can declare the code of your actor either as a
+ * pure function or as an object. It is very simple with functions:
+ *
+ * @code{.cpp}
+ * // Declare the code of your worker
+ * void worker() {
+ * printf("Hello s4u");
+ * simgrid::s4u::this_actor::execute(5*1024*1024); // Get the worker executing a task of 5 MFlops
+ * };
+ *
+ * // From your main or from another actor, create your actor on the host Jupiter
+ * new Actor("worker", simgrid::s4u::Host::by_name("Jupiter"), worker);
+ * @endcode
+ *
+ * But some people prefer to encapsulate their actors in classes and
+ * objects to save the actor state in a cleanly dedicated location.
+ * The syntax is slightly more complicated, but not much.
+ *
+ * @code{.cpp}