+/** @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.
+
+*/