IdealOscillator: Added more documentation to implementation.

Author: levy

src/inet/clock/oscillator/IdealOscillator.h

@@ -13,10 +13,34 @@
 
 namespace inet {
 
+/**
+ * @brief Ideal (uniform) oscillator.
+ *
+ * Provides a strictly periodic tick sequence with constant tick length and no
+ * drift. The computation origin is a simulation time (o ≤ now).
+ *
+ * Mathematical semantics
+ * ----------------------
+ * - Let L := tickLength > 0 be the nominal tick interval (constant).
+ * - Tick instants (relative to origin) are τ_i := i·L, i = 1,2,…  (the origin
+ *   itself is not counted as a tick).
+ * - Tick count from origin for interval Δt ≥ 0: N(Δt) = |{ i : 0 < τ_i ≤ Δt }|
+ *   = floor(Δt / L) (tick exactly at Δt is included; a tick at the origin is
+ *   excluded).
+ * - Minimal interval for n ≥ 0 ticks: I(n) = inf{ Δt ≥ 0 : N(Δt) ≥ n } = n · L
+ *   with I(0) = 0.
+ *
+ * This class implements the ~IOscillator mapping without generating per-tick
+ * events. It is suitable as a reference oscillator for clocks that require a
+ * simple, drift-free timebase.
+ */
 class INET_API IdealOscillator : public OscillatorBase
 {
   protected:
+    /// Computation origin (o ≤ now); tick counting is measured from here.
     simtime_t origin;
+
+    /// Constant tick length L > 0 used for both N(Δt) and I(n).
     simtime_t tickLength;
 
   protected:
@@ -25,15 +49,20 @@ class INET_API IdealOscillator : public OscillatorBase
     virtual void scheduleTickTimer() override;
 
   public:
+    /** @name IOscillator contract */
+    ///@{
     virtual simtime_t getComputationOrigin() const override { return origin; }
+
     virtual simtime_t getNominalTickLength() const override { return tickLength; }
+
     virtual int64_t getNumTicksAtOrigin() const override { return 0; }
 
     virtual int64_t computeTicksForInterval(simtime_t timeInterval) const override;
+
     virtual simtime_t computeIntervalForTicks(int64_t numTicks) const override;
+    ///@}
 };
 
 } // namespace inet
 
 #endif
-

src/inet/clock/oscillator/IdealOscillator.ned

@@ -11,12 +11,26 @@ import inet.clock.base.OscillatorBase;
 import inet.clock.contract.IOscillator;
 
 //
-// Generates ticks periodically with a constant tick length.
+// Ideal strictly periodic oscillator (no drift).
+//
+// Summary
+// -------
+// Provides a constant tick length L and implements the ~IOscillator mappings
+// without generating per-tick events.
+//
+// Semantics
+// ---------
+// - Let o be the computation origin (o ≤ now), and L = tickLength (> 0 unless 0s is used; see below).
+// - Tick instants (relative to origin): τ_k = k·L for k = 1,2,… (tick at origin is not counted).
+// - Mapping functions:
+//     N(Δt) = floor(Δt / L)            // ticks in (0, Δt], Δt ≥ 0
+//     I(n)  = n · L, with I(0) = 0     // minimal Δt for n ticks, n ≥ 0
+//
+// @see ~IOscillator
 //
 simple IdealOscillator extends OscillatorBase like IOscillator
 {
     parameters:
-        double tickLength @unit(s) = default(0s);
+        double tickLength @unit(s) = default(0s); // Constant tick length L. If 0s, the simulation time precision is used; otherwise must be > 0.
         @class(IdealOscillator);
 }
-