DM: fix doxy

adafruit · Aug 28, 2018 · 8a22b33 · 8a22b33
1 parent 439eaa8
commit 8a22b33
Show file tree

Hide file tree

Showing 6 changed files with 153 additions and 17 deletions.
diff --git a/Adafruit_RGBTrellis.cpp b/Adafruit_RGBTrellis.cpp
@@ -1,12 +1,25 @@
 #include "Adafruit_RGBTrellis.h"
 
+/**************************************************************************/
+/*! 
+    @brief  Class constructor
+*/
+/**************************************************************************/
 Adafruit_RGBTrellis::Adafruit_RGBTrellis() : pixels(RGB_TRELLIS_NUM_KEYS, RGB_TRELLIS_NEOPIX_PIN, NEO_GRB + NEO_KHZ800)
 {
     for(int i=0; i<RGB_TRELLIS_NUM_KEYS; i++){
         _callbacks[i] = NULL;
     }
 }
 
+/**************************************************************************/
+/*! 
+    @brief  Begin communication with the RGB trellis.
+    @param  addr optional i2c address where the device can be found. Defaults to RGB_TRELLIS_ADDR
+    @param  flow optional flow control pin
+    @returns true on success, false on error.
+*/
+/**************************************************************************/
 bool Adafruit_RGBTrellis::begin(uint8_t addr, int8_t flow)
 {
     bool ret = Adafruit_seesaw::begin(addr, flow);
@@ -18,21 +31,47 @@ bool Adafruit_RGBTrellis::begin(uint8_t addr, int8_t flow)
     return ret;
 }
 
+/**************************************************************************/
+/*! 
+    @brief  register a callback function on the passed key.
+    @param  key the key number to register the callback on
+    @param  cb the callback function that should be called when an event on that key happens
+*/
+/**************************************************************************/
 void Adafruit_RGBTrellis::registerCallback(uint8_t key, TrellisCallback (*cb)(keyEvent))
 {
     _callbacks[key] = cb;
 }
 
+/**************************************************************************/
+/*! 
+    @brief  unregister a callback on a given key
+    @param  key the key number the callback is currently mapped to.
+*/
+/**************************************************************************/
 void Adafruit_RGBTrellis::unregisterCallback(uint8_t key)
 {
     _callbacks[key] = NULL;
 }
 
+/**************************************************************************/
+/*! 
+    @brief  activate or deactivate a given key event
+    @param  key the key number to map the event to
+    @param  edge the edge sensitivity of the event
+    @param  enable pass true to enable the passed event, false to disable it.
+*/
+/**************************************************************************/
 void Adafruit_RGBTrellis::activateKey(uint8_t key, uint8_t edge, bool enable)
 {
     setKeypadEvent(RGB_TRELLIS_KEY(key), edge, enable);
 }
 
+/**************************************************************************/
+/*! 
+    @brief  read all events currently stored in the seesaw fifo and call any callbacks.
+*/
+/**************************************************************************/
 void Adafruit_RGBTrellis::read()
 {
     uint8_t count = getKeypadCount();

diff --git a/Adafruit_RGBTrellis.h b/Adafruit_RGBTrellis.h
@@ -41,10 +41,10 @@ class Adafruit_RGBTrellis : public Adafruit_seesaw {
 
     void read();
 
-    seesaw_NeoPixel pixels;
+    seesaw_NeoPixel pixels; ///< the onboard neopixel matrix
 
 protected:
-    TrellisCallback (*_callbacks[RGB_TRELLIS_NUM_KEYS])(keyEvent);
+    TrellisCallback (*_callbacks[RGB_TRELLIS_NUM_KEYS])(keyEvent); ///< the array of callback functions
 };
 
 #endif
diff --git a/Adafruit_TFTShield18.cpp b/Adafruit_TFTShield18.cpp
@@ -1,5 +1,13 @@
 #include "Adafruit_TFTShield18.h"
 
+/**************************************************************************/
+/*! 
+    @brief  set up the TFT shield
+    @param  addr optional address the seesaw chip can be found on
+    @param  flow optional flow control pin to use
+    @returns true on success, false on error
+*/
+/**************************************************************************/
 bool Adafruit_TFTShield18::begin(uint8_t addr, int8_t flow){
     if (! Adafruit_seesaw::begin(addr, flow)) {
         return false;
@@ -10,20 +18,44 @@ bool Adafruit_TFTShield18::begin(uint8_t addr, int8_t flow){
     return true;
 }
 
+/**************************************************************************/
+/*! 
+    @brief  set the value of the backlight
+    @param  value the backlight value to set
+*/
+/**************************************************************************/
 void Adafruit_TFTShield18::setBacklight(uint16_t value){
     uint8_t cmd[] = {0x00, (uint8_t)(value >> 8), (uint8_t)value};
     this->write(SEESAW_TIMER_BASE, SEESAW_TIMER_PWM, cmd, 3);
 }
 
+/**************************************************************************/
+/*! 
+    @brief  set the PWM frequency for the backlight
+    @param  freq the frequency to set the backlight to
+*/
+/**************************************************************************/
 void Adafruit_TFTShield18::setBacklightFreq(uint16_t freq){
     uint8_t cmd[] = {0x0, (uint8_t)(freq >> 8), (uint8_t)freq};
 	this->write(SEESAW_TIMER_BASE, SEESAW_TIMER_FREQ, cmd, 3);
 }
 
+/**************************************************************************/
+/*! 
+    @brief  reset the TFT screen by setting the value of the reset pin
+    @param  rst the value to set the reset pin to
+*/
+/**************************************************************************/
 void Adafruit_TFTShield18::tftReset(bool rst){
    digitalWrite(TFTSHIELD_RESET_PIN, rst); 
 }
 
+/**************************************************************************/
+/*! 
+    @brief  read all buttons on the wing and return as a 32 bit integer
+    @returns the value of the buttons
+*/
+/**************************************************************************/
 uint32_t Adafruit_TFTShield18::readButtons(){
     return digitalReadBulk(TFTSHIELD_BUTTON_ALL);
 }
diff --git a/Adafruit_miniTFTWing.cpp b/Adafruit_miniTFTWing.cpp
@@ -1,5 +1,13 @@
 #include "Adafruit_miniTFTWing.h"
 
+/**************************************************************************/
+/*! 
+    @brief  set up the miniTFTWing
+    @param  addr optional address the seesaw chip can be found on
+    @param  flow optional flow control pin to use
+    @returns true on success, false on error
+*/
+/**************************************************************************/
 bool Adafruit_miniTFTWing::begin(uint8_t addr, int8_t flow) {
   if (! Adafruit_seesaw::begin(addr, flow)) {
     return false;
@@ -10,20 +18,44 @@ bool Adafruit_miniTFTWing::begin(uint8_t addr, int8_t flow) {
   return true;
 }
 
+/**************************************************************************/
+/*! 
+    @brief  set the value of the backlight
+    @param  value the backlight value to set NOTE: 0xFFFF is all the way on 0x0000 is off.
+*/
+/**************************************************************************/
 void Adafruit_miniTFTWing::setBacklight(uint16_t value){
     uint8_t cmd[] = {0x00, (uint8_t)(value >> 8), (uint8_t)value};
     this->write(SEESAW_TIMER_BASE, SEESAW_TIMER_PWM, cmd, 3);
 }
 
+/**************************************************************************/
+/*! 
+    @brief  set the PWM frequency for the backlight
+    @param  freq the frequency to set the backlight to
+*/
+/**************************************************************************/
 void Adafruit_miniTFTWing::setBacklightFreq(uint16_t freq){
     uint8_t cmd[] = {0x0, (uint8_t)(freq >> 8), (uint8_t)freq};
 	this->write(SEESAW_TIMER_BASE, SEESAW_TIMER_FREQ, cmd, 3);
 }
 
+/**************************************************************************/
+/*! 
+    @brief  reset the TFT screen by setting the value of the reset pin
+    @param  rst the value to set the reset pin to
+*/
+/**************************************************************************/
 void Adafruit_miniTFTWing::tftReset(bool rst){
    digitalWrite(TFTWING_RESET_PIN, rst); 
 }
 
+/**************************************************************************/
+/*! 
+    @brief  read all buttons on the wing and return as a 32 bit integer
+    @returns the value of the buttons
+*/
+/**************************************************************************/
 uint32_t Adafruit_miniTFTWing::readButtons(){
     return digitalReadBulk(TFTWING_BUTTON_ALL);
 }
diff --git a/Adafruit_seesaw.cpp b/Adafruit_seesaw.cpp
@@ -581,6 +581,16 @@ void Adafruit_seesaw::UARTSetBaud(uint32_t baud)
 	this->write(SEESAW_SERCOM0_BASE, SEESAW_SERCOM_BAUD, cmd, 4);
 }
 
+/**
+ *****************************************************************************************
+ *  @brief      activate or deactivate a key and edge on the keypad module
+ * 
+ *  @param      key the key number to activate
+ *  @param		edge the edge to trigger on
+ *  @param		enable passing true will enable the passed event, passing false will disable it.
+ *
+ *  @return     none
+ ****************************************************************************************/
 void Adafruit_seesaw::setKeypadEvent(uint8_t key, uint8_t edge, bool enable)
 {
 	keyState ks;
@@ -590,21 +600,43 @@ void Adafruit_seesaw::setKeypadEvent(uint8_t key, uint8_t edge, bool enable)
 	this->write(SEESAW_KEYPAD_BASE, SEESAW_KEYPAD_EVENT, cmd, 2);
 }
 
+/**
+ *****************************************************************************************
+ *  @brief      enable the keypad interrupt that fires when events are in the fifo.
+ ****************************************************************************************/
 void Adafruit_seesaw::enableKeypadInterrupt()
 {
 	this->write8(SEESAW_KEYPAD_BASE, SEESAW_KEYPAD_INTENSET, 0x01);
 }
 
+/**
+ *****************************************************************************************
+ *  @brief      disable the keypad interrupt that fires when events are in the fifo.
+ ****************************************************************************************/
 void Adafruit_seesaw::disableKeypadInterrupt()
 {
 	this->write8(SEESAW_KEYPAD_BASE, SEESAW_KEYPAD_INTENCLR, 0x01);
 }
 
+/**
+ *****************************************************************************************
+ *  @brief      Get the number of events currently in the fifo
+ *  @return     the number of events in the fifo
+ ****************************************************************************************/
 uint8_t Adafruit_seesaw::getKeypadCount()
 {
 	return this->read8(SEESAW_KEYPAD_BASE, SEESAW_KEYPAD_COUNT);
 }
 
+/**
+ *****************************************************************************************
+ *  @brief      Read all keyEvents into the passed buffer
+ * 
+ *  @param      buf pointer to where the keyEvents should be stored
+ *  @param		count the number of events to read
+ *
+ *  @return     none
+ ****************************************************************************************/
 void Adafruit_seesaw::readKeypad(keyEvent *buf, uint8_t count)
 {
 	return this->read(SEESAW_KEYPAD_BASE, SEESAW_KEYPAD_FIFO, (uint8_t *)buf, count, 1000);

diff --git a/Adafruit_seesaw.h b/Adafruit_seesaw.h
@@ -148,12 +148,14 @@
         SEESAW_KEYPAD_FIFO = 0x10,
     };
 
+    /** keypad module edge definitions
+     */
     enum 
     {
-    SEESAW_KEYPAD_EDGE_HIGH = 0,
-    SEESAW_KEYPAD_EDGE_LOW,
-    SEESAW_KEYPAD_EDGE_FALLING,
-    SEESAW_KEYPAD_EDGE_RISING,
+        SEESAW_KEYPAD_EDGE_HIGH = 0,
+        SEESAW_KEYPAD_EDGE_LOW,
+        SEESAW_KEYPAD_EDGE_FALLING,
+        SEESAW_KEYPAD_EDGE_RISING,
     };
 
 #define ADC_INPUT_0_PIN 2 ///< default ADC input pin 
@@ -175,23 +177,22 @@
 #define SEESAW_HW_ID_CODE			0x55 ///< seesaw HW ID code
 #define SEESAW_EEPROM_I2C_ADDR 0x3F ///< EEPROM address of i2c address to start up with (for devices that support this feature)
 
+/** key event stucture for keypad module */
 union keyEvent {
     struct {
-        uint8_t EDGE: 2;
-        uint8_t NUM: 6; //64 events max
-    } bit;
-    uint8_t reg;
+        uint8_t EDGE: 2; ///< the edge that was triggered
+        uint8_t NUM: 6; ///< the event number (64 max)
+    } bit; ///< bitfield format
+    uint8_t reg; ///< register format
 };
 
+/** key state struct that will be written to seesaw chip keypad module */
 union keyState {
     struct {
-        //the current state of the key
-        uint8_t STATE: 1;
-
-        //the registered events for that key
-        uint8_t ACTIVE: 4;
-    } bit;
-    uint8_t reg;
+        uint8_t STATE: 1; ///< the current state of the key
+        uint8_t ACTIVE: 4; ///< the registered events for that key
+    } bit; ///< bitfield format
+    uint8_t reg; ///< register format
 };
 
 /**************************************************************************/