From 06197eb7f53f138638add68044162a3085e034c2 Mon Sep 17 00:00:00 2001 From: Jonathan Hui Date: Thu, 16 May 2019 08:28:51 -0700 Subject: [PATCH] [docs] fixup see-also in doxygen (#3824) --- include/openthread/channel_manager.h | 6 +++--- include/openthread/instance.h | 3 --- include/openthread/ip6.h | 4 ++-- include/openthread/link.h | 1 + include/openthread/platform/debug_uart.h | 2 +- include/openthread/thread.h | 9 ++++++++- include/openthread/thread_ftd.h | 9 ++++++++- 7 files changed, 23 insertions(+), 11 deletions(-) diff --git a/include/openthread/channel_manager.h b/include/openthread/channel_manager.h index 249662246..09c8e03b9 100644 --- a/include/openthread/channel_manager.h +++ b/include/openthread/channel_manager.h @@ -57,8 +57,8 @@ extern "C" { /** * This function requests a Thread network channel change. * - * The network switches to the given channel after a specified delay (@sa otChannelManagerSetDelay). The channel change - * is performed by updating the Pending Operational Dataset. + * The network switches to the given channel after a specified delay (see otChannelManagerSetDelay()). The channel + * change is performed by updating the Pending Operational Dataset. * * A subsequent call to this function will cancel an ongoing previously requested channel change. * @@ -117,7 +117,7 @@ otError otChannelManagerSetDelay(otInstance *aInstance, uint16_t aDelay); * * 2) If the first step passes, then `ChannelManager` selects a potentially better channel. It uses the collected * channel quality data by `ChannelMonitor` module. The supported and favored channels are used at this step. - * (@sa otChannelManagerSetSupportedChannels, @sa otChannelManagerSetFavoredChannels). + * (see otChannelManagerSetSupportedChannels() and otChannelManagerSetFavoredChannels()). * * 3) If the newly selected channel is different from the current channel, `ChannelManager` requests/starts the * channel change process (internally invoking a `RequestChannelChange()`). diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 5f73e6b0d..293170e59 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -146,7 +146,6 @@ OTAPI void OTCALL otSetDeviceAvailabilityChangedCallback(otApiInstance * * * @param[in] aApiInstance The OpenThread api instance. * - * @sa otFreeMemory */ OTAPI otDeviceList *OTCALL otEnumerateDevices(otApiInstance *aApiInstance); @@ -158,8 +157,6 @@ OTAPI otDeviceList *OTCALL otEnumerateDevices(otApiInstance *aApiInstance); * * @returns The new OpenThread device instance structure for the device. * - * @sa otFreeMemory - * */ OTAPI otInstance *OTCALL otInstanceInit(otApiInstance *aApiInstance, const GUID *aDeviceGuid); diff --git a/include/openthread/ip6.h b/include/openthread/ip6.h index ea348961b..9e89c5f22 100644 --- a/include/openthread/ip6.h +++ b/include/openthread/ip6.h @@ -158,7 +158,7 @@ typedef struct otMessageInfo /** * A pointer to link-specific information. In case @p mInterfaceId is set to OT_NETIF_INTERFACE_ID_THREAD, - * @p mLinkInfo points to @sa otThreadLinkInfo. This field is only valid for messages received from the + * @p mLinkInfo points to otThreadLinkInfo(). This field is only valid for messages received from the * Thread radio and is ignored on transmission. */ const void *mLinkInfo; @@ -331,7 +331,7 @@ otMessage *otIp6NewMessageFromBuffer(otInstance * aInstance, * * @param[in] aMessage A pointer to the message buffer containing the received IPv6 datagram. This function transfers * the ownership of the @p aMessage to the receiver of the callback. The message should be - * freed by the receiver of the callback after it is processed (@sa otMessageFree). + * freed by the receiver of the callback after it is processed (see otMessageFree()). * @param[in] aContext A pointer to application-specific context. * */ diff --git a/include/openthread/link.h b/include/openthread/link.h index 4d311b756..0f27203b3 100644 --- a/include/openthread/link.h +++ b/include/openthread/link.h @@ -299,6 +299,7 @@ OTAPI otError OTCALL otLinkOutOfBandTransmitRequest(otInstance *aInstance, otRad * @returns The IEEE 802.15.4 channel. * * @sa otLinkSetChannel + * */ OTAPI uint8_t OTCALL otLinkGetChannel(otInstance *aInstance); diff --git a/include/openthread/platform/debug_uart.h b/include/openthread/platform/debug_uart.h index 43a5a70bc..237f8da8e 100644 --- a/include/openthread/platform/debug_uart.h +++ b/include/openthread/platform/debug_uart.h @@ -126,7 +126,7 @@ int otPlatDebugUart_kbhit(void); * * This function MUST be implemented by the platform * - * @retval (negative) no data available, @sa otPlatDebugUart_kbhit() + * @retval (negative) no data available, see otPlatDebugUart_kbhit() * @retval (0x00..0x0ff) data byte value * */ diff --git a/include/openthread/thread.h b/include/openthread/thread.h index c78a8886f..251631e66 100644 --- a/include/openthread/thread.h +++ b/include/openthread/thread.h @@ -285,6 +285,7 @@ OTAPI bool OTCALL otThreadIsDiscoverInProgress(otInstance *aInstance); * @returns The Thread Child Timeout value in seconds. * * @sa otThreadSetChildTimeout + * */ OTAPI uint32_t OTCALL otThreadGetChildTimeout(otInstance *aInstance); @@ -294,7 +295,7 @@ OTAPI uint32_t OTCALL otThreadGetChildTimeout(otInstance *aInstance); * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aTimeout The timeout value in seconds. * - * @sa otThreadSetChildTimeout + * @sa otThreadGetChildTimeout * */ OTAPI void OTCALL otThreadSetChildTimeout(otInstance *aInstance, uint32_t aTimeout); @@ -307,6 +308,7 @@ OTAPI void OTCALL otThreadSetChildTimeout(otInstance *aInstance, uint32_t aTimeo * @returns A pointer to the IEEE 802.15.4 Extended PAN ID. * * @sa otThreadSetExtendedPanId + * */ OTAPI const otExtendedPanId *OTCALL otThreadGetExtendedPanId(otInstance *aInstance); @@ -324,6 +326,7 @@ OTAPI const otExtendedPanId *OTCALL otThreadGetExtendedPanId(otInstance *aInstan * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. * * @sa otThreadGetExtendedPanId + * */ OTAPI otError OTCALL otThreadSetExtendedPanId(otInstance *aInstance, const otExtendedPanId *aExtendedPanId); @@ -348,6 +351,7 @@ OTAPI otError OTCALL otThreadGetLeaderRloc(otInstance *aInstance, otIp6Address * * @returns The MLE Link Mode configuration. * * @sa otThreadSetLinkMode + * */ OTAPI otLinkModeConfig OTCALL otThreadGetLinkMode(otInstance *aInstance); @@ -360,6 +364,7 @@ OTAPI otLinkModeConfig OTCALL otThreadGetLinkMode(otInstance *aInstance); * @retval OT_ERROR_NONE Successfully set the MLE Link Mode configuration. * * @sa otThreadGetLinkMode + * */ OTAPI otError OTCALL otThreadSetLinkMode(otInstance *aInstance, otLinkModeConfig aConfig); @@ -371,6 +376,7 @@ OTAPI otError OTCALL otThreadSetLinkMode(otInstance *aInstance, otLinkModeConfig * @returns A pointer to a buffer containing the thrMasterKey. * * @sa otThreadSetMasterKey + * */ OTAPI const otMasterKey *OTCALL otThreadGetMasterKey(otInstance *aInstance); @@ -389,6 +395,7 @@ OTAPI const otMasterKey *OTCALL otThreadGetMasterKey(otInstance *aInstance); * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. * * @sa otThreadGetMasterKey + * */ OTAPI otError OTCALL otThreadSetMasterKey(otInstance *aInstance, const otMasterKey *aKey); diff --git a/include/openthread/thread_ftd.h b/include/openthread/thread_ftd.h index 6fbe666e6..2095092f5 100644 --- a/include/openthread/thread_ftd.h +++ b/include/openthread/thread_ftd.h @@ -117,7 +117,7 @@ OTAPI uint8_t OTCALL otThreadGetMaxAllowedChildren(otInstance *aInstance); * @retval OT_ERROR_INVALID_ARGS If @p aMaxChildren is not in the range [1, OPENTHREAD_CONFIG_MAX_CHILDREN]. * @retval OT_ERROR_INVALID_STATE If Thread isn't stopped. * - * @sa otThreadGetMaxAllowedChildren, otThreadStop + * @sa otThreadGetMaxAllowedChildren * */ OTAPI otError OTCALL otThreadSetMaxAllowedChildren(otInstance *aInstance, uint8_t aMaxChildren); @@ -169,6 +169,7 @@ OTAPI otError OTCALL otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t * @returns The Thread Leader Weight value. * * @sa otThreadSetLeaderWeight + * */ OTAPI uint8_t OTCALL otThreadGetLocalLeaderWeight(otInstance *aInstance); @@ -179,6 +180,7 @@ OTAPI uint8_t OTCALL otThreadGetLocalLeaderWeight(otInstance *aInstance); * @param[in] aWeight The Thread Leader Weight value. * * @sa otThreadGetLeaderWeight + * */ OTAPI void OTCALL otThreadSetLocalLeaderWeight(otInstance *aInstance, uint8_t aWeight); @@ -374,6 +376,7 @@ OTAPI otError OTCALL otThreadBecomeLeader(otInstance *aInstance); * @returns The ROUTER_DOWNGRADE_THRESHOLD value. * * @sa otThreadSetRouterDowngradeThreshold + * */ OTAPI uint8_t OTCALL otThreadGetRouterDowngradeThreshold(otInstance *aInstance); @@ -387,6 +390,7 @@ OTAPI uint8_t OTCALL otThreadGetRouterDowngradeThreshold(otInstance *aInstance); * @param[in] aThreshold The ROUTER_DOWNGRADE_THRESHOLD value. * * @sa otThreadGetRouterDowngradeThreshold + * */ OTAPI void OTCALL otThreadSetRouterDowngradeThreshold(otInstance *aInstance, uint8_t aThreshold); @@ -398,6 +402,7 @@ OTAPI void OTCALL otThreadSetRouterDowngradeThreshold(otInstance *aInstance, uin * @returns The ROUTER_SELECTION_JITTER value. * * @sa otThreadSetRouterSelectionJitter + * */ OTAPI uint8_t OTCALL otThreadGetRouterSelectionJitter(otInstance *aInstance); @@ -411,6 +416,7 @@ OTAPI uint8_t OTCALL otThreadGetRouterSelectionJitter(otInstance *aInstance); * @param[in] aRouterJitter The ROUTER_SELECTION_JITTER value. * * @sa otThreadGetRouterSelectionJitter + * */ OTAPI void OTCALL otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_t aRouterJitter); @@ -569,6 +575,7 @@ OTAPI int8_t OTCALL otThreadGetParentPriority(otInstance *aInstance); * @retval OT_ERROR_INVALID_ARGS If the parent priority value is not among 1, 0, -1 and -2. * * @sa otThreadGetParentPriority + * */ OTAPI otError OTCALL otThreadSetParentPriority(otInstance *aInstance, int8_t aParentPriority);