initial work in updating documentation

analog_input.h

@@ -17,15 +17,18 @@ const int MAX_INPUT = (1 << 10) - 1;  // Max 10 bit analog read resolution.
 const int CALIBRATED_LOW = -566;
 const int CALIBRATED_HIGH = 512;
 
+/**
+ * @brief Class for interacting with analog inputs (CV).
+ */
 class AnalogInput {
    public:
     AnalogInput() {}
     ~AnalogInput() {}
 
     /**
-     * Initializes a analog input object.
+     * @brief Initializes an analog input object.
      *
-     * @param pin gpio pin for the analog input.
+     * @param pin The GPIO pin for the analog input.
      */
     void Init(uint8_t pin) {
         pinMode(pin, INPUT);
@@ -33,8 +36,11 @@ class AnalogInput {
     }
 
     /**
-     * Read the value of the analog input and set instance state.
+     * @brief Reads and processes the analog input.
      *
+     * This method reads the raw value from the ADC, applies the current
+     * calibration, offset, and attenuation/inversion settings. It should be
+     * called regularly in the main loop to update the input's state.
      */
     void Process() {
         old_read_ = read_;
@@ -44,14 +50,38 @@ class AnalogInput {
         if (inverted_) read_ = -read_;
     }
 
-    // Set calibration values.
+    /**
-
+     * @brief Adjusts the low calibration point.
+     *
+     * This is used to fine-tune the mapping of the raw analog input to the output range.
+     *
+     * @param amount The amount to add to the current low calibration value.
+     */
     void AdjustCalibrationLow(int amount) { low_ += amount; }
 
+    /**
+     * @brief Adjusts the high calibration point.
+     *
+     * This is used to fine-tune the mapping of the raw analog input to the output range.
+     *
+     * @param amount The amount to add to the current high calibration value.
+     */
     void AdjustCalibrationHigh(int amount) { high_ += amount; }
 
+    /**
+     * @brief Sets a DC offset for the input.
+     *
+     * @param percent A percentage (e.g., 0.5 for 50%) to shift the signal.
+     */
     void SetOffset(float percent) { offset_ = -(percent)*512; }
 
+    /**
+     * @brief Sets the attenuation (scaling) of the input signal.
+     *
+     * This scales the input signal. A negative percentage will also invert the signal.
+     *
+     * @param percent The attenuation level, typically from 0.0 to 1.0.
+     */
     void SetAttenuation(float percent) {
         low_ = abs(percent) * CALIBRATED_LOW;
         high_ = abs(percent) * CALIBRATED_HIGH;
@@ -59,18 +89,16 @@ class AnalogInput {
     }
 
     /**
-     * Get the current value of the analog input within a range of +/-512.
+     * @brief Get the current processed value of the analog input.
-     *
-     * @return read value within a range of +/-512.
      *
+     * @return The read value within a range of +/-512.
      */
     inline int16_t Read() { return read_; }
 
     /**
-     * Return the analog read value as voltage.
+     * @brief Return the analog read value as a voltage.
-     *
-     * @return A float representing the voltage (-5.0 to +5.0).
      *
+     * @return A float representing the calculated voltage (-5.0 to +5.0).
      */
     inline float Voltage() { return ((read_ / 512.0) * 5.0); }
 
@@ -85,4 +113,4 @@ class AnalogInput {
     bool inverted_ = false;
 };
 
-#endif
+#endif

clock.h

@@ -4,7 +4,7 @@
  * @brief Wrapper Class for clock timing functions.
  * @version 0.1
  * @date 2025-05-04
- * 
+ *
  * @copyright MIT - (c) 2025 - Adam Wonak - adam.wonak@gmail.com
  *
  */
@@ -27,6 +27,9 @@ typedef void (*ExtCallback)(void);
 static ExtCallback extUserCallback = nullptr;
 static void serialEventNoop(uint8_t msg, uint8_t status) {}
 
+/**
+ * @brief Wrapper Class for clock timing functions.
+ */
 class Clock {
    public:
     static constexpr int DEFAULT_TEMPO = 120;
@@ -47,6 +50,9 @@ class Clock {
         PULSE_LAST,
     };
 
+    /**
+     * @brief Initializes the clock, MIDI serial, and sets default values.
+     */
     void Init() {
         NeoSerial.begin(31250);
 
@@ -67,18 +73,36 @@ class Clock {
         uClock.start();
     }
 
-    // Handle external clock tick and call user callback when receiving clock trigger (PPQN_4, PPQN_24, or MIDI).
+    /**
+     * @brief Attach a handler for external clock ticks.
+     *
+     * This function attaches a user-defined callback to the external clock input pin interrupt.
+     * It is also called for incoming MIDI clock events.
+     *
+     * @param callback Function to call on an external clock event.
+     */
     void AttachExtHandler(void (*callback)()) {
         extUserCallback = callback;
         attachInterrupt(digitalPinToInterrupt(EXT_PIN), callback, RISING);
     }
 
-    // Internal PPQN96 callback for all clock timer operations.
+    /**
+     * @brief Attach a handler for the internal high-resolution clock.
+     *
+     * Sets a callback function that is triggered at the internal PPQN_96 rate. This is the
+     * main internal timing callback for all clock operations.
+     *
+     * @param callback Function to call on every internal clock tick. It receives the tick count as a parameter.
+     */
     void AttachIntHandler(void (*callback)(uint32_t)) {
         uClock.setOnOutputPPQN(callback);
     }
 
-    // Set the source of the clock mode.
+    /**
+     * @brief Set the source of the clock.
+     *
+     * @param source The new source for driving the clock. See the `Source` enum.
+     */
     void SetSource(Source source) {
         bool was_playing = !IsPaused();
         uClock.stop();
@@ -110,47 +134,81 @@ class Clock {
         }
     }
 
-    // Return true if the current selected source is externl (PPQN_4, PPQN_24, or MIDI).
+    /**
+     * @brief Checks if the clock source is external.
+     *
+     * @return true if the current source is external (PPQN_4, PPQN_24, or MIDI).
+     * @return false if the source is internal.
+     */
     bool ExternalSource() {
         return uClock.getClockMode() == uClock.EXTERNAL_CLOCK;
     }
 
-    // Return true if the current selected source is the internal master clock.
+    /**
+     * @brief Checks if the clock source is internal.
+     *
+     * @return true if the current source is the internal master clock.
+     * @return false if the source is external.
+     */
     bool InternalSource() {
         return uClock.getClockMode() == uClock.INTERNAL_CLOCK;
     }
 
-    // Returns the current BPM tempo.
+    /**
+     * @brief Gets the current tempo.
+     *
+     * @return int The current tempo in beats per minute (BPM).
+     */
     int Tempo() {
         return uClock.getTempo();
     }
 
-    // Set the clock tempo to a int between 1 and 400.
+    /**
+     * @brief Set the clock tempo.
+     *
+     * @param tempo The new tempo in beats per minute (BPM).
+     */
     void SetTempo(int tempo) {
         return uClock.setTempo(tempo);
     }
 
-    // Record an external clock tick received to process external/internal syncronization.
+    /**
+     * @brief Manually trigger a clock tick.
+     *
+     * This should be called when in an external clock mode to register an incoming
+     * clock pulse and drive the internal timing.
+     */
     void Tick() {
         uClock.clockMe();
     }
 
-    // Start the internal clock.
+    /**
+     * @brief Starts the clock.
+     */
     void Start() {
         uClock.start();
     }
 
-    // Stop internal clock clock.
+    /**
+     * @brief Stops (pauses) the clock.
+     */
     void Stop() {
         uClock.stop();
     }
 
-    // Reset all clock counters to 0.
+    /**
+     * @brief Resets all clock counters to zero.
+     */
     void Reset() {
         uClock.resetCounters();
     }
 
-    // Returns true if the clock is not running.
+    /**
+     * @brief Checks if the clock is currently paused.
+     *
+     * @return true if the clock is stopped/paused.
+     * @return false if the clock is running.
+     */
     bool IsPaused() {
         return uClock.clock_state == uClock.PAUSED;
     }

encoder.h

@@ -4,10 +4,11 @@
  * @brief Class for interacting with encoders.
  * @version 0.1
  * @date 2025-04-19
- * 
+ *
  * @copyright MIT - (c) 2025 - Adam Wonak - adam.wonak@gmail.com
  *
  */
+
 #ifndef ENCODER_DIR_H
 #define ENCODER_DIR_H
 
@@ -16,6 +17,9 @@
 #include "button.h"
 #include "peripherials.h"
 
+/**
+ * @brief Class for interacting with a rotary encoder that has a push button.
+ */
 class Encoder {
    protected:
     typedef void (*CallbackFunction)(void);
@@ -32,22 +36,57 @@ class Encoder {
     }
     ~Encoder() {}
 
-    // Set to true if the encoder read direction should be reversed.
+    /**
+     * @brief Set the direction of the encoder.
+     *
+     * @param reversed Set to true to reverse the direction of rotation.
+     */
     void SetReverseDirection(bool reversed) {
         reversed_ = reversed;
     }
+
+    /**
+     * @brief Attach a handler for the encoder button press.
+     *
+     * This callback is triggered on a simple press and release of the button,
+     * without any rotation occurring during the press.
+     *
+     * @param f The callback function to execute when a button press.
+     */
     void AttachPressHandler(CallbackFunction f) {
         on_press = f;
     }
 
+    /**
+     * @brief Attach a handler for encoder rotation.
+     *
+     * This callback is triggered when the encoder is rotated while the button is not pressed.
+     *
+     * @param f The callback function to execute on rotation. It receives an integer
+     * representing the change in position (can be positive or negative).
+     */
     void AttachRotateHandler(RotateCallbackFunction f) {
         on_rotate = f;
     }
 
+    /**
+     * @brief Attach a handler for rotation while the button is pressed.
+     *
+     * This callback is triggered when the encoder is rotated while the button is being held down.
+     *
+     * @param f The callback function to execute. It receives an integer
+     * representing the change in position.
+     */
     void AttachPressRotateHandler(RotateCallbackFunction f) {
         on_press_rotate = f;
     }
 
+    /**
+     * @brief Processes encoder and button events.
+     *
+     * This method should be called repeatedly in the main loop to check for state
+     * changes (rotation, button presses) and dispatch the appropriate callbacks.
+     */
     void Process() {
         // Get encoder position change amount.
         int encoder_rotated = _rotate_change() != 0;
@@ -91,7 +130,6 @@ class Encoder {
         int position = encoder_.getPosition();
         unsigned long ms = encoder_.getMillisBetweenRotations();
 
-        // Validation (TODO: add debounce check).
         if (previous_pos_ == position) {
             return 0;
         }