Merge branch 'master' into actor-yield

[simgrid.git] / include / simgrid / chrono.hpp

diff --git a/include/simgrid/chrono.hpp b/include/simgrid/chrono.hpp
index 4395b41..8f5b480 100644 (file)
--- a/include/simgrid/chrono.hpp
+++ b/include/simgrid/chrono.hpp
@@ -1,4 +1,4 @@
-/* Copyright (c) 2016. The SimGrid Team. All rights reserved.          */
+/* Copyright (c) 2016-2017. The SimGrid Team. All rights reserved.          */
 
 /* This program is free software; you can redistribute it and/or modify it
  * under the terms of the license (GNU LGPL) which comes with this package. */
@@ -19,8 +19,26 @@
 
 namespace simgrid {
 
-/** A C++ compatible TrivialClock working with simulated-time */
-struct SimulationClock {
+/** @brief A C++ compatible [TrivialClock](http://en.cppreference.com/w/cpp/concept/TrivialClock) working with simulated-time.
+ *
+ * SimGrid uses `double` for representing the simulated time, where *durations* are expressed in seconds
+ * (with *infinite duration* expressed as a negative value) and
+ * *timepoints* are expressed as seconds from the beginning of the simulation.
+ * In contrast, all the C++ APIs use the much more sensible `std::chrono::duration` and`std::chrono::time_point`.
+ *
+ * This class can be used to build `std::chrono` objects that use simulated time,
+ * using #SimulationClockDuration and #SimulationClockTimePoint.
+ *
+ * This means it is possible to use (since C++14):
+ *
+ * @code{cpp}
+ * using namespace std::chrono_literals;
+ * simgrid::s4u::actor::sleep_for(42s);
+ * @endcode
+ *
+ */
+class SimulationClock {
+public:
   using rep        = double;
   using period     = std::ratio<1>;
   using duration   = std::chrono::duration<rep, period>;