[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
This commit is contained in:
Jan Gromeš 2024-04-01 11:11:24 +02:00 committed by GitHub
parent e5493618a4
commit e57c9b08ea
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 170 additions and 89 deletions

View file

@ -13,10 +13,9 @@
#endif
/*!
* Value to use as the last element in a mode table to indicate the
* end of the table.
*
* See setRfSwitchTable() for details.
\brief Value to use as the last element in a mode table to indicate the
end of the table.
See \ref 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
* code.
*
* Note: It is not recommended to use this constant in your sketch
* when defining a rfswitch pins array, to prevent issues when this
* value is ever increased and such an array gets extra zero
* elements (that will be interpreted as pin 0).
*/
\brief The maximum number of pins supported by the RF switch code.
Note: It is not recommended to use this constant in your sketch
when defining a rfswitch pins array, to prevent issues when this
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.
*
* See setRfSwitchTable() for details.
*/
\struct RfSwitchMode_t
\brief Description of RF switch pin states for a single mode.
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
* constants work for most radios, but some radios define their own
* constants to be used instead.
*
* See setRfSwitchTable() for details.
*/
\enum OpMode_t
\brief Constants to use in a mode table set be setRfSwitchTable. These
constants work for most radios, but some radios define their own
constants to be used instead.
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
* table */
/*!
\brief End of table marker, use \ref END_OF_MODE_TABLE constant instead.
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.

View file

@ -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);
@ -834,52 +835,52 @@ class CC1101: public PhysicalLayer {
\brief Gets LQI (Link Quality Indicator) of the last received packet.
\returns Last packet LQI (lower is better).
*/
uint8_t getLQI() const;
uint8_t getLQI() const;
/*!
/*!
\brief Query modem for the packet length of received payload.
\param update Update received packet length. Will return cached value when set to false.
\returns Length of last received packet in bytes.
*/
size_t getPacketLength(bool update = true) override;
/*!
/*!
\brief Set modem in fixed packet length mode.
\param len Packet length.
\returns \ref status_codes
*/
int16_t fixedPacketLengthMode(uint8_t len = RADIOLIB_CC1101_MAX_PACKET_LENGTH);
/*!
/*!
\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
*/
int16_t enableSyncWordFiltering(uint8_t maxErrBits = 0, bool requireCarrierSense = false);
/*!
/*!
\brief Disable preamble and sync word filtering and generation.
\param requireCarrierSense Require carrier sense above threshold.
\returns \ref status_codes
*/
int16_t disableSyncWordFiltering(bool requireCarrierSense = false);
/*!
/*!
\brief Enable CRC filtering and generation.
\param enable Set or unset CRC generation and filtering.
\returns \ref status_codes
*/
int16_t setCrcFiltering(bool enable = true);
/*!
/*!
\brief Set modem in "sniff" mode: no packet filtering (e.g., no preamble, sync word, address, CRC).
\param enable Set or unset promiscuous mode.
\param requireCarrierSense Set carriersense required above threshold, defaults to false.
@ -887,7 +888,7 @@ class CC1101: public PhysicalLayer {
*/
int16_t setPromiscuousMode(bool enable = true, bool requireCarrierSense = false);
/*!
/*!
\brief Get whether the modem is in promiscuous mode: no packet filtering
(e.g., no preamble, sync word, address, CRC).
\returns Whether the modem is in promiscuous mode.
@ -917,16 +918,16 @@ class CC1101: public PhysicalLayer {
void setRfSwitchTable(const uint32_t (&pins)[Module::RFSWITCH_MAX_PINS], const Module::RfSwitchMode_t table[]);
/*!
\brief Get one truly random byte from RSSI noise.
\returns TRNG byte.
*/
\brief Get one truly random byte from RSSI noise.
\returns TRNG byte.
*/
uint8_t randomByte();
/*!
\brief Read version SPI register. Should return CC1101_VERSION_LEGACY (0x04) or
CC1101_VERSION_CURRENT (0x14) if CC1101 is connected and working.
\returns Version register contents or \ref status_codes
*/
\brief Read version SPI register. Should return CC1101_VERSION_LEGACY (0x04) or
CC1101_VERSION_CURRENT (0x14) if CC1101 is connected and working.
\returns Version register contents or \ref status_codes
*/
int16_t getChipVersion();
#if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE

View file

@ -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);

View file

@ -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:

View file

@ -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();

View file

@ -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.
Set to 0 to disable OCP (not recommended).
\param power Transmission output power in dBm. Allowed values range from 2 to 17 dBm.
\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.

View file

@ -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:

View file

@ -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;

View file

@ -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);

View file

@ -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);

View file

@ -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
*/

View file

@ -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)

View file

@ -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);

View file

@ -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();

View file

@ -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);

View file

@ -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;