Added header file comments for classes and methods.

Renamed all factory methods to ::Build().

1 files changed, 54 insertions, 10 deletions

diff --git a/src/renderer.hpp b/src/renderer.hpp
index f67596a..1a27276 100644
--- a/src/renderer.hpp
+++ b/src/renderer.hpp
@@ -12,9 +12,6 @@
 #include <vector>
 #include <list>
 
-/* Axis tick */
-typedef std::tuple<double, std::string> AxisTick;
-
 /* Orientation */
 enum class Orientation {
     k90CCW,
@@ -23,19 +20,19 @@ enum class Orientation {
     k180
 };
 
-/*
+/**
  * Spectrogram rendering class
  */
 class Renderer {
 private:
-    const Configuration configuration_;
-    const std::size_t fft_count_;
-    const std::unique_ptr<const ColorMap> color_map_;
+    const Configuration configuration_; /* configuration is cached as it contains multiple settings regarding spacing and sizing */
+    const std::size_t fft_count_;       /* number of windows to render */
+    const std::unique_ptr<const ColorMap> color_map_; /* color map used for rendering */
 
     sf::Font font_;
 
     sf::RenderTexture canvas_;
-    sf::Texture fft_area_texture_;
+    sf::Texture fft_area_texture_;      /* actual spectrogram area */
 
     std::size_t width_;
     std::size_t height_;
@@ -44,15 +41,52 @@ private:
     sf::Transform fft_live_transform_;
     sf::Transform fft_area_transform_;
 
+    /**
+     * First value specifies the position of the tick in the domain [0..1].
+     * Second value is the text of the tick.
+     */
+    using AxisTick = std::tuple<double, std::string>;
+
     std::list<AxisTick> frequency_ticks_;
     std::list<AxisTick> live_ticks_;
 
+    /**
+     * Build an array of ticks with linear spacing.
+     * @param v_min Lowest value on the axis.
+     * @param v_max Highest value on the axis.
+     * @param v_unit Unit of the axis.
+     * @param num_ticks Number of ticks to generate.
+     * @return Array of ticks.
+     */
     [[maybe_unused]] /* need for this method disappeared when fixing #9, might be useful in the future */
     static std::list<AxisTick> GetLinearTicks(double v_min, double v_max, const std::string& v_unit,
                                               unsigned int num_ticks);
+
+    /**
+     * Build an array of nicely spaced ticks.
+     * @param v_min Lowest value on the axis.
+     * @param v_max Highest value on the axis.
+     * @param v_unit Unit of the axis.
+     * @param length_px Length of the scale, in pixels (used for spacing estimation).
+     * @param min_tick_length_px Minimum tick spacing.
+     * @param rotated If true then vertical. Otherwise horizontal.
+     * @return Array of ticks.
+     *
+     * NOTE: This method attempts to find some nice values for the ticks that
+     *       also have sufficient spacing for the text to fit properly.
+     */
     std::list<AxisTick> GetNiceTicks(double v_min, double v_max, const std::string& v_unit,
                                      unsigned int length_px, unsigned int min_tick_length_px, bool rotated);
 
+    /**
+     * Render an axis upon a texture
+     * @param texture Texture to render to.
+     * @param t Transform to use.
+     * @param lhs True if has left-hand side text.
+     * @param orientation One of Orientation.
+     * @param length Length in pixels.
+     * @param ticks Ticks.
+     */
     void RenderAxis(sf::RenderTexture& texture,
                     const sf::Transform& t, bool lhs, Orientation orientation, double length,
                     const std::list<AxisTick>& ticks);
@@ -61,12 +95,22 @@ public:
     Renderer() = delete;
     Renderer(const Configuration& conf, const ColorMap& cmap, const ValueMap& vmap, std::size_t fft_count);
 
-    /* render commands */
+    /**
+     * Render the spectrogram area.
+     * @param memory RGBA memory of the colorized spectrogram.
+     */
     void RenderFFTArea(const std::vector<uint8_t>& memory);
+
+    /**
+     * Render the spectrogram area.
+     * @param history List of RGBA colorized windows.
+     */
     void RenderFFTArea(const std::list<std::vector<uint8_t>>& history);
     std::vector<uint8_t> RenderLiveFFT(const RealWindow& window);
 
-    /* canvas builder */
+    /**
+     * @return The rendered canvas texture.
+     */
     sf::Texture GetCanvas();
 
     /* size getters */