Skip to content

Commit 5fb383c

Browse files
author
Hasnain Virk
committed
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.
1 parent 2b95fd3 commit 5fb383c

17 files changed

+119
-37
lines changed

features/lorawan/LoRaWANInterface.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @file
33
*
4-
* @brief Implementation of LoRaWANBase
4+
* @brief A LoRaWAN network interface
55
*
66
* Copyright (c) 2017, Arm Limited and affiliates.
77
* SPDX-License-Identifier: Apache-2.0

features/lorawan/LoRaWANInterface.h

Lines changed: 59 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@
1515
* limitations under the License.
1616
*/
1717

18+
/** @addtogroup LoRaWAN
19+
* Mbed OS LoRaWAN Stack
20+
* @{
21+
*/
22+
1823
#ifndef LORAWANINTERFACE_H_
1924
#define LORAWANINTERFACE_H_
2025

@@ -25,8 +30,12 @@
2530
#include "LoRaRadio.h"
2631
#include "lorawan_types.h"
2732

33+
// Forward declaration of LoRaPHY class
2834
class LoRaPHY;
2935

36+
/** LoRaWANInterface Class
37+
* A network interface for LoRaWAN
38+
*/
3039
class LoRaWANInterface {
3140

3241
public:
@@ -341,8 +350,7 @@ class LoRaWANInterface {
341350
* LORAWAN_STATUS_PORT_INVALID if trying to send to an invalid port (e.g. to 0)
342351
* LORAWAN_STATUS_PARAMETER_INVALID if NULL data pointer is given or flags are invalid.
343352
*/
344-
int16_t send(uint8_t port, const uint8_t *data,
345-
uint16_t length, int flags);
353+
int16_t send(uint8_t port, const uint8_t *data, uint16_t length, int flags);
346354

347355
/** Receives a message from the Network Server on a specific port.
348356
*
@@ -409,34 +417,37 @@ class LoRaWANInterface {
409417
*
410418
* An example of using this API with a latch onto 'lorawan_events' could be:
411419
*
412-
* LoRaWANInterface lorawan(radio);
413-
* lorawan_app_callbacks_t cbs;
414-
* static void my_event_handler();
415-
*
416-
* int main()
417-
* {
418-
* lorawan.initialize();
419-
* cbs.lorawan_events = mbed::callback(my_event_handler);
420-
* lorawan.add_app_callbacks(&cbs);
421-
* lorawan.connect();
422-
* }
423-
*
424-
* static void my_event_handler(lorawan_event_t event)
425-
* {
426-
* switch(event) {
427-
* case CONNECTED:
428-
* //do something
429-
* break;
430-
* case DISCONNECTED:
431-
* //do something
432-
* break;
433-
* case TX_DONE:
434-
* //do something
435-
* break;
436-
* default:
437-
* break;
438-
* }
439-
* }
420+
*\code
421+
* LoRaWANInterface lorawan(radio);
422+
* lorawan_app_callbacks_t cbs;
423+
* static void my_event_handler();
424+
*
425+
* int main()
426+
* {
427+
* lorawan.initialize();
428+
* cbs.lorawan_events = mbed::callback(my_event_handler);
429+
* lorawan.add_app_callbacks(&cbs);
430+
* lorawan.connect();
431+
* }
432+
*
433+
* static void my_event_handler(lorawan_event_t event)
434+
* {
435+
* switch(event) {
436+
* case CONNECTED:
437+
* //do something
438+
* break;
439+
* case DISCONNECTED:
440+
* //do something
441+
* break;
442+
* case TX_DONE:
443+
* //do something
444+
* break;
445+
* default:
446+
* break;
447+
* }
448+
* }
449+
*
450+
*\endcode
440451
*
441452
* @param callbacks A pointer to the structure containing application callbacks.
442453
*
@@ -523,18 +534,35 @@ class LoRaWANInterface {
523534
*/
524535
lorawan_status_t cancel_sending(void);
525536

537+
/** Provides exclusive access to the stack.
538+
*
539+
* Use only if the stack is being run in it's own separate thread.
540+
*/
526541
void lock(void)
527542
{
528543
_lw_stack.lock();
529544
}
545+
546+
/** Releases exclusive access to the stack.
547+
*
548+
* Use only if the stack is being run in it's own separate thread.
549+
*/
530550
void unlock(void)
531551
{
532552
_lw_stack.unlock();
533553
}
534554

535555
private:
556+
/** ScopedLock object
557+
*
558+
* RAII style exclusive access
559+
*/
536560
typedef mbed::ScopedLock<LoRaWANInterface> Lock;
537561

562+
/** LoRaWANStack object
563+
*
564+
* Handle for the LoRaWANStack class
565+
*/
538566
LoRaWANStack _lw_stack;
539567

540568
/** PHY object if created by LoRaWANInterface
@@ -546,3 +574,4 @@ class LoRaWANInterface {
546574
};
547575

548576
#endif /* LORAWANINTERFACE_H_ */
577+
/** @}*/

features/lorawan/LoRaWANStack.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,9 @@
5353

5454
class LoRaPHY;
5555

56+
/** LoRaWANStack Class
57+
* A controller layer for LoRaWAN MAC and PHY
58+
*/
5659
class LoRaWANStack: private mbed::NonCopyable<LoRaWANStack> {
5760

5861
public:

features/lorawan/lorastack/mac/LoRaMac.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,9 @@
5656

5757
#include "platform/ScopedLock.h"
5858

59+
/** LoRaMac Class
60+
* Implementation of LoRaWAN MAC layer
61+
*/
5962
class LoRaMac {
6063

6164
public:

features/lorawan/lorastack/mac/LoRaMacCommand.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,9 @@
5151

5252
class LoRaMac;
5353

54+
/** LoRaMacCommand Class
55+
* Helper class for LoRaMac layer to handle any MAC commands
56+
*/
5457
class LoRaMacCommand {
5558

5659
public:

features/lorawan/lorastack/phy/LoRaPHY.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@
4040
#include "LoRaRadio.h"
4141
#include "lora_phy_ds.h"
4242

43+
/** LoRaPHY Class
44+
* Parent class for LoRa regional PHY implementations
45+
*/
4346
class LoRaPHY : private mbed::NonCopyable<LoRaPHY> {
4447

4548
public:

features/lorawan/lorastack/phy/LoRaPHYAS923.h

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@
3232
#ifndef MBED_OS_LORAPHY_AS923_H_
3333
#define MBED_OS_LORAPHY_AS923_H_
3434

35+
#if !(DOXYGEN_ONLY)
36+
3537
#include "LoRaPHY.h"
3638

3739
/*!
@@ -46,7 +48,6 @@
4648

4749
#define AS923_CHANNEL_MASK_SIZE 1
4850

49-
5051
class LoRaPHYAS923 : public LoRaPHY {
5152

5253
public:
@@ -68,4 +69,5 @@ class LoRaPHYAS923 : public LoRaPHY {
6869
uint16_t default_channel_mask[AS923_CHANNEL_MASK_SIZE];
6970
};
7071

72+
#endif /* DOXYGEN_ONLY*/
7173
#endif /* MBED_OS_LORAPHY_AS923_H_ */

features/lorawan/lorastack/phy/LoRaPHYAU915.h

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@
3333

3434
#define MBED_OS_LORAPHY_AU915_H_
3535

36+
#if !(DOXYGEN_ONLY)
37+
3638
#include "LoRaPHY.h"
3739

3840
// Definitions
@@ -48,7 +50,6 @@
4850

4951
#define AU915_CHANNEL_MASK_SIZE 5
5052

51-
5253
class LoRaPHYAU915 : public LoRaPHY {
5354

5455
public:
@@ -126,4 +127,6 @@ class LoRaPHYAU915 : public LoRaPHY {
126127
uint16_t default_channel_mask[AU915_CHANNEL_MASK_SIZE];
127128
};
128129

130+
#endif /* DOXYGEN_ONLY*/
129131
#endif /* MBED_OS_LORAPHY_AU915_H_ */
132+

features/lorawan/lorastack/phy/LoRaPHYCN470.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@
3232
#ifndef MBED_OS_LORAPHY_CN470_H_
3333
#define MBED_OS_LORAPHY_CN470_H_
3434

35+
#if !(DOXYGEN_ONLY)
36+
3537
#include "LoRaPHY.h"
3638

3739
// Definitions
@@ -94,4 +96,5 @@ class LoRaPHYCN470 : public LoRaPHY {
9496
uint16_t default_channel_mask[CN470_CHANNEL_MASK_SIZE];
9597
};
9698

99+
#endif /* DOXYGEN_ONLY*/
97100
#endif /* MBED_OS_LORAPHY_CN470_H_ */

features/lorawan/lorastack/phy/LoRaPHYCN779.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@
3232
#ifndef MBED_OS_LORAPHY_CN779_H_
3333
#define MBED_OS_LORAPHY_CN779_H_
3434

35+
#if !(DOXYGEN_ONLY)
36+
3537
#include "LoRaPHY.h"
3638

3739
#define CN779_MAX_NB_CHANNELS 16
@@ -70,4 +72,5 @@ class LoRaPHYCN779 : public LoRaPHY {
7072
uint16_t default_channel_mask[CN779_CHANNEL_MASK_SIZE];
7173
};
7274

75+
#endif /* DOXYGEN_ONLY*/
7376
#endif /* MBED_OS_LORAPHY_CN779_H_ */

0 commit comments

Comments
 (0)