add to firmware documentation

5 files changed, 107 insertions, 3 deletions

diff --git a/firmware/source/periph/adc.hpp b/firmware/source/periph/adc.hpp
index 5f7fa08..ae2e881 100644
--- a/firmware/source/periph/adc.hpp
+++ b/firmware/source/periph/adc.hpp
@@ -2,7 +2,7 @@
  * @file adc.hpp
  * @brief Manages signal reading through the ADC.
  *
- * Copyright (C) 2021 Clyne Sullivan
+ * Copyright (C) 2023 Clyne Sullivan
  *
  * Distributed under the GNU GPL v3 or later. You should have received a copy of
  * the GNU General Public License along with this program.
@@ -22,18 +22,47 @@ class ADC
 public:
     using Operation = void (*)(adcsample_t *buffer, size_t count);
 
+    /**
+     * Initializes analog input pins and the microcontoller's ADC peripheral.
+     */
     static void begin();
 
+    /**
+     * Begins continuous ADC sampling triggered by SClock at the set sampling
+     * rate.
+     * @param buffer Pointer to buffer for sample data.
+     * @param count Number of samples that the buffer can hold.
+     * @param operation Handler function to operate on filled half-buffers.
+     */
     static void start(adcsample_t *buffer, size_t count, Operation operation);
+
+    /**
+     * Stops the continuous ADC sampling.
+     */
     static void stop();
 
+    /**
+     * Runs a single conversion on the "alt" inputs (parameter knobs).
+     * @param id The ID of the desired "alt" input (zero or one).
+     * @return The sampled value for the given input.
+     */
     static adcsample_t readAlt(unsigned int id);
 
+    /**
+     * Sets the desired sampling rate for the ADC to operate at.
+     */
     static void setRate(SClock::Rate rate);
+
+    /**
+     * Used to override the handler function for the currently running
+     * conversion.
+     */
     static void setOperation(Operation operation);
 
 private:
+    // ADC driver for signal input.
     static ADCDriver *m_driver;
+    // ADC driver for "alt" inputs.
     static ADCDriver *m_driver2;
 
     static const ADCConfig m_config;
diff --git a/firmware/source/periph/cordic.cpp b/firmware/source/periph/cordic.cpp
index 29ee068..b6a9d7e 100644
--- a/firmware/source/periph/cordic.cpp
+++ b/firmware/source/periph/cordic.cpp
@@ -1,3 +1,14 @@
+/**
+ * @file cordic.cpp
+ * @brief Provides mathematical functions for algorithms.
+ *
+ * Copyright (C) 2023 Clyne Sullivan
+ *
+ * Distributed under the GNU GPL v3 or later. You should have received a copy of
+ * the GNU General Public License along with this program.
+ * If not, see <https://www.gnu.org/licenses/>.
+ */
+
 #include "cordic.hpp"
 #include "hal.h"
 
diff --git a/firmware/source/periph/cordic.hpp b/firmware/source/periph/cordic.hpp
index 5d640cc..a9a0466 100644
--- a/firmware/source/periph/cordic.hpp
+++ b/firmware/source/periph/cordic.hpp
@@ -1,11 +1,33 @@
+/**
+ * @file cordic.hpp
+ * @brief Provides mathematical functions for algorithms.
+ *
+ * Copyright (C) 2023 Clyne Sullivan
+ *
+ * Distributed under the GNU GPL v3 or later. You should have received a copy of
+ * the GNU General Public License along with this program.
+ * If not, see <https://www.gnu.org/licenses/>.
+ */
+
 #ifndef CORDIC_HPP_
 #define CORDIC_HPP_
 
+/**
+ * Named after the hardware CORDIC peripheral even though software
+ * implementations may be used.
+ */
 namespace cordic {
+    // Provides pi in case cordic functions require it.
     constexpr double PI = 3.1415926535L;
 
+    /**
+     * Prepares cordic functions for use.
+     */
     void init();
 
+    // mod - Calculates remainder for given fraction.
+    // cos, sin, tan - The trig functions.
+
 #if !defined(TARGET_PLATFORM_L4)
     double mod(double n, double d);
 
diff --git a/firmware/source/periph/dac.hpp b/firmware/source/periph/dac.hpp
index 7250a52..f4266c7 100644
--- a/firmware/source/periph/dac.hpp
+++ b/firmware/source/periph/dac.hpp
@@ -2,7 +2,7 @@
  * @file dac.hpp
  * @brief Manages signal creation using the DAC.
  *
- * Copyright (C) 2021 Clyne Sullivan
+ * Copyright (C) 2023 Clyne Sullivan
  *
  * Distributed under the GNU GPL v3 or later. You should have received a copy of
  * the GNU General Public License along with this program.
@@ -18,12 +18,35 @@
 class DAC
 {
 public:
+    /**
+     * Initializes DAC output pins and peripheral.
+     */
     static void begin();
 
+    /**
+     * Begins continuous DAC conversion on the given channel, running at the
+     * current SClock sampling rate.
+     * @param channel Selected output channel (0 = sig. out, 1 = sig. gen.).
+     * @param buffer Buffer of sample data to output.
+     * @param count Number of samples in sample buffer.
+     */
     static void start(int channel, dacsample_t *buffer, size_t count);
+
+    /**
+     * Stops DAC conversion on the given channel.
+     */
     static void stop(int channel);
 
+    /**
+     * Determines if signal generator needs more sample data for streamed
+     * output (i.e. audio file streaming).
+     * @return >0 if samples needed, <0 on initial run.
+     */
     static int sigGenWantsMore();
+
+    /**
+     * Returns true if signal generator is currently running.
+     */
     static int isSigGenRunning();
 
 private:
diff --git a/firmware/source/periph/usbserial.hpp b/firmware/source/periph/usbserial.hpp
index 58113c9..85da470 100644
--- a/firmware/source/periph/usbserial.hpp
+++ b/firmware/source/periph/usbserial.hpp
@@ -2,7 +2,7 @@
  * @file usbserial.hpp
  * @brief Wrapper for ChibiOS's SerialUSBDriver.
  *
- * Copyright (C) 2021 Clyne Sullivan
+ * Copyright (C) 2023 Clyne Sullivan
  *
  * Distributed under the GNU GPL v3 or later. You should have received a copy of
  * the GNU General Public License along with this program.
@@ -17,11 +17,30 @@
 class USBSerial
 {
 public:
+    /**
+     * Prepares for USB serial communication.
+     */
     static void begin();
 
+    /**
+     * Returns true if input data has been received.
+     */
     static bool isActive();
 
+    /**
+     * Reads received input data into the given buffer.
+     * @param buffer Buffer to store input data.
+     * @param count Number of bytes to read.
+     * @return Number of bytes actually read.
+     */
     static size_t read(unsigned char *buffer, size_t count);
+
+    /**
+     * Writes data to serial output.
+     * @param buffer Buffer of output data.
+     * @param count Number of bytes to write.
+     * @return Number of bytes actually written.
+     */
     static size_t write(const unsigned char *buffer, size_t count);
 
 private: