/**
-@defgroup XBT_API XBT
+@defgroup XBT_API XBT: SimGrid core toolbox
@brief The core toolbox of SimGrid, containing useful datatypes and friends
*/
/**
-@defgroup TRACE_API TRACE
-@brief Tracing mechanism and its functions.
+@defgroup TRACE_API TRACING
+@brief Gather data about your simulation for later analysis
SimGrid can trace the resource (of hosts and links) utilization using
any of its programming interfaces (MSG, SimDAG and SMPI). This means
parameter in the command line (see \ref outcomes_vizu for details).
*/
+/** @defgroup ROUTING_API Routing: Determining the communication paths
+ @brief Organize the platform to determine the links used by each communication
+
+@section routing_basics Basic Concepts
+
+The purpose of the simgrid::kernel::routing module is to retrieve the
+routing path between two points in a time- and space-efficient manner.
+Indeed, the network model needs both the list of links that the convey
+the created communication, and the summed latency that these links
+represent. This operation is clearly on the critical path of most
+SimGrid simulations.
+
+When defining how the information is routed in the simulated network,
+it is certainly very tempting to use a formalism somehow similar to
+how it is defined on real network. One would have to define the
+routing tables of each routers interconnections sub-networks, just
+like in the real life. Given the daunting amount of configuration
+required, we could complete the information given by the user with
+classical protocols such as BGP and RIP. Many network simulator take
+such configuration as an input, for good reasons.
+
+This is not the way it goes in SimGrid: the network routing is defined
+in a global and compact way instead. This eases the modeling of very
+large systems, and allows highly optimized datastructures and
+algorithms in the simulator. The proposed description mechanism is
+thus much more convinient and efficient. In addition, it is more
+expressive than the classical solution based on forwarding tables on
+each host and router.
+
+The price to pay is that this representation of networks is very
+specific to SimGrid, so you will have to read further to understand
+it, even if you already know how real networks work.
+
+The central notion here are \b Networking \b Zones. NetZones represent
+network areas in which the routing is done in an homogeneous way.
+Conceptually, netzones generalize from the ideas of local networks
+(such as Ethernet switched networks) and Autonomous System. The
+network as a whole is represented as a single hierarchy of netzones,
+meaning that every netzone is part of another netzone (but the \c
+NetRoot, which is the top-level netzone).
+
+The main goal of the routing module is to provide a list of links
+traversed by a given communication and/or a latency to apply. These
+information are then used by the network model to compute the time
+that this communication takes. This information is retrieved by three
+combined algorithms: intra-zone routing, inter-zone routing, and the
+bypass mechanism.
+
+The <b>intra-zone level</b> is naturally handled by the netzones. Each
+netzone have to specify the routing algorithm it uses for that.
+@ref simgrid::kernel::routing::FullZone "FullZone" netzones have complete matrix where matrix(a,b)
+represents the full path (the list of links) between the hosts a and
+b. @ref simgrid::kernel::routing::FloydZone "FloydZone" apply the Floyd-Warshall algorithm to compute the
+paths. @ref simgrid::kernel::routing::ClusterZone "ClusterZone" model classical switched or hub networks,
+where each component is connected through a private link onto a common
+backbone. Many other routing algorithms are provided to model the
+classical needs, but you can naturally define your own routing if the
+provided ones do not fit your needs.
+
+The <b>inter-zone algorithm</b> is used when the communication
+traverses more than one zone. The overall path goes from the source up
+in the netzones' tree, until the first common ancestor zone, and moves
+down to the destination. It crawls the differing netzones on its path
+according to the user-defined inter-zone routes, moving from gateway
+to gateway.
+
+You can also use the <b>bypass mechanism</b> to specify manually some
+shortcuts that directly provide the list of links interconnecting two
+given processes.
+
+@section routing_declaring Declaring a platform
+
+For now, you can only declare a platform from an XML file, but we are
+working to make it possible from the C++ code (or even from bindings
+in other languages). Until then, please head to \ref platform.
+
+*/
/** \defgroup SIMIX_API SIMIX
\brief POSIX-like interface for building simulation
