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/configuration.hpp | 95 ++++++++++++++++++++++++++++++---------------------
 1 file changed, 57 insertions(+), 38 deletions(-)

(limited to 'src/configuration.hpp')

diff --git a/src/configuration.hpp b/src/configuration.hpp
index f6fff18..7659237 100644
--- a/src/configuration.hpp
+++ b/src/configuration.hpp
@@ -17,48 +17,52 @@
 #include <optional>
 #include <tuple>
 
+/**
+ * Configuration God object. This parses program arguments into usable,
+ * structured configuration options.
+ */
 class Configuration {
 private:
     std::optional<std::string> input_filename_;
     std::optional<std::string> output_filename_;
-    bool dump_to_stdout_;
-
-    std::size_t block_size_;
-    double rate_;
-    DataType datatype_;
-    bool has_complex_input_;
-    double prescale_factor_;
-
-    std::size_t fft_width_;
-    std::size_t fft_stride_;
-    WindowFunctionType window_function_;
-    std::size_t average_count_;
-    bool alias_negative_;
-
-    bool no_resampling_;
-    std::size_t width_;
-    double min_freq_;
-    double max_freq_;
-    ValueMapType scale_type_;
-    std::string scale_unit_;
+    bool dump_to_stdout_;                   /* true if output PNG image must go to stdout */
+
+    std::size_t block_size_;                /* group read values in blocks of block_size_ items */
+    double rate_;                           /* sampling rate of signal, in Hz */
+    DataType datatype_;                     /* input data type (does not cover complex/real discrimination) */
+    bool has_complex_input_;                /* true if input is complex */
+    double prescale_factor_;                /* value to scale input with before applying other transformations */
+
+    std::size_t fft_width_;                 /* size of FFT window, in values */
+    std::size_t fft_stride_;                /* stride of FFT window, in values */
+    WindowFunctionType window_function_;    /* window function to apply before FFT */
+    std::size_t average_count_;             /* number of windows to average for each displayed window */
+    bool alias_negative_;                   /* alias negative frequencies to positive */
+
+    bool no_resampling_;                    /* do not perform resampling; if true, width_ is meaningless */
+    std::size_t width_;                     /* width of resampled output window, in values or pixels */
+    double min_freq_;                       /* lower bound of displayed frewquency band */
+    double max_freq_;                       /* upper bound of displayed frewquency band */
+    ValueMapType scale_type_;               /* type of scale used on FFT output */
+    std::string scale_unit_;                /* unit of the scale (just the text) */
     double scale_lower_bound_;
     double scale_upper_bound_;
-    ColorMapType color_map_;
-    sf::Color color_map_custom_color_;
-    sf::Color background_color_;
-    sf::Color foreground_color_;
-    bool has_axes_;
-    bool has_legend_;
-    bool is_horizontal_;
-    bool print_input_;
-    bool print_fft_;
-    bool print_output_;
-
-    bool live_;
-    std::size_t count_;
-    std::string title_;
-
-    bool has_live_window_;
+    ColorMapType color_map_;                /* color map to apply to scaled output */
+    sf::Color color_map_custom_color_;      /* custom color for color map (where applicable) */
+    sf::Color background_color_;            /* background color of rendered output */
+    sf::Color foreground_color_;            /* foreground color of rendered output (text, axes etc) */
+    bool has_axes_;                         /* render axes */
+    bool has_legend_;                       /* render legend */
+    bool is_horizontal_;                    /* flows from left to right, instead of top to bottom */
+    bool print_input_;                      /* debug printing of input */
+    bool print_fft_;                        /* debug printing of FFT values */
+    bool print_output_;                     /* debug printing of output */
+
+    bool live_;                             /* whether we have live output or not */
+    std::size_t count_;                     /* number of output windows to display in spectrogoram */
+    std::string title_;                     /* window title */
+
+    bool has_live_window_;                  /* display a live plot of the current FFT window */
 
     std::size_t margin_size_;
     std::size_t live_margin_size_;
@@ -69,15 +73,30 @@ private:
 
     Configuration();
 
+    /**
+     * Translate a hex color to a sf::Color.
+     * @param str RGB/RGBA hex color code.
+     * @return Color.
+     */
     static sf::Color StringToColor(const std::string& str);
 
+    /**
+     * Parse a scale string.
+     * @param str Scale string.
+     * @return Optional bounds and unit string.
+     */
     using OptionalBound = std::optional<double>;
     using ScaleProperties = std::tuple<OptionalBound, OptionalBound, std::string>;
     static ScaleProperties StringToScale(const std::string& str);
 
 public:
-    /* parse command line arguments and return a configuration object */
-    static std::tuple<Configuration, int, bool> FromArgs(int argc, char **argv);
+    /**
+     * Parse command line arguments and return a configuration object.
+     * @param argc Argument strings.
+     * @param argv Argument count.
+     * @return New Configuration object instance.
+     */
+    static std::tuple<Configuration, int, bool> Build(int argc, char **argv);
 
     /* generic getters */
     Configuration GetForLive() const;
-- 
cgit v1.2.3