-/** @brief Get the peak processor speed in flops/s, (under full load (=1.0), at the current pstate)
+/** @brief Get the peak computing speed in flops/s at the current pstate, 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, then this reduces the available computing speed
+ * (see @ref simgrid::surf::Cpu::set_speed_trace())
+ *
+ * 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().
+ *
+ * The host may have multiple cores, and your executions may be able to use more than a single core.