From 4e52d85dff7a9a7c4f0a7c45004c119bf95b19aa Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Tue, 3 Oct 2023 19:58:59 -0700 Subject: [PATCH] [docs] fix typos in Doxygen documentation (#9485) This commit fixes typos in Doxygen documentation, ensuring that `@param` variable names match the function/method declaration. It also adds any missing `@param` tags and removes extra ones. --- include/openthread/crypto.h | 2 -- include/openthread/instance.h | 2 +- include/openthread/joiner.h | 7 +------ include/openthread/nat64.h | 4 ++-- include/openthread/netdata_publisher.h | 2 +- include/openthread/thread_ftd.h | 2 +- src/core/border_router/routing_manager.hpp | 4 ++-- src/core/coap/coap.hpp | 2 +- src/core/mac/mac_frame.hpp | 2 +- src/core/meshcop/dataset.hpp | 4 ++-- src/core/thread/network_diagnostic_tlvs.hpp | 2 +- src/core/thread/router_table.hpp | 2 +- src/core/utils/mesh_diag.hpp | 4 ++-- 13 files changed, 16 insertions(+), 23 deletions(-) diff --git a/include/openthread/crypto.h b/include/openthread/crypto.h index 112d3bd35..414b4bae5 100644 --- a/include/openthread/crypto.h +++ b/include/openthread/crypto.h @@ -56,8 +56,6 @@ extern "C" { */ /** - * @struct otCryptoSha256Hash - * * Represents a SHA-256 hash. * */ diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 04c48db05..1dece9bd9 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -53,7 +53,7 @@ extern "C" { * @note This number versions both OpenThread platform and user APIs. * */ -#define OPENTHREAD_API_VERSION (361) +#define OPENTHREAD_API_VERSION (362) /** * @addtogroup api-instance diff --git a/include/openthread/joiner.h b/include/openthread/joiner.h index dc4b09c82..7b8968455 100644 --- a/include/openthread/joiner.h +++ b/include/openthread/joiner.h @@ -135,12 +135,7 @@ void otJoinerStop(otInstance *aInstance); * * @param[in] aInstance A pointer to an OpenThread instance. * - * @retval OT_JOINER_STATE_IDLE - * @retval OT_JOINER_STATE_DISCOVER - * @retval OT_JOINER_STATE_CONNECT - * @retval OT_JOINER_STATE_CONNECTED - * @retval OT_JOINER_STATE_ENTRUST - * @retval OT_JOINER_STATE_JOINED + * @returns The joiner state. * */ otJoinerState otJoinerGetState(otInstance *aInstance); diff --git a/include/openthread/nat64.h b/include/openthread/nat64.h index 1e69da6e8..930c4c342 100644 --- a/include/openthread/nat64.h +++ b/include/openthread/nat64.h @@ -291,7 +291,7 @@ otNat64State otNat64GetPrefixManagerState(otInstance *aInstance); * @sa otNat64GetPrefixManagerState * */ -void otNat64SetEnabled(otInstance *aInstance, bool aEnable); +void otNat64SetEnabled(otInstance *aInstance, bool aEnabled); /** * Allocate a new message buffer for sending an IPv4 message to the NAT64 translator. @@ -374,7 +374,7 @@ typedef void (*otNat64ReceiveIp4Callback)(otMessage *aMessage, void *aContext); * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aCallback A pointer to a function that is called when an IPv4 datagram is received or * NULL to disable the callback. - * @param[in] aCallbackContext A pointer to application-specific context. + * @param[in] aContext A pointer to application-specific context. * */ void otNat64SetReceiveIp4Callback(otInstance *aInstance, otNat64ReceiveIp4Callback aCallback, void *aContext); diff --git a/include/openthread/netdata_publisher.h b/include/openthread/netdata_publisher.h index 60df1f658..21a934523 100644 --- a/include/openthread/netdata_publisher.h +++ b/include/openthread/netdata_publisher.h @@ -258,9 +258,9 @@ otError otNetDataPublishExternalRoute(otInstance *aInstance, const otExternalRou * Data (monitoring the Network Data to determine when/if to add the prefix, depending on the number of similar * prefixes present in the Network Data). * + * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aPrefix The previously published external route prefix to replace. * @param[in] aConfig The external route config to publish. - * @param[in] aRequester The requester (`kFromUser` or `kFromRoutingManager` module). * * @retval OT_ERROR_NONE The external route is published successfully. * @retval OT_ERROR_INVALID_ARGS The @p aConfig is not valid (bad prefix, invalid flag combinations, or not stable). diff --git a/include/openthread/thread_ftd.h b/include/openthread/thread_ftd.h index 906f6c4e2..0928acc88 100644 --- a/include/openthread/thread_ftd.h +++ b/include/openthread/thread_ftd.h @@ -913,7 +913,7 @@ bool otThreadIsRouterIdAllocated(otInstance *aInstance, uint8_t aRouterId); * to get the value. * * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aDesRloct16 The RLOC16 of destination. + * @param[in] aDestRloc16 The RLOC16 of destination. * @param[out] aNextHopRloc16 A pointer to return RLOC16 of next hop, 0xfffe if no next hop. * @param[out] aPathCost A pointer to return path cost towards destination. * diff --git a/src/core/border_router/routing_manager.hpp b/src/core/border_router/routing_manager.hpp index bfcbfa362..c78862931 100644 --- a/src/core/border_router/routing_manager.hpp +++ b/src/core/border_router/routing_manager.hpp @@ -375,8 +375,8 @@ public: * * The favored NAT64 prefix can be discovered from infrastructure link or can be the local NAT64 prefix. * - * @param[out] aPrefix A reference to output the favored prefix. - * @param[out] aPreference A reference to output the preference associated with the favored prefix. + * @param[out] aPrefix A reference to output the favored prefix. + * @param[out] aRoutePreference A reference to output the preference associated with the favored prefix. * * @retval kErrorInvalidState The Border Routing Manager is not initialized yet. * @retval kErrorNone Successfully retrieved the NAT64 prefix. diff --git a/src/core/coap/coap.hpp b/src/core/coap/coap.hpp index 30a98ec47..9a08916a1 100644 --- a/src/core/coap/coap.hpp +++ b/src/core/coap/coap.hpp @@ -848,7 +848,7 @@ protected: /** * Sets the resource handler function. * - * @param[in] aResourceHandler The resource handler function pointer. + * @param[in] aHandler The resource handler function pointer. * */ void SetResourceHandler(ResourceHandler aHandler) { mResourceHandler = aHandler; } diff --git a/src/core/mac/mac_frame.hpp b/src/core/mac/mac_frame.hpp index 38bc67f80..267e2f735 100644 --- a/src/core/mac/mac_frame.hpp +++ b/src/core/mac/mac_frame.hpp @@ -387,7 +387,7 @@ public: * ACK. The Frame Pending and IE Present bits are not set. * * @param[in] aType Frame type. - * @param[in] aVerion Frame version. + * @param[in] aVersion Frame version. * @param[in] aAddrs Frame source and destination addresses (each can be none, short, or extended). * @param[in] aPanIds Source and destination PAN IDs. * @param[in] aSecurityLevel Frame security level. diff --git a/src/core/meshcop/dataset.hpp b/src/core/meshcop/dataset.hpp index ac7b9acdb..50ecb2c62 100644 --- a/src/core/meshcop/dataset.hpp +++ b/src/core/meshcop/dataset.hpp @@ -200,7 +200,7 @@ public: * MUST be used when Active Timestamp component is present in the Dataset, otherwise its behavior is * undefined. * - * @returns The Active Timestamp in the Dataset. + * @param[out] aTimestamp A reference to output the Active Timestamp in the Dataset. * */ void GetActiveTimestamp(Timestamp &aTimestamp) const { aTimestamp.SetFromTimestamp(mActiveTimestamp); } @@ -231,7 +231,7 @@ public: * MUST be used when Pending Timestamp component is present in the Dataset, otherwise its behavior * is undefined. * - * @returns The Pending Timestamp in the Dataset. + * @param[out] aTimestamp A reference to output the Pending Timestamp in the Dataset. * */ void GetPendingTimestamp(Timestamp &aTimestamp) const { aTimestamp.SetFromTimestamp(mPendingTimestamp); } diff --git a/src/core/thread/network_diagnostic_tlvs.hpp b/src/core/thread/network_diagnostic_tlvs.hpp index 184aaf7b1..5bdb8df0f 100644 --- a/src/core/thread/network_diagnostic_tlvs.hpp +++ b/src/core/thread/network_diagnostic_tlvs.hpp @@ -1105,7 +1105,7 @@ public: /** * Initializes the TLV. * - * @param[in] aMleCounter The MLE counters to initialize the TLV with. + * @param[in] aMleCounters The MLE counters to initialize the TLV with. * */ void Init(const Mle::Counters &aMleCounters); diff --git a/src/core/thread/router_table.hpp b/src/core/thread/router_table.hpp index 6ad32bb28..bf11573a2 100644 --- a/src/core/thread/router_table.hpp +++ b/src/core/thread/router_table.hpp @@ -381,7 +381,7 @@ public: /** * Gets the allocated Router ID set. * - * @returns The allocated Router ID set. + * @param[out] aRouterIdSet A reference to output the allocated Router ID set. * */ void GetRouterIdSet(Mle::RouterIdSet &aRouterIdSet) const { return mRouterIdMap.GetAsRouterIdSet(aRouterIdSet); } diff --git a/src/core/utils/mesh_diag.hpp b/src/core/utils/mesh_diag.hpp index 529236ea5..ff6d3b1e8 100644 --- a/src/core/utils/mesh_diag.hpp +++ b/src/core/utils/mesh_diag.hpp @@ -93,9 +93,9 @@ public: /** * Iterates through the discovered IPv6 address of a router. * - * @param[out] aIp6Address A reference to return the next IPv6 address (if any). + * @param[out] aAddress A reference to return the next IPv6 address (if any). * - * @retval kErrorNone Successfully retrieved the next address. @p aIp6Address is updated. + * @retval kErrorNone Successfully retrieved the next address. @p aAddress is updated. * @retval kErrorNotFound No more address. Reached the end of the list. * */