Documents the Buzzer, Speaker and CircularQueue classes

Marlin/buzzer.h

@@ -28,11 +28,19 @@
 
 #define TONE_QUEUE_LENGTH 4
 
+/**
+ * @brief Tone structure
+ * @details Simple abstration of a tone based on a duration and a frequency.
+ *
+ */
 struct tone_t {
   uint16_t duration;
   uint16_t frequency;
 };
 
+/**
+ * @brief Buzzer class
+ */
 class Buzzer {
   private:
     struct state_t {
@@ -43,34 +51,66 @@ class Buzzer {
   protected:
     CircularQueue<tone_t, TONE_QUEUE_LENGTH> buffer;
 
+    /**
+     * @brief Inverts the sate of a digital PIN
+     * @details This will invert the current state of an digital IO pin.
+     */
     void invert() {
       WRITE(BEEPER_PIN, !READ(BEEPER_PIN));
     }
 
+    /**
+     * @brief Turn off a digital PIN
+     * @details Alias of digitalWrite(PIN, LOW) using FastIO
+     */
     void off() {
       WRITE(BEEPER_PIN, LOW);
     }
 
+    /**
+     * @brief Turn on a digital PIN
+     * @details Alias of digitalWrite(PIN, HIGH) using FastIO
+     */
     void on() {
       WRITE(BEEPER_PIN, HIGH);
     }
 
+    /**
+     * @brief Resets the state of the class
+     * @details Brings the class state to a known one.
+     */
     void reset() {
       this->off();
       this->state.timestamp = 0;
     }
 
   public:
+    /**
+     * @brief Class constructor
+     */
     Buzzer() {
       SET_OUTPUT(BEEPER_PIN);
       this->reset();
     }
 
+    /**
+     * @brief Add a tone to the queue
+     * @details Adds a tone_t structure to the ring buffer, will block IO if the
+     * queue is full waiting for one slot to get available.
+     *
+     * @param duration Duration of the tone in milliseconds
+     * @param frequency Frequency of the tone in hertz
+     */
     void tone(uint16_t const &duration, uint16_t const &frequency = 0) {
       while (buffer.isFull()) this->tick();
       this->buffer.enqueue((tone_t) { duration, frequency });
     }
 
+    /**
+     * @brief Loop function
+     * @details This function should be called at loop, it will take care of
+     * playing the tones in the queue.
+     */
     virtual void tick() {
       if (!this->state.timestamp) {
         if (this->buffer.isEmpty()) return;

Marlin/circularqueue.h

@@ -25,10 +25,19 @@
 
 #include <Arduino.h>
 
+/**
+ * @brief Circular Queue class
+ * @details Implementation of the classic ring buffer data structure
+ */
 template<typename T, int N>
 class CircularQueue {
   private:
 
+    /**
+     * @brief Buffer structure
+     * @details This structure consolidates all the overhead required to handle
+     * a circular queue such as the pointers and the buffer vector.
+     */
     struct buffer_t {
       uint8_t head;
       uint8_t tail;
@@ -38,11 +47,23 @@ class CircularQueue {
     } buffer;
 
   public:
+    /**
+     * @brief Class constructor
+     * @details This class requires two template parameters, T defines the type
+     * of the items this queue will handle and N defines the maximum number of
+     * items that can be stored on the queue.
+     */
     CircularQueue<T, N>() {
       this->buffer.length = N;
       this->buffer.size = this->buffer.head = this->buffer.tail = 0;
     }
 
+    /**
+     * @brief Removes and returns a item from the queue
+     * @details Removes the oldest item on the queue which is pointed by the
+     * buffer_t head variable, this item is then returned to the caller.
+     * @return type T item
+     */
     T dequeue() {
       if (this->isEmpty()) return T();
 
@@ -55,6 +76,14 @@ class CircularQueue {
       return item;
     }
 
+    /**
+     * @brief Adds an item to the queue
+     * @details Adds a item to the queue on the location pointed by the buffer_t
+     * tail vairable, will return false if there is no queue space available.
+     *
+     * @param item Item to be added to the queue
+     * @return true if the operation was successfull
+     */
     bool enqueue(T const &item) {
       if (this->isFull()) return false;
 
@@ -67,22 +96,48 @@ class CircularQueue {
       return true;
     }
 
+    /**
+     * @brief Checks if the queue has no items
+     * @details Returns true if there are no items on the queue, false otherwise.
+     * @return true if queue is empty
+     */
     bool isEmpty() {
       return this->buffer.size == 0;
     }
 
+    /**
+     * @brief Checks if the queue is full
+     * @details Returns true if the queue is full, false otherwise.
+     * @return true if queue is full
+     */
     bool isFull() {
       return this->buffer.size == this->buffer.length;
     }
 
+    /**
+     * @brief Gets the queue size
+     * @details Returns the maximum number of items a queue can have.
+     * @return the queue lenght
+     */
     uint8_t length() {
       return this->buffer.length;
     }
 
+    /**
+     * @brief Gets the next item from the queue without removing it
+     * @details Returns the next item on the queue but the item is not removed
+     * from the queue nor the pointers updated.
+     * @return the queue size
+     */
     uint8_t peek() {
       return this->buffer.queue[this->buffer.head];
     }
 
+    /**
+     * @brief Gets the number of items on the queue
+     * @details Returns the current number of items stored on the queue.
+     * @return type T item
+     */
     uint8_t size() {
       return this->buffer.size;
     }

Marlin/speaker.h

@@ -36,17 +36,29 @@ class Speaker: public Buzzer {
     } state;
 
   protected:
+    /**
+     * @brief Resets the state of the class
+     * @details Brings the class state to a known one.
+     */
     void reset() {
       super::reset();
       this->state.period = 0;
       this->state.cycles = 0;
     }
 
   public:
+    /**
+     * @brief Class constructor
+     */
     Speaker() {
       this->reset();
     }
 
+    /**
+     * @brief Loop function
+     * @details This function should be called at loop, it will take care of
+     * playing the tones in the queue.
+     */
     virtual void tick() {
       if (!this->state.cycles) {
         if (this->buffer.isEmpty()) return;