Improved API documentation

doc/Doxyfile

@@ -633,7 +633,7 @@ FORCE_LOCAL_INCLUDES   = NO
 # documentation for inline members.
 # The default value is: YES.
 
-INLINE_INFO            = YES
+INLINE_INFO            = NO
 
 # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
 # (detailed) documentation of file and class members alphabetically by member
@@ -865,7 +865,7 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = ../include \
-                         mainpage.h
+                         doc.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

doc/doc.dox

@@ -0,0 +1,21 @@
+/*!
+\mainpage ttn-esp32 API Documentation 
+
+  ttn-esp32 is a C and C++ library for the ESP-IDF (ESP32) framework
+  for The Things Network library end devices using Semtech SX127x chips.
+
+
+\section cplusplus C++ API
+
+  \ref TheThingsNetwork class
+
+  \ref TTNRFSettings struct
+
+
+\section c C API
+
+  \ref c_api
+
+  \ref ttn_rf_settings_t struct
+
+*/

doc/generate.sh

@@ -1,2 +1,3 @@
 #!/bin/sh
+rm -rf html
 doxygen Doxyfile

doc/mainpage.h

@@ -1,8 +0,0 @@
-/*! \mainpage ttn-esp32 – The Things Network library for ESP32
- *
- * This library for ESP-IDF (ESP32) supports devices with Semtech SX127x chips.
- * 
- * \ref TheThingsNetwork class
- * 
- * \ref ttn.h C functions
- */

include/TheThingsNetwork.h

@@ -440,8 +440,8 @@ public:
     /**
      * @brief Resets the LoRaWAN radio.
      * 
-     * To restart communication, join() must be called.
+     * To restart communication, @ref join() must be called.
-     * It neither clears the provisioned keys nor the configured pins.
+     * Clears neither the provisioned keys nor the configured pins.
      */
     void reset() { ttn_reset(); }
 
@@ -453,8 +453,8 @@ public:
      * 
      * @param spi_host  The SPI bus/peripherial to use (`SPI_HOST`, `HSPI_HOST` or `VSPI_HOST`).
      * @param nss       The GPIO pin number connected to the radio chip's NSS pin (serving as the SPI chip select)
-     * @param rxtx      The GPIO pin number connected to the radio chip's RXTX pin (`TTN_NOT_CONNECTED` if not connected)
+     * @param rxtx      The GPIO pin number connected to the radio chip's RXTX pin (@ref TTN_NOT_CONNECTED if not connected)
-     * @param rst       The GPIO pin number connected to the radio chip's RST pin (`TTN_NOT_CONNECTED` if not connected)
+     * @param rst       The GPIO pin number connected to the radio chip's RST pin (@ref TTN_NOT_CONNECTED if not connected)
      * @param dio0      The GPIO pin number connected to the radio chip's DIO0 pin
      * @param dio1      The GPIO pin number connected to the radio chip's DIO1 pin
      */
@@ -483,7 +483,7 @@ public:
      * The provided DevEUI, AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
      * this function is called, `nvs_flash_init()` must have been called once.
      * 
-     * Call join() to activate the device.
+     * Call @ref join() to activate the device.
      * 
      * @param devEui  DevEUI (16 character string with hexadecimal data)
      * @param appEui  AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
@@ -497,7 +497,7 @@ public:
      * and without activating it.
      * 
      * The generated DevEUI and the provided AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
-     * this function is called, 'nvs_flash_init' must have been called once.
+     * this function is called, `nvs_flash_init` must have been called once.
      * 
      * The DevEUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a DevEUI
      * by adding FFFE in the middle. So the MAC address A0:B1:C2:01:02:03 becomes the EUI A0B1C2FFFE010203.
@@ -508,7 +508,7 @@ public:
      * it is okay for that the LoRa communication of your application can easily be intercepted and that
      * forged data can be injected.
      * 
-     * Call join() to activate.
+     * Call @ref join() to activate.
      * 
      * @param appEui  AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
      * @param appKey  AppKey of the device (32 character string with hexadecimal data)
@@ -528,7 +528,7 @@ public:
      * by the provisioning task.
      * 
      * If the device has already been provisioned (stored data in NVS, call of provision()
-     * or call of join(const char*, const char*, const char*), this function
+     * or call of @ref join(const char*, const char*, const char*), this function
      * immediately returns.
      */
     void waitForProvisioning() { ttn_wait_for_provisioning(); }
@@ -570,7 +570,7 @@ public:
      * @param length   number of bytes to be transmitted
      * @param port     port (defaults to 1)
      * @param confirm  flag indicating if a confirmation should be requested. Defaults to `false`
-     * @return `kTTNSuccessfulTransmission` for successful transmission, `kTTNErrorTransmissionFailed` for failed transmission, `kTTNErrorUnexpected` for unexpected error
+     * @return @ref kTTNSuccessfulTransmission for successful transmission, @ref kTTNErrorTransmissionFailed for failed transmission, @ref kTTNErrorUnexpected for unexpected error
      */
     TTNResponseCode transmitMessage(const uint8_t *payload, size_t length, ttn_port_t port = 1, bool confirm = false)
     {
@@ -585,9 +585,9 @@ public:
      * parameters. The values are only valid during the duration of the
      * callback. So they must be immediately processed or copied.
      * 
-     * Messages are received as a result of transmitMessage(). The callback is called
+     * Messages are received as a result of a call to @ref transmitMessage(). The callback is called
-     * in the task that called any of these functions and it occurs before these functions
+     * in the task that called this function and it occurs before this function
-     * return control to the caller.
+     * returns control to the caller.
      * 
      * @param callback  the callback function
      */
@@ -595,7 +595,7 @@ public:
 
     /**
      * @brief Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage
-     * or have been provided as by a call to join(const char*, const char*, const char*).
+     * or have been provided as by a call to @ref join(const char*, const char*, const char*).
      * 
      * @return `true` if they are stored, complete and of the correct size, `false` otherwise
      */
@@ -635,7 +635,7 @@ public:
      * If ADR is enabled, it's is used as the initial data rate and later adjusted depending
      * on the RF conditions. If ADR is disabled, it is used for all uplink messages.
      * 
-     * @param data_rate data rate (use constants kTTNDataRate_xx)
+     * @param data_rate data rate (use constants of enum @ref TTNDataRate)
      */
     void setDataRate(TTNDataRate data_rate) { ttn_set_data_rate(static_cast<ttn_data_rate_t>(data_rate)); }
 
@@ -643,7 +643,7 @@ public:
      * @brief Sets the maximum power for transmission
      * 
      * The power is specified in dBm and sets the power emitted by the radio.
-     * If the antenna has a gain, it must be substracted fro the specified value to
+     * If the antenna has a gain, it must be substracted from the specified value to
      * achieve the correct transmission power.
      * 
      * @param tx_pow power, in dBm
@@ -653,7 +653,7 @@ public:
     /**
      * @brief Stops all activies and shuts down the RF module and the background tasks.
      * 
-     * To restart communication, startup() and join() must be called.
+     * To restart communication, @ref startup() and @ref join() must be called.
      * it neither clears the provisioned keys nor the configured pins.
      */
     void shutdown() { ttn_shutdown(); }
@@ -673,7 +673,7 @@ public:
 
     /**
      * @brief Gets the RF settings for the specified window
-     * @param window RX/TX windows (valid values are `kTTNTxWindow`, `kTTNRx1Window` and `kTTNRx2Window`)
+     * @param window RX/TX window (valid values are @ref kTTNTxWindow, @ref kTTNRx1Window and @ref kTTNRx2Window)
      */
     TTNRFSettings getRFSettings(TTNRxTxWindow window);
 

include/ttn.h

@@ -11,9 +11,7 @@
  *******************************************************************************/
 
 /**
- * @file ttn.h
+ * @defgroup c_api C API
- * 
- * C interface for ttn-esp32
  */
 
 #ifndef TTN_C_H
@@ -27,6 +25,12 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup c_api
+ * 
+ * @{
+ */
+
 
 /**
  * @brief Constant for indicating that a pin is not connected
@@ -44,9 +48,13 @@ typedef uint8_t ttn_port_t;
  */
 typedef enum
 {
+    /** @brief Transmission failed error */
     TTN_ERROR_TRANSMISSION_FAILED = -1,
+    /** @brief Unexpected or internal error */
     TTN_ERROR_UNEXPECTED = -10,
+    /** @brief Successful transmission of an uplink message */
     TTN_SUCCESSFUL_TRANSMISSION = 1,
+    /** @brief Successful receipt of a downlink message */
     TTN_SUCCESSFUL_RECEIVE = 2
 } ttn_response_code_t;
 
@@ -427,14 +435,16 @@ typedef void (*ttn_message_cb)(const uint8_t* payload, size_t length, ttn_port_t
 
 
 /**
- * @brief Constructs a new The Things Network device instance.
+ * @brief Initializes The Things Network device instance.
+ * 
+ * Call this function once at the start of the program and before all other TTN functions.
  */
 void ttn_init(void);
 
 /**
  * @brief Resets the LoRaWAN radio.
  * 
- * To restart communication, join() must be called.
+ * To restart communication, @ref ttn_join() or @ref ttn_join_provisioned() must be called.
  * It neither clears the provisioned keys nor the configured pins.
  */
 void ttn_reset(void);
@@ -447,8 +457,8 @@ void ttn_reset(void);
  * 
  * @param spi_host  The SPI bus/peripherial to use (`SPI_HOST`, `HSPI_HOST` or `VSPI_HOST`).
  * @param nss       The GPIO pin number connected to the radio chip's NSS pin (serving as the SPI chip select)
- * @param rxtx      The GPIO pin number connected to the radio chip's RXTX pin (`TTN_NOT_CONNECTED` if not connected)
+ * @param rxtx      The GPIO pin number connected to the radio chip's RXTX pin (@ref TTN_NOT_CONNECTED if not connected)
- * @param rst       The GPIO pin number connected to the radio chip's RST pin (`TTN_NOT_CONNECTED` if not connected)
+ * @param rst       The GPIO pin number connected to the radio chip's RST pin (@ref TTN_NOT_CONNECTED if not connected)
  * @param dio0      The GPIO pin number connected to the radio chip's DIO0 pin
  * @param dio1      The GPIO pin number connected to the radio chip's DIO1 pin
  */
@@ -474,7 +484,7 @@ void ttn_set_subband(int band);
  * The provided DevEUI, AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
  * this function is called, `nvs_flash_init()` must have been called once.
  * 
- * Call join() to activate the device.
+ * Call @ref ttn_join_provisioned() to activate the device.
  * 
  * @param dev_eui  DevEUI (16 character string with hexadecimal data)
  * @param app_eui  AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
@@ -488,7 +498,7 @@ bool ttn_provision(const char *dev_eui, const char *app_eui, const char *app_key
  * and without activating it.
  * 
  * The generated DevEUI and the provided AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
- * this function is called, 'nvs_flash_init' must have been called once.
+ * this function is called, `nvs_flash_init` must have been called once.
  * 
  * The DevEUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a DevEUI
  * by adding FFFE in the middle. So the MAC address A0:B1:C2:01:02:03 becomes the EUI A0B1C2FFFE010203.
@@ -499,7 +509,7 @@ bool ttn_provision(const char *dev_eui, const char *app_eui, const char *app_key
  * it is okay for that the LoRa communication of your application can easily be intercepted and that
  * forged data can be injected.
  * 
- * Call join() to activate.
+ * Call @ref ttn_join_provisioned() to activate.
  * 
  * @param app_eui  AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
  * @param app_key  AppKey of the device (32 character string with hexadecimal data)
@@ -519,12 +529,11 @@ void ttn_start_provisioning_task(void);
  * by the provisioning task.
  * 
  * If the device has already been provisioned (stored data in NVS, call of provision()
- * or call of join(const char*, const char*, const char*), this function
+ * or call of @ref ttn_join(), this function immediately returns.
- * immediately returns.
  */
 void ttn_wait_for_provisioning(void);
 
-    /**
+/**
  * @brief Activates the device via OTAA.
  * 
  * The DevEUI, AppEUI/JoinEUI and AppKey must have already been provisioned by a call to provision().
@@ -561,7 +570,7 @@ bool ttn_join(const char *dev_eui, const char *app_eui, const char *app_key);
  * @param length   number of bytes to be transmitted
  * @param port     port (use 1 as default)
  * @param confirm  flag indicating if a confirmation should be requested (use `false` as default)
- * @return `kTTNSuccessfulTransmission` for successful transmission, `kTTNErrorTransmissionFailed` for failed transmission, `kTTNErrorUnexpected` for unexpected error
+ * @return @ref TTN_SUCCESSFUL_TRANSMISSION for successful transmission, @ref TTN_ERROR_TRANSMISSION_FAILED for failed transmission, @ref TTN_ERROR_UNEXPECTED for unexpected error
  */
 ttn_response_code_t ttn_transmit_message(const uint8_t *payload, size_t length, ttn_port_t port, bool confirm);
 
@@ -573,9 +582,9 @@ ttn_response_code_t ttn_transmit_message(const uint8_t *payload, size_t length,
  * parameters. The values are only valid during the duration of the
  * callback. So they must be immediately processed or copied.
  * 
- * Messages are received as a result of transmitMessage(). The callback is called
+ * Messages are received as a result of @ref ttn_transmit_message(). The callback is called
- * in the task that called any of these functions and it occurs before these functions
+ * in the task that called this function and it occurs before this function
- * return control to the caller.
+ * returns control to the caller.
  * 
  * @param callback  the callback function
  */
@@ -583,7 +592,7 @@ void ttn_on_message(ttn_message_cb callback);
 
 /**
  * @brief Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage
- * or have been provided as by a call to join(const char*, const char*, const char*).
+ * or have been provided as by a call to @ref ttn_join().
  * 
  * @return `true` if they are stored, complete and of the correct size, `false` otherwise
  */
@@ -623,7 +632,7 @@ void ttn_set_adr_enabled(bool enabled);
  * If ADR is enabled, it's is used as the initial data rate and later adjusted depending
  * on the RF conditions. If ADR is disabled, it is used for all uplink messages.
  * 
- * @param data_rate data rate (use constants TTN_DR_xx)
+ * @param data_rate data rate (use constants of enum @ref ttn_data_rate_t)
  */
 void ttn_set_data_rate(ttn_data_rate_t data_rate);
 
@@ -631,7 +640,7 @@ void ttn_set_data_rate(ttn_data_rate_t data_rate);
  * @brief Sets the maximum power for transmission
  * 
  * The power is specified in dBm and sets the power emitted by the radio.
- * If the antenna has a gain, it must be substracted fro the specified value to
+ * If the antenna has a gain, it must be substracted from the specified value to
  * achieve the correct transmission power.
  * 
  * @param tx_pow power, in dBm
@@ -641,7 +650,7 @@ void ttn_set_max_tx_pow(int tx_pow);
 /**
  * @brief Stops all activies and shuts down the RF module and the background tasks.
  * 
- * To restart communication, startup() and join() must be called.
+ * To restart communication, @ref ttn_startup() and @ref ttn_join() must be called.
  * it neither clears the provisioned keys nor the configured pins.
  */
 void ttn_shutdown(void);
@@ -661,7 +670,7 @@ ttn_rx_tx_window_t ttn_rx_tx_window(void);
 
 /**
  * @brief Gets the RF settings for the specified window
- * @param window RX/TX windows (valid values are `kTTNTxWindow`, `kTTNRx1Window` and `kTTNRx2Window`)
+ * @param window RX/TX window (valid values are @ref TTN_WINDOW_TX, @ref TTN_WINDOW_RX1 and @ref TTN_WINDOW_RX2
  */
 ttn_rf_settings_t ttn_get_rf_settings(ttn_rx_tx_window_t window);
 
@@ -693,6 +702,11 @@ ttn_rf_settings_t ttn_rx2_settings(void);
 int ttn_rssi();
 
 
+/**
+ * @}
+ */
+
+
 #ifdef __cplusplus
 }
 #endif