From 3ee31ec562c82d09643c32dcb5d0c3e4e624d3a8 Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Thu, 19 Jul 2018 21:43:08 -0700 Subject: [PATCH] [commissioner] update comments and method documentations (#2900) --- include/openthread/commissioner.h | 14 +++++++----- src/core/meshcop/announce_begin_client.hpp | 4 ++-- src/core/meshcop/commissioner.hpp | 26 +++++++++++++--------- 3 files changed, 27 insertions(+), 17 deletions(-) diff --git a/include/openthread/commissioner.h b/include/openthread/commissioner.h index 1a92c3073..cc2db14b7 100644 --- a/include/openthread/commissioner.h +++ b/include/openthread/commissioner.h @@ -67,7 +67,8 @@ typedef enum otCommissionerState { * * @param[in] aInstance A pointer to an OpenThread instance. * - * @retval OT_ERROR_NONE Successfully started the Commissioner role. + * @retval OT_ERROR_NONE Successfully started the Commissioner role. + * @retval OT_ERROR_INVALID_STATE Commissioner is already started. * */ OTAPI otError OTCALL otCommissionerStart(otInstance *aInstance); @@ -77,7 +78,8 @@ OTAPI otError OTCALL otCommissionerStart(otInstance *aInstance); * * @param[in] aInstance A pointer to an OpenThread instance. * - * @retval OT_ERROR_NONE Successfully stopped the Commissioner role. + * @retval OT_ERROR_NONE Successfully stopped the Commissioner role. + * @retval OT_ERROR_INVALID_STATE Commissioner is already stopped. * */ OTAPI otError OTCALL otCommissionerStop(otInstance *aInstance); @@ -136,8 +138,8 @@ OTAPI otError OTCALL otCommissionerSetProvisioningUrl(otInstance *aInstance, con * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aChannelMask The channel mask value. - * @param[in] aCount The number of energy measurements per channel. - * @param[in] aPeriod The time between energy measurements (milliseconds). + * @param[in] aCount The number of Announcement messages per channel. + * @param[in] aPeriod The time between two successive MLE Announce transmissions (in milliseconds). * @param[in] aAddress A pointer to the IPv6 destination. * * @retval OT_ERROR_NONE Successfully enqueued the Announce Begin message. @@ -212,7 +214,7 @@ typedef void(OTCALL *otCommissionerPanIdConflictCallback)(uint16_t aPanId, uint3 * @param[in] aPanId The PAN ID to query. * @param[in] aChannelMask The channel mask value. * @param[in] aAddress A pointer to the IPv6 destination. - * @param[in] aCallback A pointer to a function called on receiving an Energy Report message. + * @param[in] aCallback A pointer to a function called on receiving a PAN ID Conflict message. * @param[in] aContext A pointer to application-specific context. * * @retval OT_ERROR_NONE Successfully enqueued the PAN ID Query message. @@ -238,6 +240,7 @@ OTAPI otError OTCALL otCommissionerPanIdQuery(otInstance * * * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. + * @retval OT_ERROR_INVALID_STATE The commissioner is not active. * */ OTAPI otError OTCALL otCommissionerSendMgmtGet(otInstance *aInstance, const uint8_t *aTlvs, uint8_t aLength); @@ -252,6 +255,7 @@ OTAPI otError OTCALL otCommissionerSendMgmtGet(otInstance *aInstance, const uint * * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. + * @retval OT_ERROR_INVALID_STATE The commissioner is not active. * */ OTAPI otError OTCALL otCommissionerSendMgmtSet(otInstance * aInstance, diff --git a/src/core/meshcop/announce_begin_client.hpp b/src/core/meshcop/announce_begin_client.hpp index 4662c91fe..392df1764 100644 --- a/src/core/meshcop/announce_begin_client.hpp +++ b/src/core/meshcop/announce_begin_client.hpp @@ -60,8 +60,8 @@ public: * This method sends a Announce Begin message. * * @param[in] aChannelMask The channel mask value. - * @param[in] aCount The number of energy measurements per channel. - * @param[in] aPeriod The time between energy measurements (milliseconds). + * @param[in] aCount The number of Announce messages sent per channel. + * @param[in] aPeriod The time between two successive MLE Announce transmissions (in milliseconds). * * @retval OT_ERROR_NONE Successfully enqueued the Announce Begin message. * @retval OT_ERROR_NO_BUFS Insufficient buffers to generate a Announce Begin message. diff --git a/src/core/meshcop/commissioner.hpp b/src/core/meshcop/commissioner.hpp index 5a2f34615..effef0480 100644 --- a/src/core/meshcop/commissioner.hpp +++ b/src/core/meshcop/commissioner.hpp @@ -68,7 +68,8 @@ public: /** * This method starts the Commissioner service. * - * @retval OT_ERROR_NONE Successfully started the Commissioner service. + * @retval OT_ERROR_NONE Successfully started the Commissioner service. + * @retval OT_ERROR_INVALID_STATE Commissioner is already started. * */ otError Start(void); @@ -76,7 +77,8 @@ public: /** * This method stops the Commissioner service. * - * @retval OT_ERROR_NONE Successfully stopped the Commissioner service. + * @retval OT_ERROR_NONE Successfully stopped the Commissioner service. + * @retval OT_ERROR_INVALID_STATE Commissioner is already stopped. * */ otError Stop(void); @@ -94,8 +96,9 @@ public: * @param[in] aPSKd A pointer to the PSKd. * @param[in] aTimeout A time after which a Joiner is automatically removed, in seconds. * - * @retval OT_ERROR_NONE Successfully added the Joiner. - * @retval OT_ERROR_NO_BUFS No buffers available to add the Joiner. + * @retval OT_ERROR_NONE Successfully added the Joiner. + * @retval OT_ERROR_NO_BUFS No buffers available to add the Joiner. + * @retval OT_ERROR_INVALID_STATE Commissioner service is not started. * */ otError AddJoiner(const Mac::ExtAddress *aEui64, const char *aPSKd, uint32_t aTimeout); @@ -106,8 +109,9 @@ public: * @param[in] aEui64 A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner. * @param[in] aDelay The delay to remove Joiner (in seconds). * - * @retval OT_ERROR_NONE Successfully added the Joiner. - * @retval OT_ERROR_NOT_FOUND The Joiner specified by @p aEui64 was not found. + * @retval OT_ERROR_NONE Successfully added the Joiner. + * @retval OT_ERROR_NOT_FOUND The Joiner specified by @p aEui64 was not found. + * @retval OT_ERROR_INVALID_STATE Commissioner service is not started. * */ otError RemoveJoiner(const Mac::ExtAddress *aEui64, uint32_t aDelay); @@ -157,8 +161,9 @@ public: * @param[in] aTlvs A pointer to Commissioning Data TLVs. * @param[in] aLength The length of requested TLVs in bytes. * - * @retval OT_ERROR_NONE Send MGMT_COMMISSIONER_GET successfully. - * @retval OT_ERROR_FAILED Send MGMT_COMMISSIONER_GET fail. + * @retval OT_ERROR_NONE Send MGMT_COMMISSIONER_GET successfully. + * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. + * @retval OT_ERROR_INVALID_STATE Commissioner service is not started. * */ otError SendMgmtCommissionerGetRequest(const uint8_t *aTlvs, uint8_t aLength); @@ -170,8 +175,9 @@ public: * @param[in] aTlvs A pointer to user specific Commissioning Data TLVs. * @param[in] aLength The length of user specific TLVs in bytes. * - * @retval OT_ERROR_NONE Send MGMT_COMMISSIONER_SET successfully. - * @retval OT_ERROR_FAILED Send MGMT_COMMISSIONER_SET fail. + * @retval OT_ERROR_NONE Send MGMT_COMMISSIONER_SET successfully. + * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. + * @retval OT_ERROR_INVALID_STATE Commissioner service is not started. * */ otError SendMgmtCommissionerSetRequest(const otCommissioningDataset &aDataset,