Doxygen corrections

Adding group identidier so that LoRaWANInterface class goes to the class
hierarchy section rather than data-structures.

Adding missing documentation for a couple of public functions.

Adding \code and \endcode modifiers for the example code in the
documentation.

Adding compile time NO_DOXYGEN flag for the implementations of the
LoRaPHY Class.

Adding documentation for some of the private structures.

features/lorawan/LoRaWANInterface.cpp

@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @brief      Implementation of LoRaWANBase
+ * @brief      A LoRaWAN network interface
  *
  * Copyright (c) 2017, Arm Limited and affiliates.
  * SPDX-License-Identifier: Apache-2.0

features/lorawan/LoRaWANInterface.h

@@ -15,6 +15,11 @@
  * limitations under the License.
  */
 
+/** @addtogroup LoRaWAN
+ * Mbed OS LoRaWAN Stack
+ *  @{
+ */
+
 #ifndef LORAWANINTERFACE_H_
 #define LORAWANINTERFACE_H_
 
@@ -25,8 +30,12 @@
 #include "LoRaRadio.h"
 #include "lorawan_types.h"
 
+// Forward declaration of LoRaPHY class
 class LoRaPHY;
 
+/** LoRaWANInterface Class
+ * A network interface for LoRaWAN
+ */
 class LoRaWANInterface {
 
 public:
@@ -341,8 +350,7 @@ public:
      *                      LORAWAN_STATUS_PORT_INVALID      if trying to send to an invalid port (e.g. to 0)
      *                      LORAWAN_STATUS_PARAMETER_INVALID if NULL data pointer is given or flags are invalid.
      */
-    int16_t send(uint8_t port, const uint8_t *data,
+    int16_t send(uint8_t port, const uint8_t *data, uint16_t length, int flags);
-                         uint16_t length, int flags);
 
     /** Receives a message from the Network Server on a specific port.
      *
@@ -409,34 +417,37 @@ public:
      *
      * An example of using this API with a latch onto 'lorawan_events' could be:
      *
-     * LoRaWANInterface lorawan(radio);
+     *\code
-     * lorawan_app_callbacks_t cbs;
+     *  LoRaWANInterface lorawan(radio);
-     * static void my_event_handler();
+     *  lorawan_app_callbacks_t cbs;
+     *  static void my_event_handler();
      *
-     * int main()
+     *  int main()
-     * {
+     *  {
-     *   lorawan.initialize();
+     *      lorawan.initialize();
-     *   cbs.lorawan_events = mbed::callback(my_event_handler);
+     *      cbs.lorawan_events = mbed::callback(my_event_handler);
-     *   lorawan.add_app_callbacks(&cbs);
+     *      lorawan.add_app_callbacks(&cbs);
-     *   lorawan.connect();
+     *      lorawan.connect();
-     * }
+     *  }
      *
-     * static void my_event_handler(lorawan_event_t event)
+     *  static void my_event_handler(lorawan_event_t event)
-     * {
+     *  {
-     *   switch(event) {
+     *      switch(event) {
-     *      case CONNECTED:
+     *          case CONNECTED:
-     *          //do something
+     *              //do something
-     *          break;
+     *              break;
-     *      case DISCONNECTED:
+     *          case DISCONNECTED:
-     *          //do something
+     *              //do something
-     *          break;
+     *              break;
-     *      case TX_DONE:
+     *          case TX_DONE:
-     *          //do something
+     *              //do something
-     *          break;
+     *              break;
-     *      default:
+     *          default:
-     *          break;
+     *              break;
-     *   }
+     *      }
-     * }
+     *  }
+     *
+     *\endcode
      *
      * @param callbacks     A pointer to the structure containing application callbacks.
      *
@@ -523,18 +534,35 @@ public:
      */
     lorawan_status_t cancel_sending(void);
 
+    /** Provides exclusive access to the stack.
+     *
+     * Use only if the stack is being run in it's own separate thread.
+     */
     void lock(void)
     {
         _lw_stack.lock();
     }
+
+    /** Releases exclusive access to the stack.
+     *
+     * Use only if the stack is being run in it's own separate thread.
+     */
     void unlock(void)
     {
         _lw_stack.unlock();
     }
 
 private:
+    /** ScopedLock object
+     *
+     * RAII style exclusive access
+     */
     typedef mbed::ScopedLock<LoRaWANInterface> Lock;
 
+    /** LoRaWANStack object
+     *
+     * Handle for the LoRaWANStack class
+     */
     LoRaWANStack _lw_stack;
 
     /** PHY object if created by LoRaWANInterface
@@ -546,3 +574,4 @@ private:
 };
 
 #endif /* LORAWANINTERFACE_H_ */
+/** @}*/

features/lorawan/LoRaWANStack.h

@@ -53,6 +53,9 @@
 
 class LoRaPHY;
 
+/** LoRaWANStack Class
+ * A controller layer for LoRaWAN MAC and PHY
+ */
 class LoRaWANStack: private mbed::NonCopyable<LoRaWANStack> {
 
 public:

features/lorawan/lorastack/mac/LoRaMac.h

@@ -56,6 +56,9 @@
 
 #include "platform/ScopedLock.h"
 
+/** LoRaMac Class
+ * Implementation of LoRaWAN MAC layer
+ */
 class LoRaMac {
 
 public:

features/lorawan/lorastack/mac/LoRaMacCommand.h

@@ -51,6 +51,9 @@
 
 class LoRaMac;
 
+/** LoRaMacCommand Class
+ * Helper class for LoRaMac layer to handle any MAC commands
+ */
 class LoRaMacCommand {
 
 public:

features/lorawan/lorastack/phy/LoRaPHY.h

@@ -40,6 +40,9 @@
 #include "LoRaRadio.h"
 #include "lora_phy_ds.h"
 
+/** LoRaPHY Class
+ * Parent class for LoRa regional PHY implementations
+ */
 class LoRaPHY : private mbed::NonCopyable<LoRaPHY> {
 
 public:

features/lorawan/lorastack/phy/LoRaPHYAS923.h

@@ -32,6 +32,8 @@
 #ifndef MBED_OS_LORAPHY_AS923_H_
 #define MBED_OS_LORAPHY_AS923_H_
 
+#if !(DOXYGEN_ONLY)
+
 #include "LoRaPHY.h"
 
 /*!
@@ -46,7 +48,6 @@
 
 #define AS923_CHANNEL_MASK_SIZE                    1
 
-
 class LoRaPHYAS923 : public LoRaPHY {
 
 public:
@@ -68,4 +69,5 @@ private:
     uint16_t default_channel_mask[AS923_CHANNEL_MASK_SIZE];
 };
 
+#endif /* DOXYGEN_ONLY*/
 #endif /* MBED_OS_LORAPHY_AS923_H_ */

features/lorawan/lorastack/phy/LoRaPHYAU915.h

@@ -33,6 +33,8 @@
 
 #define MBED_OS_LORAPHY_AU915_H_
 
+#if !(DOXYGEN_ONLY)
+
 #include "LoRaPHY.h"
 
 // Definitions
@@ -48,7 +50,6 @@
 
 #define AU915_CHANNEL_MASK_SIZE                    5
 
-
 class LoRaPHYAU915 : public LoRaPHY {
 
 public:
@@ -126,4 +127,6 @@ private:
     uint16_t default_channel_mask[AU915_CHANNEL_MASK_SIZE];
 };
 
+#endif /* DOXYGEN_ONLY*/
 #endif /* MBED_OS_LORAPHY_AU915_H_ */
+

features/lorawan/lorastack/phy/LoRaPHYCN470.h

@@ -32,6 +32,8 @@
 #ifndef MBED_OS_LORAPHY_CN470_H_
 #define MBED_OS_LORAPHY_CN470_H_
 
+#if !(DOXYGEN_ONLY)
+
 #include "LoRaPHY.h"
 
 // Definitions
@@ -94,4 +96,5 @@ private:
     uint16_t default_channel_mask[CN470_CHANNEL_MASK_SIZE];
 };
 
+#endif /* DOXYGEN_ONLY*/
 #endif /* MBED_OS_LORAPHY_CN470_H_ */

features/lorawan/lorastack/phy/LoRaPHYCN779.h

@@ -32,6 +32,8 @@
 #ifndef MBED_OS_LORAPHY_CN779_H_
 #define MBED_OS_LORAPHY_CN779_H_
 
+#if !(DOXYGEN_ONLY)
+
 #include "LoRaPHY.h"
 
 #define CN779_MAX_NB_CHANNELS                       16
@@ -70,4 +72,5 @@ private:
     uint16_t default_channel_mask[CN779_CHANNEL_MASK_SIZE];
 };
 
+#endif /* DOXYGEN_ONLY*/
 #endif /* MBED_OS_LORAPHY_CN779_H_ */

features/lorawan/lorastack/phy/LoRaPHYEU433.h

@@ -32,6 +32,8 @@
 #ifndef MBED_OS_LORAPHY_EU433_H_
 #define MBED_OS_LORAPHY_EU433_H_
 
+#if !(DOXYGEN_ONLY)
+
 #include "LoRaPHY.h"
 
 /*!
@@ -76,5 +78,5 @@ private:
     uint16_t default_channel_mask[EU433_CHANNEL_MASK_SIZE];
 };
 
-
+#endif /* DOXYGEN_ONLY*/
 #endif /* MBED_OS_LORAPHY_EU433_H_ */

features/lorawan/lorastack/phy/LoRaPHYEU868.h

@@ -32,6 +32,8 @@
 #ifndef MBED_OS_LORAPHY_EU868_H_
 #define MBED_OS_LORAPHY_EU868_H_
 
+#if !(DOXYGEN_ONLY)
+
 #include "LoRaPHY.h"
 
 /*!
@@ -79,4 +81,5 @@ private:
     uint16_t default_channel_mask[EU868_CHANNEL_MASK_SIZE];
 };
 
+#endif /* DOXYGEN_ONLY*/
 #endif /* MBED_OS_LORAPHY_EU868_H_ */

features/lorawan/lorastack/phy/LoRaPHYIN865.h

@@ -32,8 +32,9 @@
 #ifndef MBED_OS_LORAPHY_IN865_H_
 #define MBED_OS_LORAPHY_IN865_H_
 
-#include "LoRaPHY.h"
+#if !(DOXYGEN_ONLY)
 
+#include "LoRaPHY.h"
 
 /*!
  * LoRaMac maximum number of channels
@@ -79,4 +80,5 @@ private:
     uint16_t default_channel_mask[IN865_CHANNEL_MASK_SIZE];
 };
 
+#endif /* DOXYGEN_ONLY */
 #endif /* MBED_OS_LORAPHY_IN865_H_ */

features/lorawan/lorastack/phy/LoRaPHYKR920.h

@@ -32,6 +32,8 @@
 #ifndef MBED_OS_LORAPHY_KR920_H_
 #define MBED_OS_LORAPHY_KR920_H_
 
+#if !(DOXYGEN_ONLY)
+
 #include "LoRaPHY.h"
 
 /*!
@@ -92,5 +94,6 @@ private:
     uint16_t default_channel_mask[KR920_CHANNEL_MASK_SIZE];
 };
 
+#endif /* DOXYGEN_ONLY */
 #endif // MBED_OS_LORAPHY_KR920_H_
 

features/lorawan/lorastack/phy/LoRaPHYUS915.h

@@ -32,6 +32,8 @@
 #ifndef MBED_OS_LORAPHYUS_915_H_
 #define MBED_OS_LORAPHYUS_915_H_
 
+#if !(DOXYGEN_ONLY)
+
 #include "LoRaPHY.h"
 
 /*!
@@ -129,4 +131,5 @@ private:
     uint16_t default_channel_mask[US915_CHANNEL_MASK_SIZE];
 };
 
+#endif /* DOXYGEN_ONLY */
 #endif /* MBED_OS_LORAPHY_US915_H_ */

features/lorawan/lorastack/phy/lora_phy_ds.h

@@ -480,21 +480,29 @@ typedef struct continuous_wave_mode_params_s {
     uint16_t timeout;
 } cw_mode_params_t;
 
+/*!
+ * Template for a table
+ */
 typedef struct {
     void *table;
     uint8_t size;
 } loraphy_table_t;
 
+/*!
+ * Contains information regarding channel configuration of
+ * a given PHY
+ */
 typedef struct {
-
     uint8_t channel_list_size;
     uint8_t  mask_size;
-
     uint16_t *mask;
     uint16_t *default_mask;
     channel_params_t *channel_list;
 } loraphy_channels_t;
 
+/*!
+ * Global configuration parameters of a given PHY
+ */
 typedef struct {
     bool duty_cycle_enabled;
     bool accept_tx_param_setup_req;

features/lorawan/system/lorawan_data_structures.h

@@ -1040,6 +1040,9 @@ typedef struct {
     int timer_id;
 } timer_event_t;
 
+/*!
+ * A composite structure containing device identifiers and security keys
+ */
 typedef struct {
     /*!
      * Device IEEE EUI
@@ -1070,6 +1073,9 @@ typedef struct {
 
 } loramac_keys;
 
+/*!
+ * A composite structure containing all the timers used in the LoRaWAN operation
+ */
 typedef struct {
     /*!
      * Aggregated duty cycle management
@@ -1107,6 +1113,9 @@ typedef struct {
 
 } lorawan_timers;
 
+/*!
+ * Global MAC layer configuration parameters
+ */
 typedef struct {
 
     /*!