doc: Document time header

include/core/time.h

@@ -3,19 +3,41 @@
 namespace kku
 {
 
+/// microsec
+///
+/// Primitive alias representing microseconds, which
+/// is the main time measure in-game.
+/// 1 second is 1000000 microseconds.
 using microsec = long long;
 
+/// TimeRange
+///
+/// Object representing a section of time.
+/// To ensure order safety use
+/// static produceValidated function.
 struct TimeRange
 {
     const microsec begin = 0;
     const microsec end = 0;
 
-    constexpr inline explicit TimeRange() noexcept : begin(0), end(0) {}
+    constexpr inline explicit TimeRange() noexcept : begin(0), end(0)
+    {
+    }
 
     constexpr inline explicit TimeRange(microsec x, microsec y) noexcept
         : begin(x), end(y)
     {
     }
+
+    /// produceValidated
+    ///
+    /// Creates an object of TimeRange, but
+    /// also makes sure to place begin and end
+    /// in the right order to avoid confusion.
+    static inline TimeRange produceValidated(microsec x, microsec y) noexcept
+    {
+        return (x < y) ? TimeRange(x, y) : TimeRange(y, x);
+    }
 };
 
 } // namespace kku