[Doxygen] Warnings fixes (#1046)

* [APRS] Fix Doxygen warnings

* [Print] Fix Doxygen warnings

* [CC1101] Fixed doxygen warnings

* [nRF24] Fixed doxygen warnings

* [RF69] Fixed doxygen warnings

* [SX126x] Fixed doxygen warnings

* [SX127x] Fixed doxygen warnings

* [AFSK] Fixed doxygen warnings

* [APRS] Fixed doxygen warnings

* [Bell] Fixed doxygen warnings

* [Ext] Fixed doxygen warnings

* [LoRaWAN] Fixed doxygen warnings

* [PHY] Fixed doxygen warnings

* [Print] Fixed doxygen warnings

* [Mod] Fixed doxygen warnings

src/Module.h

@@ -13,10 +13,9 @@
 #endif
 
 /*!
-* Value to use as the last element in a mode table to indicate the
+  \brief Value to use as the last element in a mode table to indicate the
-* end of the table.
+  end of the table.
-*
+  See \ref setRfSwitchTable for details.
-* See setRfSwitchTable() for details.
 */
 #define END_OF_MODE_TABLE    { Module::MODE_END_OF_TABLE, {} }
 
@@ -31,43 +30,49 @@
 class Module {
   public:
     /*!
-     * \brief The maximum number of pins supported by the RF switch
+      \brief The maximum number of pins supported by the RF switch code.
-     * code.
+      Note: It is not recommended to use this constant in your sketch
-     *
+      when defining a rfswitch pins array, to prevent issues when this
-     * Note: It is not recommended to use this constant in your sketch
+      value is ever increased and such an array gets extra zero
-     * when defining a rfswitch pins array, to prevent issues when this
+      elements (that will be interpreted as pin 0).
-     * value is ever increased and such an array gets extra zero
-     * elements (that will be interpreted as pin 0).
     */
     static const size_t RFSWITCH_MAX_PINS = 3;
 
     /*!
-     * Description of RF switch pin states for a single mode.
+      \struct RfSwitchMode_t
-     *
+      \brief Description of RF switch pin states for a single mode.
-     * See setRfSwitchTable() for details.
+      See \ref setRfSwitchTable for details.
     */
     struct RfSwitchMode_t {
+      /*! \brief RF switching mode, one of \ref OpMode_t or a custom radio-defined value. */
       uint8_t mode;
+
+      /*! \brief Output pin values */
       uint32_t values[RFSWITCH_MAX_PINS];
     };
 
     /*!
-     * Constants to use in a mode table set be setRfSwitchTable. These
+      \enum OpMode_t
-     * constants work for most radios, but some radios define their own
+      \brief Constants to use in a mode table set be setRfSwitchTable. These
-     * constants to be used instead.
+      constants work for most radios, but some radios define their own
-     *
+      constants to be used instead.
-     * See setRfSwitchTable() for details.
+     
+      See \ref setRfSwitchTable for details.
     */
     enum OpMode_t {
-      /*! End of table marker, use \ref END_OF_MODE_TABLE constant
+      /*!
-       * instead. Value is zero to ensure zero-initialized mode ends the
+        \brief End of table marker, use \ref END_OF_MODE_TABLE constant instead.
-       * table */
+        Value is zero to ensure zero-initialized mode ends the table.
+      */
       MODE_END_OF_TABLE = 0,
-      /*! Idle mode */
+
+      /*! \brief Idle mode */
       MODE_IDLE,
-      /*! Receive mode */
+
+      /*! \brief Receive mode */
       MODE_RX,
-      /*! Transmission mode */
+
+      /*! \brief Transmission mode */
       MODE_TX,
     };
 
@@ -111,7 +116,7 @@ class Module {
 
     /*!
       \brief Overload for assignment operator.
-      \param frame rvalue Module.
+      \param mod rvalue Module.
     */
     Module& operator=(const Module& mod);
 
@@ -438,7 +443,7 @@ class Module {
 
     /*!
       \brief Find a mode in the RfSwitchTable.
-      \param The mode to find.
+      \param mode The mode to find.
       \returns A pointer to the RfSwitchMode_t struct in the table that
       matches the passed mode. Returns nullptr if no rfswitch pins are
       configured, or the passed mode is not listed in the table.

src/modules/CC1101/CC1101.h

@@ -537,7 +537,7 @@ class CC1101: public PhysicalLayer {
 
     /*!
       \brief Default constructor.
-      \param mod Instance of Module that will be used to communicate with the radio.
+      \param module Instance of Module that will be used to communicate with the radio.
     */
     CC1101(Module* module);
 
@@ -797,6 +797,7 @@ class CC1101: public PhysicalLayer {
     /*!
       \brief Sets preamble length.
       \param preambleLength Preamble length to be set (in bits), allowed values: 16, 24, 32, 48, 64, 96, 128 and 192.
+      \param qualityThreshold Preamble quality threshold (PQT) to set.
       \returns \ref status_codes
     */
     int16_t setPreambleLength(uint8_t preambleLength, uint8_t qualityThreshold);
@@ -852,14 +853,14 @@ class CC1101: public PhysicalLayer {
 
     /*!
       \brief Set modem in variable packet length mode.
-      \param len Maximum packet length.
+      \param maxLen Maximum packet length.
       \returns \ref status_codes
     */
     int16_t variablePacketLengthMode(uint8_t maxLen = RADIOLIB_CC1101_MAX_PACKET_LENGTH);
 
     /*!
       \brief Enable sync word filtering and generation.
-      \param numBits Sync word length in bits.
+      \param maxErrBits Maximum number of allowed error bits in sync word.
       \param requireCarrierSense Require carrier sense above threshold in addition to sync word.
       \returns \ref status_codes
     */

src/modules/RF69/RF69.h

@@ -486,7 +486,7 @@ class RF69: public PhysicalLayer {
 
     /*!
       \brief Default constructor.
-      \param mod Instance of Module that will be used to communicate with the radio.
+      \param module Instance of Module that will be used to communicate with the radio.
     */
     RF69(Module* module);
 
@@ -575,7 +575,7 @@ class RF69: public PhysicalLayer {
 
     /*!
       \brief Sets AES key.
-      \param Key to be used for AES encryption. Must be exactly 16 bytes long.
+      \param key Key to be used for AES encryption. Must be exactly 16 bytes long.
     */
     void setAESKey(uint8_t* key);
 
@@ -872,14 +872,14 @@ class RF69: public PhysicalLayer {
 
      /*!
       \brief Set modem in variable packet length mode.
-      \param len Maximum packet length.
+      \param maxLen Maximum packet length.
       \returns \ref status_codes
     */
     int16_t variablePacketLengthMode(uint8_t maxLen = RADIOLIB_RF69_MAX_PACKET_LENGTH);
 
      /*!
       \brief Enable sync word filtering and generation.
-      \param numBits Sync word length in bits.
+      \param maxErrBits Maximum allowed number of error bits in sync word.
       \returns \ref status_codes
     */
     int16_t enableSyncWordFiltering(uint8_t maxErrBits = 0);

src/modules/SX126x/STM32WLx_Module.cpp

@@ -22,10 +22,19 @@ enum {
   RADIOLIB_STM32WLx_VIRTUAL_PIN_RESET,
 };
 
+/*!
+  \class Stm32wlxHal
+  \brief Hardware Abstraction Layer for STM32WL.
+*/
 class Stm32wlxHal : public ArduinoHal {
   public:
     Stm32wlxHal(): ArduinoHal(SubGhz.SPI, SubGhz.spi_settings) {}
 
+    /*!
+      \brief Pin mode override to handle STM32WL virtual pins.
+      \param dwPin Pin to set.
+      \param dwMode Mode to set.
+    */
     void pinMode(uint32_t dwPin, uint32_t dwMode) {
       switch(dwPin) {
         case RADIOLIB_STM32WLx_VIRTUAL_PIN_NSS:
@@ -40,6 +49,11 @@ class Stm32wlxHal : public ArduinoHal {
       }
     }
 
+    /*!
+      \brief Digital write override to handle STM32WL virtual pins.
+      \param dwPin Pin to set.
+      \param dwVal Value to set.
+    */
     void digitalWrite(uint32_t dwPin, uint32_t dwVal) {
       switch (dwPin) {
         case RADIOLIB_STM32WLx_VIRTUAL_PIN_NSS:
@@ -61,6 +75,11 @@ class Stm32wlxHal : public ArduinoHal {
       }
     }
 
+    /*!
+      \brief Digital read override to handle STM32WL virtual pins.
+      \param dwPin Pin to set.
+      \returns Value read on the pin.
+    */
     uint32_t digitalRead(uint32_t ulPin) {
       switch (ulPin) {
         case RADIOLIB_STM32WLx_VIRTUAL_PIN_BUSY:

src/modules/SX126x/SX126x.h

@@ -964,7 +964,7 @@ class SX126x: public PhysicalLayer {
 
     /*!
       \brief Check whether the IRQ bit for RxTimeout is set
-      \returns \ref RxTimeout IRQ is set
+      \returns Whether RxTimeout IRQ is set
     */
     bool isRxTimeout();
 

src/modules/SX127x/SX1272.h

@@ -111,8 +111,7 @@ class SX1272: public SX127x {
       \param sf %LoRa link spreading factor. Allowed values range from 6 to 12.
       \param cr %LoRa link coding rate denominator. Allowed values range from 5 to 8.
       \param syncWord %LoRa sync word. Can be used to distinguish different networks. Note that value 0x34 is reserved for LoRaWAN networks.
-      \param currentLimit Trim value for OCP (over current protection) in mA. Can be set to multiplies of 5 in range 45 to 120 mA and to multiples of 10 in range 120 to 240 mA.
+      \param power Transmission output power in dBm. Allowed values range from 2 to 17 dBm.
-      Set to 0 to disable OCP (not recommended).
       \param preambleLength Length of %LoRa transmission preamble in symbols. The actual preamble length is 4.25 symbols longer than the set number.
       Allowed values range from 6 to 65535.
       \param gain Gain of receiver LNA (low-noise amplifier). Can be set to any integer in range 1 to 6 where 1 is the highest gain.

src/modules/SX127x/SX127x.h

@@ -600,7 +600,7 @@ class SX127x: public PhysicalLayer {
 
     /*!
       \brief Initialization method. Will be called with appropriate parameters when calling initialization method from derived class.
-      \param chipVersion Array of possible values in SPI version register. Used to verify the connection and hardware version.
+      \param chipVersions Array of possible values in SPI version register. Used to verify the connection and hardware version.
       \param numVersions Number of possible chip versions.
       \param syncWord %LoRa sync word.
       \param preambleLength Length of %LoRa transmission preamble in symbols.
@@ -615,7 +615,7 @@ class SX127x: public PhysicalLayer {
 
     /*!
       \brief Initialization method for FSK modem. Will be called with appropriate parameters when calling FSK initialization method from derived class.
-      \param chipVersion Array of possible values in SPI version register. Used to verify the connection and hardware version.
+      \param chipVersions Array of possible values in SPI version register. Used to verify the connection and hardware version.
       \param numVersions Number of possible chip versions.
       \param freqDev Frequency deviation of the FSK transmission in kHz.
       \param rxBw Receiver bandwidth in kHz.
@@ -928,7 +928,7 @@ class SX127x: public PhysicalLayer {
 
     /*!
       \brief Sets FSK automatic frequency correction bandwidth. Allowed values range from 2.6 to 250 kHz. Only available in FSK mode.
-      \param rxBw Receiver AFC bandwidth to be set (in kHz).
+      \param afcBw Receiver AFC bandwidth to be set (in kHz).
       \returns \ref status_codes
     */
     int16_t setAFCBandwidth(float afcBw);
@@ -1038,7 +1038,7 @@ class SX127x: public PhysicalLayer {
 
     /*!
       \brief Set modem in variable packet length mode. Available in FSK mode only.
-      \param len Maximum packet length.
+      \param maxLen Maximum packet length.
       \returns \ref status_codes
     */
     int16_t variablePacketLengthMode(uint8_t maxLen = RADIOLIB_SX127X_MAX_PACKET_LENGTH_FSK);
@@ -1201,14 +1201,6 @@ class SX127x: public PhysicalLayer {
     */
     int16_t setDIOPreambleDetect(bool usePreambleDetect);
 
-    /*!
-      \brief Gets recorded signal strength indicator.
-      \param packet Whether to read last packet RSSI, or the current value. LoRa mode only, ignored for FSK.
-      \param skipReceive Set to true to skip putting radio in receive mode for the RSSI measurement in FSK/OOK mode.
-      \returns RSSI value in dBm.
-    */
-    float getRSSI(bool packet, bool skipReceive, int16_t offset);
-
     /*!
       \brief Sets the RSSI value above which the RSSI interrupt is signaled
       \param dbm A dBm value between -127.5 and 0 inclusive
@@ -1246,6 +1238,7 @@ class SX127x: public PhysicalLayer {
     int16_t getActiveModem();
     int16_t setFrequencyRaw(float newFreq);
     int16_t setBitRateCommon(float br, uint8_t fracRegAddr);
+    float getRSSI(bool packet, bool skipReceive, int16_t offset);
 
 #if !RADIOLIB_GODMODE
   private:

src/modules/nRF24/nRF24.h

@@ -460,7 +460,7 @@ class nRF24: public PhysicalLayer {
 
     /*!
       \brief Dummy encoding configuration method, to ensure PhysicalLayer compatibility.
-      \param sh Ignored.
+      \param encoding Ignored.
       \returns \ref status_codes
     */
     int16_t setEncoding(uint8_t encoding) override;

src/protocols/AFSK/AFSK.h

@@ -44,7 +44,7 @@ class AFSKClient  {
 
     /*!
       \brief Stops transmitting audio tone.
-      \param freq Keep transmitter on - this may limit noise when switching transmitter on or off.
+      \param keepOn Keep transmitter on - this may limit noise when switching transmitter on or off.
       \returns \ref status_codes
     */
     int16_t noTone(bool keepOn = false);

src/protocols/APRS/APRS.h

@@ -29,17 +29,33 @@
 
 /*!
   \defgroup mic_e_message_types Mic-E message types.
-
   \{
 */
+
+/*! \brief Mic-E "Off duty" message. */
 #define RADIOLIB_APRS_MIC_E_TYPE_OFF_DUTY                       0b00000111
+
+/*! \brief Mic-E "En route" message. */
 #define RADIOLIB_APRS_MIC_E_TYPE_EN_ROUTE                       0b00000110
+
+/*! \brief Mic-E "In service" message. */
 #define RADIOLIB_APRS_MIC_E_TYPE_IN_SERVICE                     0b00000101
+
+/*! \brief Mic-E "Returning" message. */
 #define RADIOLIB_APRS_MIC_E_TYPE_RETURNING                      0b00000100
+
+/*! \brief Mic-E "Commited" message. */
 #define RADIOLIB_APRS_MIC_E_TYPE_COMMITTED                      0b00000011
+
+/*! \brief Mic-E special message. */
 #define RADIOLIB_APRS_MIC_E_TYPE_SPECIAL                        0b00000010
+
+/*! \brief Mic-E priority message. */
 #define RADIOLIB_APRS_MIC_E_TYPE_PRIORITY                       0b00000001
+
+/*! \brief Mic-E emergency message. */
 #define RADIOLIB_APRS_MIC_E_TYPE_EMERGENCY                      0b00000000
+
 /*!
   \}
 */
@@ -97,9 +113,9 @@ class APRSClient {
       \param destCallsign Destination station callsign.
       \param destSSID Destination station SSID.
       \param lat Latitude as a null-terminated string.
-      \param long Longitude as a null-terminated string.
+      \param lon Longitude as a null-terminated string.
       \param msg Message to be transmitted. Defaults to NULL (no message).
-      \param msg Position timestamp. Defaults to NULL (no timestamp).
+      \param time Position timestamp. Defaults to NULL (no timestamp).
       \returns \ref status_codes
     */
     int16_t sendPosition(char* destCallsign, uint8_t destSSID, char* lat, char* lon, char* msg = NULL, char* time = NULL);

src/protocols/BellModem/BellModem.h

@@ -93,7 +93,7 @@ class BellClient: public AFSKClient, public RadioLibPrint {
 
     /*!
       \brief Set correction coefficient for tone length.
-      \param correction Timing correction factor, used to adjust the length of tones.
+      \param corr Timing correction factor, used to adjust the length of tones.
       Less than 1.0 leads to shorter tones, defaults to 1.0 (no correction).
       \returns \ref status_codes
     */

src/protocols/ExternalRadio/ExternalRadio.h

@@ -9,6 +9,10 @@
 
 #include "../PhysicalLayer/PhysicalLayer.h"
 
+/*!
+  \class ExternalRadio
+  \brief Class to interface with external radio hardware.
+*/
 class ExternalRadio: public PhysicalLayer {
   public:
     #if defined(RADIOLIB_BUILD_ARDUINO)

src/protocols/LoRaWAN/LoRaWAN.h

@@ -199,11 +199,22 @@
 #define RADIOLIB_LORAWAN_MAX_MAC_COMMAND_LEN_UP                 (2)
 #define RADIOLIB_LORAWAN_MAX_NUM_ADR_COMMANDS                   (8)
 
+/*!
+  \struct LoRaWANMacSpec_t
+  \brief MAC command specification structure.
+*/
 struct LoRaWANMacSpec_t {
+  /*! \brief Command ID */
   const uint8_t cid;
+  
+  /*! \brief Uplink message length */
   const uint8_t lenDn;
+  
+  /*! \brief Downlink message length */
   const uint8_t lenUp;
-  const bool user;      // whether this MAC command can be issued by a user or not
+  
+  /*! \brief Whether this MAC command can be issued by the user or not */
+  const bool user;
 };
 
 const LoRaWANMacSpec_t MacTable[RADIOLIB_LORAWAN_NUM_MAC_COMMANDS + 1] = {
@@ -277,7 +288,7 @@ enum LoRaWANSchemeSession_t {
 };
 
 /*!
-  \struct LoRaWANChannelSpan_t
+  \struct LoRaWANChannel_t
   \brief Structure to save information about LoRaWAN channels.
   To save space, adjacent channels are saved in "spans".
 */
@@ -352,8 +363,10 @@ struct LoRaWANBand_t {
   /*! \brief Number of milliseconds per hour of allowed Time-on-Air */
   uint32_t dutyCycle;
 
-  /*! \brief Maximum dwell time per message in milliseconds */
+  /*! \brief Maximum dwell time per uplink message in milliseconds */
   uint32_t dwellTimeUp;
+
+  /*! \brief Maximum dwell time per downlink message in milliseconds */
   uint32_t dwellTimeDn;
 
   /*! \brief A set of default uplink (TX) channels for frequency-type bands */
@@ -432,10 +445,18 @@ struct LoRaWANMacCommand_t {
   /*! \brief Repetition counter (the command will be uplinked repeat + 1 times) */
   uint8_t repeat;
 };
-
+/*!
+  \struct LoRaWANMacCommandQueue_t
+  \brief Structure to hold information about a queue of MAC commands
+*/
 struct LoRaWANMacCommandQueue_t {
+  /*! \brief Number of commands in the queue */
   uint8_t numCommands;
+
+  /*! \brief Total length of the queue */
   uint8_t len;
+
+  /*! \brief MAC command buffer */
   LoRaWANMacCommand_t commands[RADIOLIB_LORAWAN_MAC_COMMAND_QUEUE_SIZE];
 };
 
@@ -477,10 +498,10 @@ struct LoRaWANEvent_t {
 class LoRaWANNode {
   public:
 
-    // Offset between TX and RX1 (such that RX1 has equal or lower DR)
+    /*! \brief Offset between TX and RX1 (such that RX1 has equal or lower DR) */
     uint8_t rx1DrOffset = 0;
 
-    // RX2 channel properties - may be changed by MAC command
+    /*! \brief RX2 channel properties - may be changed by MAC command */
     LoRaWANChannel_t rx2;
 
     /*!
@@ -734,7 +755,7 @@ class LoRaWANNode {
 
     /*!
       \brief Set uplink datarate. This should not be used when ADR is enabled.
-      \param dr Datarate to use for uplinks.
+      \param drUp Datarate to use for uplinks.
       \returns \ref status_codes
     */
     int16_t setDatarate(uint8_t drUp);
@@ -768,7 +789,7 @@ class LoRaWANNode {
     /*!
       \brief Toggle adherence to dwellTime limits to on or off.
       \param enable Whether to adhere to dwellTime limits or not (default true).
-      \param msPerHour The maximum allowed Time-on-Air per uplink in milliseconds 
+      \param msPerUplink The maximum allowed Time-on-Air per uplink in milliseconds 
       (default 0 = maximum allowed for configured band).
     */
     void setDwellTime(bool enable, uint32_t msPerUplink = 0);

src/protocols/PhysicalLayer/PhysicalLayer.h

@@ -4,22 +4,42 @@
 #include "../../TypeDef.h"
 #include "../../Module.h"
 
-// data rate structure interpretation in case LoRa is used
+/*!
+  \struct LoRaRate_t
+  \brief Data rate structure interpretation in case LoRa is used
+*/
 struct LoRaRate_t {
+  /*! \brief LoRa spreading factor */
   uint8_t spreadingFactor;
+  
+  /*! \brief LoRa bandwidth in kHz */
   float bandwidth;
+  
+  /*! \brief LoRa coding rate */
   uint8_t codingRate;
 };
 
-// data rate structure interpretation in case FSK is used
+/*!
+  \struct FSKRate_t
+  \brief Data rate structure interpretation in case FSK is used
+*/
 struct FSKRate_t {
+  /*! \brief FSK bit rate in kbps */
   float bitRate;
+  
+  /*! \brief FS frequency deviation in kHz*/
   float freqDev;
 };
 
-// common data rate
+/*!
+  \union DataRate_t
+  \brief Common data rate structure
+*/
 union DataRate_t {
+  /*! \brief Interpretation for LoRa modems */
   LoRaRate_t lora;
+
+  /*! \brief Interpretation for FSK modems */
   FSKRate_t fsk;
 };
 
@@ -237,7 +257,7 @@ class PhysicalLayer {
 
     /*!
       \brief Sets FSK data encoding. Only available in FSK mode. Must be implemented in module class.
-      \param enc Encoding to be used. See \ref config_encoding for possible values.
+      \param encoding Encoding to be used. See \ref config_encoding for possible values.
       \returns \ref status_codes
     */
     virtual int16_t setEncoding(uint8_t encoding);
@@ -334,7 +354,7 @@ class PhysicalLayer {
 
     /*!
       \brief Check whether the IRQ bit for RxTimeout is set
-      \returns \ref RxTimeout IRQ is set
+      \returns Whether RxTimeout IRQ is set
     */
     virtual bool isRxTimeout();
 

src/protocols/Print/Print.cpp

@@ -152,7 +152,7 @@ size_t RadioLibPrint::print(double n, int digits) {
   return(RadioLibPrint::printFloat(n, digits));
 }
 
-size_t RadioLibPrint::println(const char* str) {
+size_t RadioLibPrint::println(const char str[]) {
   size_t n = RadioLibPrint::print(str);
   n += RadioLibPrint::println();
   return(n);

src/protocols/Print/Print.h

@@ -10,7 +10,10 @@
 #define RADIOLIB_ASCII_EXTENDED                                 1
 #define RADIOLIB_ITA2                                           2
 
-// based on Arduino Print class
+/*!
+  \class RadioLibPrint
+  \brief Printing class, based on Arduino Print class with additional encodings.
+*/
 class RadioLibPrint {
   public:
     virtual size_t write(uint8_t) = 0;