diff --git a/include/openthread/border_agent_proxy.h b/include/openthread/border_agent_proxy.h index 29a46e532..420b67b54 100644 --- a/include/openthread/border_agent_proxy.h +++ b/include/openthread/border_agent_proxy.h @@ -48,7 +48,7 @@ extern "C" { #endif /** - * @addtogroup border-agent-proxy Border Agent Proxy + * @addtogroup api-border-agent * * @brief * This module includes functions for signal border agent proxy feature. diff --git a/include/openthread/child_supervision.h b/include/openthread/child_supervision.h index 549494830..9e8d5f40e 100644 --- a/include/openthread/child_supervision.h +++ b/include/openthread/child_supervision.h @@ -50,7 +50,7 @@ extern "C" { #if OPENTHREAD_ENABLE_CHILD_SUPERVISION /** - * @addtogroup child-supervision Child Supervision + * @addtogroup api-child-supervision * * @brief * This module includes functions for child supervision feature. diff --git a/include/openthread/cli.h b/include/openthread/cli.h index b22388d75..93d0a448d 100644 --- a/include/openthread/cli.h +++ b/include/openthread/cli.h @@ -43,6 +43,16 @@ extern "C" { #endif +/** + * @addtogroup api-cli + * + * @brief + * This module includes functions that control the Thread stack's execution. + * + * @{ + * + */ + /** * This function pointer is called to notify about Console output. * @@ -83,6 +93,11 @@ void otCliConsoleInputLine(char *aBuf, uint16_t aBufLength); */ void otCliUartInit(otInstance *aInstance); +/** + * @} + * + */ + #ifdef __cplusplus } // extern "C" #endif diff --git a/include/openthread/coap.h b/include/openthread/coap.h index da0704303..4c650e67b 100644 --- a/include/openthread/coap.h +++ b/include/openthread/coap.h @@ -51,7 +51,7 @@ extern "C" { #endif /** - * @addtogroup coap CoAP + * @addtogroup api-coap * * @brief * This module includes functions that control CoAP communication. @@ -75,11 +75,15 @@ typedef enum otCoapType } otCoapType; /** - * CoAP Code values. + * Helper macro to define CoAP Code values. * */ #define COAP_CODE(c, d) ((((c) & 0x7) << 5) | ((d) & 0x1f)) +/** + * CoAP Code values. + * + */ typedef enum otCoapCode { kCoapCodeEmpty = COAP_CODE(0, 0), ///< Empty message code diff --git a/include/openthread/commissioner.h b/include/openthread/commissioner.h index 28a02c527..cf9d61dff 100644 --- a/include/openthread/commissioner.h +++ b/include/openthread/commissioner.h @@ -29,7 +29,7 @@ /** * @file * @brief - * This file includes the platform abstraction for the Thread Commissioner role. + * This file includes functions for the Thread Commissioner role. */ #ifndef OPENTHREAD_COMMISSIONER_H_ @@ -43,7 +43,10 @@ extern "C" { #endif /** - * @addtogroup core-commissioning + * @addtogroup api-commissioner + * + * @brief + * This module includes functions for the Thread Commissioner role. * * @{ * @@ -102,7 +105,7 @@ OTAPI ThreadError OTCALL otCommissionerAddJoiner(otInstance *aInstance, const ot * @note Only use this after successfully started the Commissioner role by otCommissionerStart(). * */ -OTAPI ThreadError OTCALL otCommissionerRemoveJoiner(otInstance *aIntsance, const otExtAddress *aExtAddress); +OTAPI ThreadError OTCALL otCommissionerRemoveJoiner(otInstance *aInstance, const otExtAddress *aExtAddress); /** * This function sets the Provisioning URL. @@ -213,7 +216,7 @@ OTAPI ThreadError OTCALL otCommissionerPanIdQuery(otInstance *aInstance, uint16_ * @retval kThreadError_NoBufs Insufficient buffer space to send. * */ -OTAPI ThreadError OTCALL otCommissionerSendMgmtGet(otInstance *, const uint8_t *aTlvs, uint8_t aLength); +OTAPI ThreadError OTCALL otCommissionerSendMgmtGet(otInstance *aInstance, const uint8_t *aTlvs, uint8_t aLength); /** * This function sends MGMT_COMMISSIONER_SET. @@ -227,7 +230,7 @@ OTAPI ThreadError OTCALL otCommissionerSendMgmtGet(otInstance *, const uint8_t * * @retval kThreadError_NoBufs Insufficient buffer space to send. * */ -OTAPI ThreadError OTCALL otCommissionerSendMgmtSet(otInstance *, const otCommissioningDataset *aDataset, +OTAPI ThreadError OTCALL otCommissionerSendMgmtSet(otInstance *aInstance, const otCommissioningDataset *aDataset, const uint8_t *aTlvs, uint8_t aLength); /** @@ -238,7 +241,7 @@ OTAPI ThreadError OTCALL otCommissionerSendMgmtSet(otInstance *, const otCommiss * @returns The current commissioner session id. * */ -OTAPI uint16_t OTCALL otCommissionerGetSessionId(otInstance *); +OTAPI uint16_t OTCALL otCommissionerGetSessionId(otInstance *aInstance); /** * This function returns the Commissioner State. @@ -250,7 +253,7 @@ OTAPI uint16_t OTCALL otCommissionerGetSessionId(otInstance *); * @retval kCommissionerStateActive Commissioner enabled. * */ -OTAPI otCommissionerState OTCALL otCommissionerGetState(otInstance *); +OTAPI otCommissionerState OTCALL otCommissionerGetState(otInstance *aInstance); /** * This method generates PSKc. diff --git a/include/openthread/crypto.h b/include/openthread/crypto.h index 9f9f5a776..d80a45af8 100644 --- a/include/openthread/crypto.h +++ b/include/openthread/crypto.h @@ -42,6 +42,16 @@ extern "C" { #endif +/** + * @addtogroup api-crypto + * + * @brief + * This module includes cryptographic functions. + * + * @{ + * + */ + #define OT_CRYPTO_HMAC_SHA_HASH_SIZE 32 ///< Length of HMAC SHA (in bytes). /** @@ -87,6 +97,10 @@ void otCryptoAesCcm( void *aPlainText, void *aCipherText, uint32_t aLength, bool aEncrypt, void *aTag); +/** + * @} + * + */ #ifdef __cplusplus } // extern "C" diff --git a/include/openthread/dataset.h b/include/openthread/dataset.h index 849639178..0124f1bac 100644 --- a/include/openthread/dataset.h +++ b/include/openthread/dataset.h @@ -42,10 +42,7 @@ extern "C" { #endif /** - * @addtogroup dataset Operational Dataset - * - * @brief - * This module includes functions for Operational Dataset configuration. + * @addtogroup api-thread-general * * @{ * diff --git a/include/openthread/dataset_ftd.h b/include/openthread/dataset_ftd.h index 71426e845..3e9e8ff5b 100644 --- a/include/openthread/dataset_ftd.h +++ b/include/openthread/dataset_ftd.h @@ -42,10 +42,7 @@ extern "C" { #endif /** - * @addtogroup dataset Operational Dataset - * - * @brief - * This module includes functions for Operational Dataset configuration for FTD. + * @addtogroup api-thread-general * * @{ * diff --git a/include/openthread/dhcp6_client.h b/include/openthread/dhcp6_client.h index dd26a86c3..ebdfa8f24 100644 --- a/include/openthread/dhcp6_client.h +++ b/include/openthread/dhcp6_client.h @@ -42,7 +42,7 @@ extern "C" { #endif /** - * @addtogroup core-dhcp6-client + * @addtogroup api-dhcp6 * * @{ * diff --git a/include/openthread/dhcp6_server.h b/include/openthread/dhcp6_server.h index c8c019bd8..429fefcd2 100644 --- a/include/openthread/dhcp6_server.h +++ b/include/openthread/dhcp6_server.h @@ -42,14 +42,14 @@ extern "C" { #endif /** - * @addtogroup core-dhcp6-server + * @addtogroup api-dhcp6 * * @{ * */ /** - * Update updates DHCP Agents and DHCP Alocs. + * Updates DHCP Agents and DHCP Alocs. * * @param[in] aInstance A pointer to an OpenThread instance. * diff --git a/include/openthread/diag.h b/include/openthread/diag.h index 68aaedb46..a59844dd8 100644 --- a/include/openthread/diag.h +++ b/include/openthread/diag.h @@ -41,14 +41,58 @@ extern "C" { #endif +/** + * @addtogroup api-factory-diagnostics + * + * @brief + * This module includes functions that control the Thread stack's execution. + * + * @{ + * + */ + +/** + * Initialize the diagnostics module. + * + * @param[in] aInstance A pointer to the OpenThread instance. + * + */ void otDiagInit(otInstance *aInstance); +/** + * This function processes a factory diagnostics command line. + * + * @param[in] argc The argument counter of diagnostics command line. + * @param[in] argv The argument vector of diagnostics command line. + * + * @returns A pointer to the output string. + * + */ char *otDiagProcessCmd(int argc, char *argv[]); -char *otDiagProcessCmdLine(char *string); +/** + * This function processes a factory diagnostics command line. + * + * @param[in] aString A NULL-terminated string. + * + * @returns A pointer to the output string. + * + */ +char *otDiagProcessCmdLine(char *aString); +/** + * This function indicates whether or not the factory diagnostics mode is enabled. + * + * @returns TRUE if factory diagnostics mode is enabled, FALSE otherwise. + * + */ bool otDiagIsEnabled(void); +/** + * @} + * + */ + #ifdef __cplusplus } // extern "C" #endif diff --git a/include/openthread/dns.h b/include/openthread/dns.h index 978d19158..34eb90837 100644 --- a/include/openthread/dns.h +++ b/include/openthread/dns.h @@ -49,7 +49,7 @@ extern "C" { #endif /** - * @addtogroup dns DNS + * @addtogroup api-dns * * @brief * This module includes functions that control DNS communication. diff --git a/include/openthread/icmp6.h b/include/openthread/icmp6.h index ef3c6b300..84c9ee9f9 100644 --- a/include/openthread/icmp6.h +++ b/include/openthread/icmp6.h @@ -42,9 +42,8 @@ extern "C" { #endif - /** - * @addtogroup icmp6 ICMPv6 + * @addtogroup api-icmp6 * * @brief * This module includes functions that control ICMPv6 communication. diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 930de9a22..e192e6b2e 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -43,7 +43,7 @@ extern "C" { #endif /** - * @addtogroup instance Instance + * @addtogroup api-instance * * @brief * This module includes functions that control the OpenThread Instance. @@ -225,9 +225,9 @@ OTAPI ThreadError OTCALL otSetStateChangedCallback(otInstance *aInstance, otStat /** * This function removes a callback to indicate when certain configuration or state changes within OpenThread. * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. - * @param[in] aContext A pointer to application-specific context. + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. + * @param[in] aCallbackContext A pointer to application-specific context. * */ OTAPI void OTCALL otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback aCallback, diff --git a/include/openthread/ip6.h b/include/openthread/ip6.h index ddd3bb17b..ebb2308a8 100644 --- a/include/openthread/ip6.h +++ b/include/openthread/ip6.h @@ -43,7 +43,7 @@ extern "C" { #endif /** - * @addtogroup ip6 IPv6 + * @addtogroup api-ip6 * * @brief * This module includes functions that control IPv6 communication. diff --git a/include/openthread/jam_detection.h b/include/openthread/jam_detection.h index 5934c9f1b..0e64d67a0 100644 --- a/include/openthread/jam_detection.h +++ b/include/openthread/jam_detection.h @@ -50,7 +50,7 @@ extern "C" { #if OPENTHREAD_ENABLE_JAM_DETECTION /** - * @addtogroup jam-det Jamming Detection + * @addtogroup api-jam-detection * * @brief * This module includes functions for signal jamming detection feature. diff --git a/include/openthread/joiner.h b/include/openthread/joiner.h index 92c746cfc..e4a7c547c 100644 --- a/include/openthread/joiner.h +++ b/include/openthread/joiner.h @@ -29,7 +29,7 @@ /** * @file * @brief - * This file includes the platform abstraction for the Thread Joiner role. + * This file includes functions for the Thread Joiner role. */ #ifndef OPENTHREAD_JOINER_H_ @@ -43,7 +43,10 @@ extern "C" { #endif /** - * @addtogroup core-commissioning + * @addtogroup api-joiner + * + * @brief + * This module includes functions for the Thread Joiner role. * * @{ * @@ -80,7 +83,7 @@ typedef void (OTCALL *otJoinerCallback)(ThreadError aError, void *aContext); */ OTAPI ThreadError OTCALL otJoinerStart(otInstance *aInstance, const char *aPSKd, const char *aProvisioningUrl, const char *aVendorName, const char *aVendorModel, - const char *aVendorSwVersion, const char *aVendordata, + const char *aVendorSwVersion, const char *aVendorData, otJoinerCallback aCallback, void *aContext); /** diff --git a/include/openthread/link.h b/include/openthread/link.h index a176b0e0d..bdb95a7dc 100644 --- a/include/openthread/link.h +++ b/include/openthread/link.h @@ -43,7 +43,7 @@ extern "C" { #endif /** - * @addtogroup link Link + * @addtogroup api-link-link * * @brief * This module includes functions that control link-layer configuration. @@ -171,9 +171,9 @@ OTAPI uint8_t OTCALL otLinkGetChannel(otInstance *aInstance); * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aChannel The IEEE 802.15.4 channel. * - * @retval kThreadErrorNone Successfully set the channel. - * @retval kThreadErrorInvalidArgs If @p aChnanel is not in the range [11, 26]. - * @retrval kThreadError_InvalidState Thread protocols are enabled. + * @retval kThreadErrorNone Successfully set the channel. + * @retval kThreadErrorInvalidArgs If @p aChnanel is not in the range [11, 26]. + * @retval kThreadError_InvalidState Thread protocols are enabled. * * @sa otLinkGetChannel */ @@ -475,7 +475,7 @@ OTAPI void OTCALL otLinkClearBlacklist(otInstance *aInstance); * Enable MAC Blacklist filtering. * * @param[in] aInstance A pointer to an OpenThread instance. - * @parma[in] aEnabled TRUE to enable the blacklist, FALSE otherwise. + * @param[in] aEnabled TRUE to enable the blacklist, FALSE otherwise. * * @sa otLinkAddBlacklist * @sa otLinkRemoveBlacklist diff --git a/include/openthread/link_raw.h b/include/openthread/link_raw.h index 09748bec6..a35cccd70 100644 --- a/include/openthread/link_raw.h +++ b/include/openthread/link_raw.h @@ -43,7 +43,7 @@ extern "C" { #endif /** - * @addtogroup linkraw Link Raw + * @addtogroup api-link-raw * * @brief * This module includes functions that control the raw link-layer configuration. diff --git a/include/openthread/message.h b/include/openthread/message.h index 463a5c19f..aa892935e 100644 --- a/include/openthread/message.h +++ b/include/openthread/message.h @@ -42,7 +42,7 @@ extern "C" { #endif /** - * @addtogroup messages Message Buffers + * @addtogroup api-message * * @brief * This module includes functions that manipulate OpenThread message buffers diff --git a/include/openthread/ncp.h b/include/openthread/ncp.h index f77907a5d..d0972eb15 100644 --- a/include/openthread/ncp.h +++ b/include/openthread/ncp.h @@ -41,6 +41,16 @@ extern "C" { #endif +/** + * @addtogroup api-ncp + * + * @brief + * This module includes functions that control the Thread stack's execution. + * + * @{ + * + */ + /** * Initialize the NCP. * @@ -122,11 +132,10 @@ typedef void (*otNcpHandlerSetLegacyUlaPrefix)(const uint8_t *aUlaPrefix); */ typedef struct otNcpLegacyHandlers { - otNcpHandlerStartLegacy mStartLegacy; - otNcpHandlerStopLegacy mStopLegacy; - otNcpHandlerJoinLegacyNode mJoinLegacyNode; - otNcpHandlerSetLegacyUlaPrefix mSetLegacyUlaPrefix; - + otNcpHandlerStartLegacy mStartLegacy; ///< Start handler + otNcpHandlerStopLegacy mStopLegacy; ///< Stop handler + otNcpHandlerJoinLegacyNode mJoinLegacyNode; ///< Join handler + otNcpHandlerSetLegacyUlaPrefix mSetLegacyUlaPrefix; ///< Set ULA handler } otNcpLegacyHandlers; /** @@ -154,6 +163,10 @@ void otNcpHandleDidReceiveNewLegacyUlaPrefix(const uint8_t *aUlaPrefix); */ void otNcpRegisterLegacyHandlers(const otNcpLegacyHandlers *aHandlers); +/** + * @} + * + */ #ifdef __cplusplus } // extern "C" diff --git a/include/openthread/netdata.h b/include/openthread/netdata.h index 9bf1d8926..dcea55d5b 100644 --- a/include/openthread/netdata.h +++ b/include/openthread/netdata.h @@ -42,10 +42,7 @@ extern "C" { #endif /** - * @addtogroup netdata Network Data - * - * @brief - * This module includes functions that control Network Data configuration. + * @addtogroup api-thread-general * * @{ * diff --git a/include/openthread/openthread.h b/include/openthread/openthread.h index 144b995b6..aeb47a295 100644 --- a/include/openthread/openthread.h +++ b/include/openthread/openthread.h @@ -57,14 +57,65 @@ extern "C" { * * @{ * - * @defgroup execution Execution - * @defgroup commands Commands - * @defgroup config Configuration - * @defgroup diags Diagnostics - * @defgroup messages Message Buffers - * @defgroup ip6 IPv6 - * @defgroup udp UDP - * @defgroup coap CoAP + * @defgroup api-execution Execution + * + * @{ + * + * @defgroup api-instance Instance + * @defgroup api-tasklets Tasklets + * + * @} + * + * @defgroup api-net IPv6 Networking + * @{ + * + * @defgroup api-dhcp6 DHCPv6 + * @brief This module includes functions for DHCPv6 Client and Server. + * @defgroup api-dns DNSv6 + * @defgroup api-icmp6 ICMPv6 + * @defgroup api-ip6 IPv6 + * @defgroup api-udp UDP + * + * @} + * + * @defgroup api-link Link + * + * @{ + * + * @defgroup api-link-link Link + * @defgroup api-link-raw Raw Link + * + * @} + * + * @defgroup api-message Message + * + * @defgroup api-thread Thread + * + * @{ + * + * @defgroup api-border-agent Border Agent + * @defgroup api-commissioner Commissioner + * @defgroup api-thread-general General + * @brief This module includes functions for all Thread roles. + * @defgroup api-joiner Joiner + * @defgroup api-thread-router Router/Leader + * @brief This module includes functions for Thread Routers and Leaders. + * + * @} + * + * @defgroup api-addons Add-Ons + * + * @{ + * + * @defgroup api-child-supervision Child Supervision + * @defgroup api-coap CoAP + * @defgroup api-cli Command Line Interface + * @defgroup api-crypto Crypto + * @defgroup api-factory-diagnostics Factory Diagnostics + * @defgroup api-jam-detection Jam Detection + * @defgroup api-ncp Network Co-Processor + * + * @} * * @} * @@ -76,42 +127,24 @@ extern "C" { * This module includes the platform abstraction used by the OpenThread stack. * * @{ - * @} * - */ - -/** - * @defgroup core Core - * @brief - * This module includes the core OpenThread stack. - * - * @{ - * - * @defgroup core-6lowpan 6LoWPAN - * @defgroup core-coap CoAP - * @defgroup core-global-address Global IPv6 Address - * @defgroup core-ipv6 IPv6 - * @defgroup core-mac MAC - * @defgroup core-mesh-forwarding Mesh Forwarding - * @defgroup core-data-poll-manager Data Poll Manager - * @defgroup core-source-match-controller Source Address Match Controller - * @defgroup core-message Message - * @defgroup core-mle MLE - * @defgroup core-netdata Network Data - * @defgroup core-netif Network Interface - * @defgroup core-arp RLOC Mapping - * @defgroup core-security Security - * @defgroup core-tasklet Tasklet - * @defgroup core-timer Timer - * @defgroup core-udp UDP - * @defgroup core-tcp TCP - * @defgroup core-link-quality Link Quality + * @defgroup plat-alarm Alarm + * @defgroup plat-factory-diagnostics Factory Diagnostics + * @defgroup plat-logging Logging + * @defgroup plat-memory Memory + * @defgroup plat-messagepool Message Pool + * @defgroup plat-misc Miscellaneous + * @defgroup plat-radio Radio + * @defgroup plat-random Random + * @defgroup plat-settings Settings + * @defgroup plat-spi-slave SPI Slave + * @defgroup plat-toolchain Toolchain + * @defgroup plat-uart UART * * @} * */ - /** * Get the OpenThread version string. * diff --git a/include/openthread/platform/alarm.h b/include/openthread/platform/alarm.h index 7df8d258a..2ffeb44af 100644 --- a/include/openthread/platform/alarm.h +++ b/include/openthread/platform/alarm.h @@ -44,8 +44,7 @@ extern "C" { #endif /** - * @defgroup alarm Alarm - * @ingroup platform + * @addtogroup plat-alarm * * @brief * This module includes the platform abstraction for the alarm service. diff --git a/include/openthread/platform/diag.h b/include/openthread/platform/diag.h index 2062301f3..c3e661ed7 100644 --- a/include/openthread/platform/diag.h +++ b/include/openthread/platform/diag.h @@ -47,8 +47,7 @@ extern "C" { #endif /** - * @defgroup diag Diag - * @ingroup platform + * @addtogroup plat-factory-diagnostics * * @brief * This module includes the platform abstraction for diagnostics features. @@ -58,52 +57,72 @@ extern "C" { */ /** - * Process the platform specific diagnostics features. + * This function processes a factory diagnostics command line. * * @param[in] aInstance The OpenThread instance for current request. * @param[in] argc The argument counter of diagnostics command line. * @param[in] argv The argument vector of diagnostics command line. * @param[out] aOutput The diagnostics execution result. * @param[in] aOutputMaxLen The output buffer size. + * */ void otPlatDiagProcess(otInstance *aInstance, int argc, char *argv[], char *aOutput, size_t aOutputMaxLen); /** - * Set diagnostics mode. + * This function enables/disables the factory diagnostics mode. + * + * @param[in] aMode TRUE to enable diagnostics mode, FALSE otherwise. + * */ void otPlatDiagModeSet(bool aMode); /** - * Get diagnostics mode. + * This function indicates whether or not factory diagnostics mode is enabled. + * + * @returns TRUE if factory diagnostics mode is enabled, FALSE otherwise. + * */ bool otPlatDiagModeGet(void); /** - * Set diagnostics channel. + * This function sets the channel to use for factory diagnostics. + * + * @param[in] aChannel The channel value. + * */ void otPlatDiagChannelSet(uint8_t aChannel); /** - * Set diagnostics tx power. + * This function sets the transmit power to use for factory diagnostics. + * + * @param[in] aTxPower The transmit power value. + * */ void otPlatDiagTxPowerSet(int8_t aTxPower); /** - * Process the platform specific received frame parsing. + * This function processes the received radio frame. * * @param[in] aInstance The OpenThread instance for current request. * @param[in] aFrame The received radio frame. * @param[in] aError The received radio frame status. + * */ void otPlatDiagRadioReceived(otInstance *aInstance, RadioPacket *aFrame, ThreadError aError); /** - * Process the platform specific alarm callback. + * This function processes the alarm event. * * @param[in] aInstance The OpenThread instance for current request. + * */ void otPlatDiagAlarmCallback(otInstance *aInstance); +/** + * @} + * + */ + #ifdef __cplusplus } // end of extern "C" #endif diff --git a/include/openthread/platform/logging.h b/include/openthread/platform/logging.h index 90d90db96..1b518cf88 100644 --- a/include/openthread/platform/logging.h +++ b/include/openthread/platform/logging.h @@ -42,8 +42,7 @@ extern "C" { #endif /** - * @defgroup logging Logging - * @ingroup platform + * @addtogroup plat-logging * * @brief * This module includes the platform abstraction for the debug log service. @@ -52,11 +51,14 @@ extern "C" { * */ -#define OPENTHREAD_LOG_LEVEL_NONE 0 -#define OPENTHREAD_LOG_LEVEL_CRIT 1 -#define OPENTHREAD_LOG_LEVEL_WARN 2 -#define OPENTHREAD_LOG_LEVEL_INFO 3 -#define OPENTHREAD_LOG_LEVEL_DEBG 4 +/** + * Log levels. + */ +#define OPENTHREAD_LOG_LEVEL_NONE 0 ///< None +#define OPENTHREAD_LOG_LEVEL_CRIT 1 ///< Critical +#define OPENTHREAD_LOG_LEVEL_WARN 2 ///< Warning +#define OPENTHREAD_LOG_LEVEL_INFO 3 ///< Info +#define OPENTHREAD_LOG_LEVEL_DEBG 4 ///< Debug /** * This enum represents different log levels. diff --git a/include/openthread/platform/memory.h b/include/openthread/platform/memory.h index e1b9db0c2..c9a1fec93 100644 --- a/include/openthread/platform/memory.h +++ b/include/openthread/platform/memory.h @@ -40,8 +40,7 @@ extern "C" { #endif /** - * @defgroup memory Memory - * @ingroup platform + * @addtogroup plat-memory * * @brief * This module includes the platform abstraction for dynamic memory allocation. diff --git a/include/openthread/platform/messagepool.h b/include/openthread/platform/messagepool.h index c464465d8..b9a7eaed8 100644 --- a/include/openthread/platform/messagepool.h +++ b/include/openthread/platform/messagepool.h @@ -41,8 +41,7 @@ #include /** - * @defgroup messagepool MessagePool - * @ingroup platform + * @addtogroup plat-messagepool * * @brief * This module includes the platform abstraction for the message pool. @@ -58,6 +57,7 @@ extern "C" { /** * Initialize the platform implemented message pool. * + * @param[in] aInstance A pointer to the OpenThread instance. * @param[in] aMinNumFreeBuffers An uint16 containing the minimum number of free buffers desired by OpenThread. * @param[in] aBufferSize The size in bytes of a Buffer object. * @@ -67,6 +67,8 @@ void otPlatMessagePoolInit(otInstance *aInstance, uint16_t aMinNumFreeBuffers, s /** * Allocate a buffer from the platform managed buffer pool. * + * @param[in] aInstance A pointer to the OpenThread instance. + * * @returns A pointer to the Buffer or NULL if no Buffers are available. * */ @@ -75,7 +77,8 @@ otMessage *otPlatMessagePoolNew(otInstance *aInstance); /** * This function is used to free a Buffer back to the platform managed buffer pool. * - * @param[in] aBuffer The Buffer to free. + * @param[in] aInstance A pointer to the OpenThread instance. + * @param[in] aBuffer The Buffer to free. * */ void otPlatMessagePoolFree(otInstance *aInstance, otMessage *aBuffer); @@ -83,6 +86,8 @@ void otPlatMessagePoolFree(otInstance *aInstance, otMessage *aBuffer); /** * Get the number of free buffers. * + * @param[in] aInstance A pointer to the OpenThread instance. + * * @returns The number of buffers currently free and available to OpenThread. * */ diff --git a/include/openthread/platform/misc.h b/include/openthread/platform/misc.h index 5e5f4ebda..e22b5d238 100644 --- a/include/openthread/platform/misc.h +++ b/include/openthread/platform/misc.h @@ -43,6 +43,16 @@ extern "C" { #endif +/** + * @addtogroup plat-misc + * + * @brief + * This module includes platform abstractions for miscellaneous behaviors. + * + * @{ + * + */ + /** * This function performs a software reset on the platform, if supported. * @@ -89,6 +99,11 @@ otPlatResetReason otPlatGetResetReason(otInstance *aInstance); */ void otPlatAssertFail(const char *aFilename, int aLineNumber); +/** + * @} + * + */ + #ifdef __cplusplus } // extern "C" #endif diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h index 230e6d8e4..f36f4fbd5 100644 --- a/include/openthread/platform/radio.h +++ b/include/openthread/platform/radio.h @@ -45,8 +45,7 @@ extern "C" { #endif /** - * @defgroup radio Radio - * @ingroup platform + * @addtogroup plat-radio * * @brief * This module includes the platform abstraction for radio communication. @@ -220,8 +219,8 @@ PhyState otPlatRadioGetState(otInstance *aInstance); * * @param[in] aInstance The OpenThread instance structure. * - * @retval ::kThreadError_None Successfully enabled. - * @retval ::kThreadError_Failure The radio could not be enabled. + * @retval kThreadError_None Successfully enabled. + * @retval kThreadError_Failure The radio could not be enabled. */ ThreadError otPlatRadioEnable(otInstance *aInstance); @@ -230,7 +229,7 @@ ThreadError otPlatRadioEnable(otInstance *aInstance); * * @param[in] aInstance The OpenThread instance structure. * - * @retval ::kThreadError_None Successfully transitioned to Disabled. + * @retval kThreadError_None Successfully transitioned to Disabled. */ ThreadError otPlatRadioDisable(otInstance *aInstance); @@ -239,8 +238,8 @@ ThreadError otPlatRadioDisable(otInstance *aInstance); * * @param[in] aInstance The OpenThread instance structure. * - * @retval ::true radio is enabled. - * @retval ::false radio is disabled. + * @returns TRUE if the radio is enabled, FALSE otherwise. + * */ bool otPlatRadioIsEnabled(otInstance *aInstance); @@ -250,9 +249,9 @@ bool otPlatRadioIsEnabled(otInstance *aInstance); * * @param[in] aInstance The OpenThread instance structure. * - * @retval ::kThreadError_None Successfully transitioned to Sleep. - * @retval ::kThreadError_Busy The radio was transmitting - * @retval ::kThreadError_InvalidState The radio was disabled + * @retval kThreadError_None Successfully transitioned to Sleep. + * @retval kThreadError_Busy The radio was transmitting + * @retval kThreadError_InvalidState The radio was disabled */ ThreadError otPlatRadioSleep(otInstance *aInstance); @@ -263,8 +262,8 @@ ThreadError otPlatRadioSleep(otInstance *aInstance); * @param[in] aInstance The OpenThread instance structure. * @param[in] aChannel The channel to use for receiving. * - * @retval ::kThreadError_None Successfully transitioned to Receive. - * @retval ::kThreadError_InvalidState The radio was disabled or transmitting. + * @retval kThreadError_None Successfully transitioned to Receive. + * @retval kThreadError_InvalidState The radio was disabled or transmitting. */ ThreadError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel); @@ -293,8 +292,8 @@ void otPlatRadioEnableSrcMatch(otInstance *aInstance, bool aEnable); * @param[in] aInstance The OpenThread instance structure. * @param[in] aShortAddress The short address to be added. * - * @retval ::kThreadError_None Successfully added short address to the source match table. - * @retval ::kThreadError_NoBufs No available entry in the source match table. + * @retval kThreadError_None Successfully added short address to the source match table. + * @retval kThreadError_NoBufs No available entry in the source match table. */ ThreadError otPlatRadioAddSrcMatchShortEntry(otInstance *aInstance, const uint16_t aShortAddress); @@ -304,8 +303,8 @@ ThreadError otPlatRadioAddSrcMatchShortEntry(otInstance *aInstance, const uint16 * @param[in] aInstance The OpenThread instance structure. * @param[in] aExtAddress The extended address to be added. * - * @retval ::kThreadError_None Successfully added extended address to the source match table. - * @retval ::kThreadError_NoBufs No available entry in the source match table. + * @retval kThreadError_None Successfully added extended address to the source match table. + * @retval kThreadError_NoBufs No available entry in the source match table. */ ThreadError otPlatRadioAddSrcMatchExtEntry(otInstance *aInstance, const uint8_t *aExtAddress); @@ -315,8 +314,8 @@ ThreadError otPlatRadioAddSrcMatchExtEntry(otInstance *aInstance, const uint8_t * @param[in] aInstance The OpenThread instance structure. * @param[in] aShortAddress The short address to be removed. * - * @retval ::kThreadError_None Successfully removed short address from the source match table. - * @retval ::kThreadError_NoAddress The short address is not in source address match table. + * @retval kThreadError_None Successfully removed short address from the source match table. + * @retval kThreadError_NoAddress The short address is not in source address match table. */ ThreadError otPlatRadioClearSrcMatchShortEntry(otInstance *aInstance, const uint16_t aShortAddress); @@ -326,8 +325,8 @@ ThreadError otPlatRadioClearSrcMatchShortEntry(otInstance *aInstance, const uint * @param[in] aInstance The OpenThread instance structure. * @param[in] aExtAddress The extended address to be removed. * - * @retval ::kThreadError_None Successfully removed the extended address from the source match table. - * @retval ::kThreadError_NoAddress The extended address is not in source address match table. + * @retval kThreadError_None Successfully removed the extended address from the source match table. + * @retval kThreadError_NoAddress The extended address is not in source address match table. */ ThreadError otPlatRadioClearSrcMatchExtEntry(otInstance *aInstance, const uint8_t *aExtAddress); @@ -352,8 +351,8 @@ void otPlatRadioClearSrcMatchExtEntries(otInstance *aInstance); * * @param[in] aInstance The OpenThread instance structure. * @param[in] aPacket A pointer to the received packet or NULL if the receive operation failed. - * @param[in] aError ::kThreadError_None when successfully received a frame, ::kThreadError_Abort when reception - * was aborted and a frame was not received, ::kThreadError_NoBufs when a frame could not be + * @param[in] aError kThreadError_None when successfully received a frame, kThreadError_Abort when reception + * was aborted and a frame was not received, kThreadError_NoBufs when a frame could not be * received due to lack of rx buffer space. * */ @@ -385,8 +384,8 @@ RadioPacket *otPlatRadioGetTransmitBuffer(otInstance *aInstance); * @param[in] aInstance The OpenThread instance structure. * @param[in] aPacket A pointer to the packet that will be transmitted. * - * @retval ::kThreadError_None Successfully transitioned to Transmit. - * @retval ::kThreadError_InvalidState The radio was not in the Receive state. + * @retval kThreadError_None Successfully transitioned to Transmit. + * @retval kThreadError_InvalidState The radio was not in the Receive state. */ ThreadError otPlatRadioTransmit(otInstance *aInstance, RadioPacket *aPacket); @@ -396,9 +395,9 @@ ThreadError otPlatRadioTransmit(otInstance *aInstance, RadioPacket *aPacket); * @param[in] aInstance The OpenThread instance structure. * @param[in] aPacket A pointer to the packet that was transmitted. * @param[in] aFramePending TRUE if an ACK frame was received and the Frame Pending bit was set. - * @param[in] aError ::kThreadError_None when the frame was transmitted, ::kThreadError_NoAck when the frame was - * transmitted but no ACK was received, ::kThreadError_ChannelAccessFailure when the transmission - * could not take place due to activity on the channel, ::kThreadError_Abort when transmission was + * @param[in] aError kThreadError_None when the frame was transmitted, kThreadError_NoAck when the frame was + * transmitted but no ACK was received, kThreadError_ChannelAccessFailure when the transmission + * could not take place due to activity on the channel, kThreadError_Abort when transmission was * aborted for other reasons. * */ @@ -456,9 +455,9 @@ void otPlatRadioSetPromiscuous(otInstance *aInstance, bool aEnable); * @param[in] aInstance The OpenThread instance structure. * @param[in] aPacket A pointer to the packet that was transmitted. * @param[in] aFramePending TRUE if an ACK frame was received and the Frame Pending bit was set. - * @param[in] aError ::kThreadError_None when the frame was transmitted, ::kThreadError_NoAck when the frame was - * transmitted but no ACK was received, ::kThreadError_ChannelAccessFailure when the transmission - * could not take place due to activity on the channel, ::kThreadError_Abort when transmission was + * @param[in] aError kThreadError_None when the frame was transmitted, kThreadError_NoAck when the frame was + * transmitted but no ACK was received, kThreadError_ChannelAccessFailure when the transmission + * could not take place due to activity on the channel, kThreadError_Abort when transmission was * aborted for other reasons. * */ @@ -470,8 +469,8 @@ extern void otPlatDiagRadioTransmitDone(otInstance *aInstance, RadioPacket *aPac * * @param[in] aInstance The OpenThread instance structure. * @param[in] aPacket A pointer to the received packet or NULL if the receive operation failed. - * @param[in] aError ::kThreadError_None when successfully received a frame, ::kThreadError_Abort when reception - * was aborted and a frame was not received, ::kThreadError_NoBufs when a frame could not be + * @param[in] aError kThreadError_None when successfully received a frame, kThreadError_Abort when reception + * was aborted and a frame was not received, kThreadError_NoBufs when a frame could not be * received due to lack of rx buffer space. * */ @@ -484,8 +483,8 @@ extern void otPlatDiagRadioReceiveDone(otInstance *aInstance, RadioPacket *aPack * @param[in] aScanChannel The channel to perform the energy scan on. * @param[in] aScanDuration The duration, in milliseconds, for the channel to be scanned. * - * @retval ::kThreadError_None Successfully started scanning the channel. - * @retval ::kThreadError_NotImplemented The radio doesn't support energy scanning. + * @retval kThreadError_None Successfully started scanning the channel. + * @retval kThreadError_NotImplemented The radio doesn't support energy scanning. */ ThreadError otPlatRadioEnergyScan(otInstance *aInstance, uint8_t aScanChannel, uint16_t aScanDuration); diff --git a/include/openthread/platform/random.h b/include/openthread/platform/random.h index c0c91576e..c8c804ba1 100644 --- a/include/openthread/platform/random.h +++ b/include/openthread/platform/random.h @@ -44,8 +44,7 @@ extern "C" { #endif /** - * @defgroup random Random - * @ingroup platform + * @addtogroup plat-random * * @brief * This module includes the platform abstraction for random number generation. diff --git a/include/openthread/platform/settings.h b/include/openthread/platform/settings.h index 306956eb0..6cdf36828 100644 --- a/include/openthread/platform/settings.h +++ b/include/openthread/platform/settings.h @@ -29,7 +29,7 @@ /** * @file * @brief - * This file includes platform abstractions for non-volatile storage of settings. + * This file includes platform abstraction for non-volatile storage of settings. */ #ifndef OT_PLATFORM_SETTINGS_H @@ -41,6 +41,16 @@ extern "C" { #endif +/** + * @addtogroup plat-settings + * + * @brief + * This module includes the platform abstraction for non-volatile storage of settings. + * + * @{ + * + */ + /** * Performs any initialization for the settings subsystem, if necessary. * @@ -147,7 +157,7 @@ ThreadError otPlatSettingsAbandonChange(otInstance *aInstance); * A pointer to where the value of the setting * should be written. May be set to NULL if just * testing for the presence or length of a setting. - * @param[in/out] aValueLength + * @param[inout] aValueLength * A pointer to the length of the value. When * called, this pointer should point to an * integer containing the maximum value size that @@ -215,7 +225,7 @@ ThreadError otPlatSettingsSet(otInstance *aInstance, uint16_t aKey, const uint8_ * A pointer to where the new value of the setting * should be read from. MUST NOT be NULL if aValueLength * is non-zero. - * @param[in/out] aValueLength + * @param[inout] aValueLength * The length of the data pointed to by aValue. * May be zero. * @@ -260,6 +270,11 @@ ThreadError otPlatSettingsDelete(otInstance *aInstance, uint16_t aKey, int aInde */ void otPlatSettingsWipe(otInstance *aInstance); +/** + * @} + * + */ + #ifdef __cplusplus } // extern "C" #endif diff --git a/include/openthread/platform/spi-slave.h b/include/openthread/platform/spi-slave.h index 014599130..ff89a8b37 100644 --- a/include/openthread/platform/spi-slave.h +++ b/include/openthread/platform/spi-slave.h @@ -44,8 +44,7 @@ extern "C" { #endif /** - * @defgroup spi-slave SPI Slave - * @ingroup platform + * @addtogroup plat-spi-slave * * @brief * This module includes the platform abstraction for SPI slave communication. diff --git a/include/openthread/platform/toolchain.h b/include/openthread/platform/toolchain.h index b0deace1b..3476a0d34 100644 --- a/include/openthread/platform/toolchain.h +++ b/include/openthread/platform/toolchain.h @@ -27,8 +27,7 @@ */ /** - * @defgroup toolchain Toolchain - * @ingroup platform + * @addtogroup plat-toolchain * * @brief * This module defines a toolchain abstraction layer through macros. @@ -85,6 +84,13 @@ extern "C" { * */ +/** + * @def OT_TOOL_ALIGN + * + * Compiler-specific alignment modifier. + * + */ + // =========== TOOLCHAIN SELECTION : START =========== #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM) || defined(__TI_ARM__) @@ -144,6 +150,20 @@ extern "C" { // =========== TOOLCHAIN SELECTION : END =========== +/** + * @def OTAPI + * + * Compiler-specific modifier for public API declarations. + * + */ + +/** + * @def OTCALL + * + * Compiler-specific modifier to export functions in a DLL. + * + */ + #ifdef _MSC_VER #ifdef _WIN64 diff --git a/include/openthread/platform/uart.h b/include/openthread/platform/uart.h index 566a2c9ad..465efb887 100644 --- a/include/openthread/platform/uart.h +++ b/include/openthread/platform/uart.h @@ -44,8 +44,7 @@ extern "C" { #endif /** - * @defgroup uart UART - * @ingroup platform + * @addtogroup plat-uart * * @brief * This module includes the platform abstraction for UART communication. @@ -57,16 +56,18 @@ extern "C" { /** * Enable the UART. * - * @retval ::kThreadError_None Successfully enabled the UART. - * @retval ::kThreadError_Failed Failed to enabled the UART. + * @retval kThreadError_None Successfully enabled the UART. + * @retval kThreadError_Failed Failed to enabled the UART. + * */ ThreadError otPlatUartEnable(void); /** * Disable the UART. * - * @retval ::kThreadError_None Successfully disabled the UART. - * @retval ::kThreadError_Failed Failed to disable the UART. + * @retval kThreadError_None Successfully disabled the UART. + * @retval kThreadError_Failed Failed to disable the UART. + * */ ThreadError otPlatUartDisable(void); @@ -76,8 +77,9 @@ ThreadError otPlatUartDisable(void); * @param[in] aBuf A pointer to the data buffer. * @param[in] aBufLength Number of bytes to transmit. * - * @retval ::kThreadError_None Successfully started transmission. - * @retval ::kThreadError_Failed Failed to start the transmission. + * @retval kThreadError_None Successfully started transmission. + * @retval kThreadError_Failed Failed to start the transmission. + * */ ThreadError otPlatUartSend(const uint8_t *aBuf, uint16_t aBufLength); diff --git a/include/openthread/platform/usec-alarm.h b/include/openthread/platform/usec-alarm.h index f367e461e..b1f263c6c 100644 --- a/include/openthread/platform/usec-alarm.h +++ b/include/openthread/platform/usec-alarm.h @@ -44,22 +44,28 @@ extern "C" { #endif /** - * @defgroup usec-alarm Microsecond alarm - * @ingroup alarm - * - * @brief - * This module includes the platform abstraction for the microsecond alarm service. + * @addtogroup plat-alarm * * @{ * */ +/** + * This structure represents time in microseconds. + * + */ typedef struct { uint32_t mMs; ///< Time in milliseconds. uint16_t mUs; ///< Time fraction in microseconds. } otPlatUsecAlarmTime; +/** + * This defines the callback for indicating when the alarm has expired. + * + * @param[in] aContext A pointer to arbitrary context information. + * + */ typedef void (*otPlatUsecAlarmHandler)(void *aContext); /** @@ -70,6 +76,7 @@ typedef void (*otPlatUsecAlarmHandler)(void *aContext); * @param[in] aDt The time delay in milliseconds and microseconds from @p aT0. * @param[in] aHandler A pointer to a function that is called when the timer expires. * @param[in] aContext A pointer to arbitrary context information. + * */ void otPlatUsecAlarmStartAt(otInstance *aInstance, const otPlatUsecAlarmTime *aT0, @@ -81,6 +88,7 @@ void otPlatUsecAlarmStartAt(otInstance *aInstance, * Stop the alarm. * * @param[in] aInstance The OpenThread instance structure. + * */ void otPlatUsecAlarmStop(otInstance *aInstance); @@ -88,6 +96,7 @@ void otPlatUsecAlarmStop(otInstance *aInstance); * Get the current time. * * @param[out] aNow The current time in milliseconds and microseconds. + * */ void otPlatUsecAlarmGetNow(otPlatUsecAlarmTime *aNow); diff --git a/include/openthread/tasklet.h b/include/openthread/tasklet.h index f074e2c8d..3d915f1ed 100644 --- a/include/openthread/tasklet.h +++ b/include/openthread/tasklet.h @@ -42,7 +42,7 @@ extern "C" { #endif /** - * @addtogroup execution Execution + * @addtogroup api-tasklets * * @brief * This module includes functions that control the Thread stack's execution. diff --git a/include/openthread/thread.h b/include/openthread/thread.h index e5af9a589..c2ba92729 100644 --- a/include/openthread/thread.h +++ b/include/openthread/thread.h @@ -44,20 +44,7 @@ extern "C" { #endif /** - * @addtogroup thread Thread - * - * @brief - * This module includes functions that control Thread-specific functions. - * - * @{ - * - */ - -/** - * @addtogroup config Configuration - * - * @brief - * This module includes functions for configuration. + * @addtogroup api-thread-general * * @{ * @@ -112,18 +99,20 @@ OTAPI bool OTCALL otThreadIsSingleton(otInstance *aInstance); /** * This function starts a Thread Discovery scan. * - * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aScanChannels A bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK). - * @param[in] aPanId The PAN ID filter (set to Broadcast PAN to disable filter). - * @param[in] aJoiner Value of the Joiner Flag in the Discovery Request TLV. - * @param[in] aCallback A pointer to a function called on receiving an MLE Discovery Response or scan completes. - * @param[in] aCallbackContext A pointer to application-specific context. + * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aScanChannels A bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK). + * @param[in] aPanId The PAN ID filter (set to Broadcast PAN to disable filter). + * @param[in] aJoiner Value of the Joiner Flag in the Discovery Request TLV. + * @param[in] aEnableEui64Filtering TRUE to filter responses on EUI-64, FALSE otherwise. + * @param[in] aCallback A pointer to a function called on receiving an MLE Discovery Response or + * scan completes. + * @param[in] aCallbackContext A pointer to application-specific context. * * @retval kThreadError_None Accepted the Thread Discovery request. * @retval kThreadError_Busy Already performing an Thread Discovery. * */ -OTAPI ThreadError OTCALL otThreadDiscover(otInstance *aInstance, uint32_t aScanChannels, uint16_t aPanid, bool aJoiner, +OTAPI ThreadError OTCALL otThreadDiscover(otInstance *aInstance, uint32_t aScanChannels, uint16_t aPanId, bool aJoiner, bool aEnableEui64Filtering, otHandleActiveScanResult aCallback, void *aCallbackContext); /** @@ -134,16 +123,6 @@ OTAPI ThreadError OTCALL otThreadDiscover(otInstance *aInstance, uint32_t aScanC */ OTAPI bool OTCALL otThreadIsDiscoverInProgress(otInstance *aInstance); -/** - * @defgroup config-general General - * - * @brief - * This module includes functions that manage configuration parameters for the Thread Child, Router, and Leader roles. - * - * @{ - * - */ - /** * Get the Thread Child Timeout used when operating in the Child role. * @@ -159,8 +138,10 @@ OTAPI uint32_t OTCALL otThreadGetChildTimeout(otInstance *aInstance); * Set the Thread Child Timeout used when operating in the Child role. * * @param[in] aInstance A pointer to an OpenThread instance. + * @param[in] aTimeout The timeout value. * * @sa otThreadSetChildTimeout + * */ OTAPI void OTCALL otThreadSetChildTimeout(otInstance *aInstance, uint32_t aTimeout); @@ -349,24 +330,6 @@ OTAPI const char *OTCALL otThreadGetNetworkName(otInstance *aInstance); */ OTAPI ThreadError OTCALL otThreadSetNetworkName(otInstance *aInstance, const char *aNetworkName); -/** - * @} - */ - -/** - * @} - */ - -/** - * @defgroup config-test Test - * - * @brief - * This module includes functions that manage configuration parameters required for Thread Certification testing. - * - * @{ - * - */ - /** * Get the thrKeySequenceCounter. * @@ -430,26 +393,6 @@ OTAPI ThreadError OTCALL otThreadBecomeDetached(otInstance *aInstance); */ OTAPI ThreadError OTCALL otThreadBecomeChild(otInstance *aInstance, otMleAttachFilter aFilter); -/** - * @} - * - */ - -/** - * @} - * - */ - -/** - * @addtogroup diags Diagnostics - * - * @brief - * This module includes functions that expose internal state. - * - * @{ - * - */ - /** * This function gets the next neighbor information. It is used to go through the entries of * the neighbor table. @@ -586,9 +529,11 @@ void otThreadSetReceiveDiagnosticGetCallback(otInstance *aInstance, otReceiveDia /** * Send a Network Diagnostic Get request. * + * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aDestination A pointer to destination address. * @param[in] aTlvTypes An array of Network Diagnostic TLV types. * @param[in] aCount Number of types in aTlvTypes + * */ OTAPI ThreadError OTCALL otThreadSendDiagnosticGet(otInstance *aInstance, const otIp6Address *aDestination, const uint8_t aTlvTypes[], uint8_t aCount); @@ -600,6 +545,7 @@ OTAPI ThreadError OTCALL otThreadSendDiagnosticGet(otInstance *aInstance, const * @param[in] aDestination A pointer to destination address. * @param[in] aTlvTypes An array of Network Diagnostic TLV types. Currently only Type 9 is allowed. * @param[in] aCount Number of types in aTlvTypes + * */ OTAPI ThreadError OTCALL otThreadSendDiagnosticReset(otInstance *aInstance, const otIp6Address *aDestination, const uint8_t aTlvTypes[], uint8_t aCount); @@ -609,11 +555,6 @@ OTAPI ThreadError OTCALL otThreadSendDiagnosticReset(otInstance *aInstance, cons * */ -/** - * @} - * - */ - #ifdef __cplusplus } // extern "C" #endif diff --git a/include/openthread/thread_ftd.h b/include/openthread/thread_ftd.h index 4d5a1c6d3..48f7dc1d3 100644 --- a/include/openthread/thread_ftd.h +++ b/include/openthread/thread_ftd.h @@ -44,20 +44,7 @@ extern "C" { #endif /** - * @addtogroup thread Thread - * - * @brief - * This module includes functions that control Thread-specific functions. - * - * @{ - * - */ - -/** - * @defgroup config-general General - * - * @brief - * This module includes functions that manage configuration parameters for the Thread Router, and Leader roles. + * @addtogroup api-thread-router * * @{ * @@ -128,17 +115,6 @@ OTAPI void OTCALL otThreadSetRouterRoleEnabled(otInstance *aInstance, bool aEnab */ OTAPI ThreadError OTCALL otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t aRouterId); - -/** - * @defgroup config-router Router/Leader - * - * @brief - * This module includes functions that manage configuration parameters for the Thread Router and Leader roles. - * - * @{ - * - */ - /** * Get the Thread Leader Weight used when operating in the Leader role. * @@ -218,16 +194,6 @@ OTAPI ThreadError OTCALL otThreadSetJoinerUdpPort(otInstance *aInstance, uint16_ ThreadError otThreadSetSteeringData(otInstance *aInstance, otExtAddress *aExtAddress); #endif // OPENTHREAD_CONFIG_ENABLE_STEERING_DATA_SET_OOB -/** - * @defgroup config-test Test - * - * @brief - * This module includes functions that manage configuration parameters required for Thread Certification testing. - * - * @{ - * - */ - /** * Get the CONTEXT_ID_REUSE_DELAY parameter used in the Leader role. * @@ -363,16 +329,6 @@ OTAPI uint8_t OTCALL otThreadGetRouterSelectionJitter(otInstance *aInstance); */ OTAPI void OTCALL otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_t aRouterJitter); -/** - * @addtogroup diags Diagnostics - * - * @brief - * This module includes functions that expose internal state. - * - * @{ - * - */ - /** * The function retains diagnostic information for an attached Child by its Child ID or RLOC16. * @@ -380,9 +336,9 @@ OTAPI void OTCALL otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_ * @param[in] aChildId The Child ID or RLOC16 for the attached child. * @param[out] aChildInfo A pointer to where the child information is placed. * - * @retavl kThreadError_None @p aChildInfo was successfully updated with the info for the given ID. + * @retval kThreadError_None @p aChildInfo was successfully updated with the info for the given ID. * @retval kThreadError_NotFound No valid child with this Child ID. - * @retavl kThreadError_InvalidArgs If @p aChildInfo is NULL. + * @retval kThreadError_InvalidArgs If @p aChildInfo is NULL. * */ OTAPI ThreadError OTCALL otThreadGetChildInfoById(otInstance *aInstance, uint16_t aChildId, otChildInfo *aChildInfo); @@ -394,9 +350,9 @@ OTAPI ThreadError OTCALL otThreadGetChildInfoById(otInstance *aInstance, uint16_ * @param[in] aChildIndex The table index. * @param[out] aChildInfo A pointer to where the child information is placed. * - * @retavl kThreadError_None @p aChildInfo was successfully updated with the info for the given index. + * @retval kThreadError_None @p aChildInfo was successfully updated with the info for the given index. * @retval kThreadError_NotFound No valid child at this index. - * @retavl kThreadError_InvalidArgs Either @p aChildInfo is NULL, or @p aChildIndex is out of range (higher + * @retval kThreadError_InvalidArgs Either @p aChildInfo is NULL, or @p aChildIndex is out of range (higher * than max table index). * * @sa otGetMaxAllowedChildren diff --git a/include/openthread/types.h b/include/openthread/types.h index 5d373d2aa..e96fcb461 100644 --- a/include/openthread/types.h +++ b/include/openthread/types.h @@ -220,15 +220,21 @@ typedef enum ThreadError #define OT_NETWORK_DIAGNOSTIC_TYPELIST_MAX_ENTRIES 18 ///< Maximum Number of Other Network Diagnostic TLV Types /** + * @struct otMasterKey + * * This structure represents a Thread Master Key. * */ OT_TOOL_PACKED_BEGIN struct otMasterKey { - uint8_t m8[OT_MASTER_KEY_SIZE]; + uint8_t m8[OT_MASTER_KEY_SIZE]; ///< Byte values } OT_TOOL_PACKED_END; +/** + * This type represents a Thread Master Key. + * + */ typedef struct otMasterKey otMasterKey; #define OT_NETWORK_NAME_MAX_SIZE 16 ///< Maximum size of the Thread Network Name field (bytes) @@ -239,7 +245,7 @@ typedef struct otMasterKey otMasterKey; */ typedef struct otNetworkName { - char m8[OT_NETWORK_NAME_MAX_SIZE + 1]; + char m8[OT_NETWORK_NAME_MAX_SIZE + 1]; ///< Byte values } otNetworkName; #define OT_EXT_PAN_ID_SIZE 8 ///< Size of a Thread PAN ID (bytes) @@ -250,7 +256,7 @@ typedef struct otNetworkName */ typedef struct otExtendedPanId { - uint8_t m8[OT_EXT_PAN_ID_SIZE]; + uint8_t m8[OT_EXT_PAN_ID_SIZE]; ///< Byte values } otExtendedPanId; #define OT_MESH_LOCAL_PREFIX_SIZE 8 ///< Size of the Mesh Local Prefix (bytes) @@ -261,7 +267,7 @@ typedef struct otExtendedPanId */ typedef struct otMeshLocalPrefix { - uint8_t m8[OT_MESH_LOCAL_PREFIX_SIZE]; + uint8_t m8[OT_MESH_LOCAL_PREFIX_SIZE]; ///< Byte values } otMeshLocalPrefix; #define OT_PSKC_MAX_SIZE 16 ///< Maximum size of the PSKc (bytes) @@ -275,7 +281,7 @@ typedef struct otMeshLocalPrefix */ typedef struct otPSKc { - uint8_t m8[OT_PSKC_MAX_SIZE]; + uint8_t m8[OT_PSKC_MAX_SIZE]; ///< Byte values } otPSKc; /** @@ -284,8 +290,8 @@ typedef struct otPSKc */ typedef struct otSecurityPolicy { - uint16_t mRotationTime; - uint8_t mFlags; + uint16_t mRotationTime; ///< The value for thrKeyRotation in units of hours + uint8_t mFlags; ///< Flags as defined in Thread 1.1 Section 8.10.1.15 } otSecurityPolicy; /** @@ -346,7 +352,10 @@ typedef struct otExtAddress #define OT_IP6_ADDRESS_SIZE 16 ///< Size of an IPv6 address (bytes) /** + * @struct otIp6Address + * * This structure represents an IPv6 address. + * */ OT_TOOL_PACKED_BEGIN struct otIp6Address @@ -359,6 +368,10 @@ struct otIp6Address } mFields; ///< IPv6 accessor fields } OT_TOOL_PACKED_END; +/** + * This type represents an IPv6 address. + * + */ typedef struct otIp6Address otIp6Address; @@ -384,12 +397,6 @@ typedef struct otMessage struct otMessage *mNext; ///< A pointer to the next Message buffer. } otMessage; -/** - * @addtogroup commands Commands - * - * @{ - * - */ #define OT_PANID_BROADCAST 0xffff ///< IEEE 802.15.4 Broadcast PAN ID @@ -420,8 +427,8 @@ typedef struct otMessage */ typedef struct otSteeringData { - uint8_t mLength; - uint8_t m8[OT_STEERING_DATA_MAX_LENGTH]; + uint8_t mLength; ///< Length of steering data (bytes) + uint8_t m8[OT_STEERING_DATA_MAX_LENGTH]; ///< Byte values } otSteeringData; /** @@ -454,31 +461,6 @@ typedef struct otEnergyScanResult int8_t mMaxRssi; ///< The max RSSI (dBm) } otEnergyScanResult; -/** - * @} - * - */ - -/** - * @addtogroup config Configuration - * - * @brief - * This module includes functions for configuration. - * - * @{ - * - */ - -/** - * @defgroup config-general General - * - * @brief - * This module includes functions that manage configuration parameters for the Thread Child, Router, and Leader roles. - * - * @{ - * - */ - /** * This structure represents an Active or Pending Operational Dataset. * @@ -624,20 +606,6 @@ enum OT_IP6_RLOC_REMOVED = 1 << 12, ///< RLOC was removed }; -/** - * @} - */ - -/** - * @defgroup config-br Border Router - * - * @brief - * This module includes functions that manage configuration parameters that apply to the Thread Border Router role. - * - * @{ - * - */ - /** * This structure represents an IPv6 prefix. */ @@ -738,21 +706,6 @@ typedef enum otRoutePreference kRoutePreferenceHigh = 1 ///< The most preferred route. Routes assigned this value should be selected over any other route. } otRoutePreference; -/** - * @} - * - */ - -/** - * @defgroup config-test Test - * - * @brief - * This module includes functions that manage configuration parameters required for Thread Certification testing. - * - * @{ - * - */ - /** * Represents any restrictions on the attach process. */ @@ -786,26 +739,6 @@ typedef struct otMacBlacklistEntry bool mValid; ///< Indicates whether or not the blacklist entry is valid } otMacBlacklistEntry; -/** - * @} - * - */ - -/** - * @} - * - */ - -/** - * @addtogroup diags Diagnostics - * - * @brief - * This module includes functions that expose internal state. - * - * @{ - * - */ - /** * Represents a Thread device role. */ @@ -971,11 +904,6 @@ typedef struct otBufferInfo uint16_t mCoapServerBuffers; ///< The number of buffers in the CoAP server responses queue. } otBufferInfo; -/** - * @} - * - */ - /** * This structure represents an IPv6 network interface unicast address. * @@ -1028,20 +956,10 @@ typedef struct uint16_t mSecretKeyLength; ///< Secret key length in bytes. Should be at least 16 bytes == 128 bits. } otSemanticallyOpaqueIidGeneratorData; -/** - * @addtogroup icmp6 ICMPv6 - * - * @brief - * This module includes functions that control ICMPv6 communication. - * - * @{ - * - */ - /** * ICMPv6 Message Types * -*/ + */ typedef enum otIcmp6Type { kIcmp6TypeDstUnreach = 1, ///< Destination Unreachable @@ -1061,6 +979,8 @@ typedef enum otIcmp6Code #define OT_ICMP6_HEADER_DATA_SIZE 4 ///< Size of an message specific data of ICMPv6 Header. /** + * @struct otIcmp6Header + * * This structure represents an ICMPv6 header. * */ @@ -1078,6 +998,10 @@ struct otIcmp6Header } mData; ///< Message-specific data } OT_TOOL_PACKED_END; +/** + * This type represents an ICMPv6 header. + * + */ typedef struct otIcmp6Header otIcmp6Header; /** @@ -1098,26 +1022,11 @@ typedef void (*otIcmp6ReceiveCallback)(void *aContext, otMessage *aMessage, cons */ typedef struct otIcmp6Handler { - otIcmp6ReceiveCallback mReceiveCallback; - void *mContext; - struct otIcmp6Handler *mNext; + otIcmp6ReceiveCallback mReceiveCallback; ///< The ICMPv6 received callback + void *mContext; ///< A pointer to arbitrary context information. + struct otIcmp6Handler *mNext; ///< A pointer to the next handler in the list. } otIcmp6Handler; -/** - * @} - * - */ - -/** - * @addtogroup udp UDP - * - * @brief - * This module includes functions that control UDP communication. - * - * @{ - * - */ - /** * This structure represents an IPv6 socket address. */ @@ -1142,11 +1051,6 @@ typedef void (OTCALL *otDeviceAvailabilityChangedCallback)(bool aAdded, const GU #endif // OTDLL -/** - * @} - * - */ - #ifdef __cplusplus } // extern "C" #endif diff --git a/include/openthread/udp.h b/include/openthread/udp.h index 491e6cf69..80ff86b4a 100644 --- a/include/openthread/udp.h +++ b/include/openthread/udp.h @@ -43,7 +43,7 @@ extern "C" { #endif /** - * @addtogroup udp UDP + * @addtogroup api-udp * * @brief * This module includes functions that control UDP communication.