From ee8a1573204f76b16b9fb711608447aabee55696 Mon Sep 17 00:00:00 2001
From: Vasile Vilvoiu <vasi@vilvoiu.ro>
Date: Wed, 21 Jul 2021 21:14:30 +0300
Subject: Added header file comments for classes and methods.

Renamed all factory methods to ::Build().
---
 src/value-map.hpp | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 59 insertions(+), 5 deletions(-)

(limited to 'src/value-map.hpp')

diff --git a/src/value-map.hpp b/src/value-map.hpp
index 2f32d92..3d5a160 100644
--- a/src/value-map.hpp
+++ b/src/value-map.hpp
@@ -14,17 +14,28 @@
 #include <vector>
 #include <complex>
 
+/**
+ * Type of supported value maps
+ */
 enum class ValueMapType {
     kLinear,
     kDecibel
 };
 
+/**
+ * Base value map class
+ */
 class ValueMap {
 protected:
-    const double lower_;
-    const double upper_;
-    const std::string unit_;
+    const double lower_;        /* lower bound, in whatever unit */
+    const double upper_;        /* upper bound, in whatever unit */
+    const std::string unit_;    /* unit */
 
+    /**
+     * @param lower_ Lower bound of scale.
+     * @param upper Upper bound of scale.
+     * @param unit Unit.
+     */
     ValueMap(double lower_, double upper, const std::string& unit);
 
 public:
@@ -32,26 +43,69 @@ public:
 
     auto GetLowerBound() const { return lower_; }
     auto GetUpperBound() const { return upper_; }
+    virtual std::string GetUnit() const;
 
+    /**
+     * Maps all values to [0..1], based on bounds.
+     * @param input Input values in whatever unit.
+     * @return Output corresponding values, in the [0..1] domain.
+     */
     virtual RealWindow Map(const RealWindow& input) = 0;
-    virtual std::string GetUnit() const;
 
+    /**
+     * Build a fitting value map.
+     * @param type One of ValueMapType.
+     * @param lower Lower bound.
+     * @param upper Upper bound.
+     * @param unit Unit.
+     * @return New ValueMap instance.
+     */
     static std::unique_ptr<ValueMap> Build(ValueMapType type, double lower, double upper, std::string unit);
 };
 
+/**
+ * Specialization for linear maps.
+ */
 class LinearValueMap : public ValueMap {
 public:
     LinearValueMap(double lower, double upper, const std::string& unit);
 
+    /**
+     * Linearly map input to output.
+     * @param input Input values in whatever unit.
+     * @return Output corresponding values, in the [0..1] domain.
+     *
+     * NOTE: Transformation is
+     *       x : [lower_ .. upper_] ---> [0 .. 1].
+     */
     RealWindow Map(const RealWindow& input) override;
 };
 
+/**
+ * Specialization for logarithmic maps in some dB unit
+ */
 class DecibelValueMap : public ValueMap {
 public:
-    /* unit parameter should NOT contain "dB" prefix */
+    /**
+     * @param lower Lower bound.
+     * @param upper Upper bound.
+     * @param unit Unit without dB prefix.
+     */
     DecibelValueMap(double lower, double upper, const std::string& unit);
 
+    /**
+     * Logarithmically map input to output.
+     * @param input Input values in whatever unit.
+     * @return Output corresponding values, in the [0..1] domain.
+     *
+     * NOTE: Transformation is
+     *       20*log10(x) : [lower_ .. upper_] ---> [0 .. 1].
+     */
     RealWindow Map(const RealWindow& input) override;
+
+    /**
+     * @return Unit with dB prefix.
+     */
     std::string GetUnit() const override;
 };
 
-- 
cgit v1.2.3