SettableClock: Extended documentation.

Author: levy

src/inet/clock/model/SettableClock.h

@@ -13,6 +13,13 @@
 
 namespace inet {
 
+/**
+ * @brief Clock that can be stepped (set) and whose effective oscillator compensation can be changed at runtime.
+ *
+ * Stepping creates a discontinuity in C(t) (the simulation time to clock time mapping). Conversions at the step instant
+ * follow the lower/upper-bound conventions documented by ~IClock. When stepping forward, previously scheduled events
+ * might become overdue; the behavior is controlled by a module parameter.
+ */
 class INET_API SettableClock : public OscillatorBasedClock, public IScriptable
 {
   protected:
@@ -39,8 +46,15 @@ class INET_API SettableClock : public OscillatorBasedClock, public IScriptable
     virtual ppm getOscillatorCompensation() const override { return oscillatorCompensation; }
 
     /**
-     * Sets the clock time immediately to the given value. Greater than 1 oscillator
-     * compensation factor means the clock measures time faster.
+     * @brief Step the clock to a new time and (optionally) update oscillator compensation.
+     *
+     * Effects (executed atomically at the current simulation time s = now):
+     *  - The clock origin is moved to s, and the new origin clock time is set to the given time.
+     *  - The oscillator compensation factor is updated to the provided ppm value.
+     *  - If resetOscillator is true, the phase/origin of the driving oscillator is also reset.
+     *  - Pending events affected by the step are handled according to defaultOverdueClockEventHandlingMode.
+     *
+     *  Backward steps are allowed and may affect modules assuming monotone clock progression.
      */
     virtual void setClockTime(clocktime_t time, ppm oscillatorCompensation, bool resetOscillator);
 };

src/inet/clock/model/SettableClock.ned

@@ -10,11 +10,19 @@ package inet.clock.model;
 import inet.clock.contract.IClock;
 
 //
-// Models a clock which can be set to a different clock time. The clock time
-// can be set from C++ or using a <set-clock module="..." time="..."/> command
-// in a `ScenarioManager` script.
+// This module represents a settable (step-able) clock with adjustable oscillator compensation.
 //
-// @see ~ScenarioManager
+// Extends ~OscillatorBasedClock with the ability to step the clock time to an explicitly provided value (forward or
+// backward) and to apply a new oscillator-compensation factor. Stepping the clock introduces a discontinuity in the
+// clock-time mapping. Overdue events (whose target time becomes < now after the step) can be handled in three ways:
+//  - execute : run overdue events immediately (in order)
+//  - skip    : drop/cancel overdue events
+//  - error   : terminate simulation and report an error
+//
+// The clock time can be set from C++ or by a clock servo module or by a time synchronization protocol or using a
+// <set-clock module="..." time="..."/> command in a `ScenarioManager` script.
+//
+// @see ~IClockServo, ~ScenarioManager
 //
 module SettableClock extends OscillatorBasedClock
 {