[docs] CLI bbr (#7986)

include/openthread/backbone_router_ftd.h

@@ -64,7 +64,14 @@ typedef enum
 } otBackboneRouterState;
 
 /**
- * This function enables or disables Backbone functionality.
+ * Enables or disables Backbone functionality.
+ *
+ * If enabled, a Server Data Request message `SRV_DATA.ntf` is triggered for the attached
+ * device if there is no Backbone Router Service in the Thread Network Data.
+ *
+ * If disabled, `SRV_DATA.ntf` is triggered if the Backbone Router is in the Primary state.
+ *
+ * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE` is enabled.
  *
  * @param[in] aInstance A pointer to an OpenThread instance.
  * @param[in] aEnable   TRUE to enable Backbone functionality, FALSE otherwise.
@@ -78,7 +85,7 @@ typedef enum
 void otBackboneRouterSetEnabled(otInstance *aInstance, bool aEnable);
 
 /**
- * This function gets the Backbone Router state.
+ * Gets the Backbone Router #otBackboneRouterState.
  *
  * @param[in] aInstance       A pointer to an OpenThread instance.
  *
@@ -95,7 +102,9 @@ void otBackboneRouterSetEnabled(otInstance *aInstance, bool aEnable);
 otBackboneRouterState otBackboneRouterGetState(otInstance *aInstance);
 
 /**
- * This function gets the local Backbone Router configuration.
+ * Gets the local Backbone Router configuration.
+ *
+ * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE` is enabled.
  *
  * @param[in]   aInstance            A pointer to an OpenThread instance.
  * @param[out]  aConfig              A pointer where to put local Backbone Router configuration.
@@ -110,7 +119,12 @@ otBackboneRouterState otBackboneRouterGetState(otInstance *aInstance);
 void otBackboneRouterGetConfig(otInstance *aInstance, otBackboneRouterConfig *aConfig);
 
 /**
- * This function sets the local Backbone Router configuration.
+ * Sets the local Backbone Router configuration #otBackboneRouterConfig.
+ *
+ * A Server Data Request message `SRV_DATA.ntf` is initiated automatically if BBR Dataset changes for Primary
+ * Backbone Router.
+ *
+ * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE` is enabled.
  *
  * @param[in]  aInstance             A pointer to an OpenThread instance.
  * @param[in]  aConfig               A pointer to the Backbone Router configuration to take effect.
@@ -127,7 +141,11 @@ void otBackboneRouterGetConfig(otInstance *aInstance, otBackboneRouterConfig *aC
 otError otBackboneRouterSetConfig(otInstance *aInstance, const otBackboneRouterConfig *aConfig);
 
 /**
- * This function explicitly registers local Backbone Router configuration.
+ * Explicitly registers local Backbone Router configuration.
+ *
+ * A Server Data Request message `SRV_DATA.ntf` is triggered for the attached device.
+ *
+ * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE` is enabled.
  *
  * @param[in]  aInstance             A pointer to an OpenThread instance.
  *
@@ -194,10 +212,11 @@ void otBackboneRouterConfigNextDuaRegistrationResponse(otInstance *
                                                        uint8_t                         aStatus);
 
 /**
- * This method configures response status for next Multicast Listener Registration.
+ * Configures the response status for the next Multicast Listener Registration.
  *
- * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled.
- *       Only used for test and certification.
+ * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE`,
+ * `OPENTHREAD_CONFIG_BACKBONE_ROUTER_MULTICAST_ROUTING_ENABLE`, and
+ * `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` are enabled.
  *
  * @param[in] aInstance  A pointer to an OpenThread instance.
  * @param[in] aStatus    The status to respond.
@@ -240,10 +259,11 @@ void otBackboneRouterSetMulticastListenerCallback(otInstance *
                                                   void *                                    aContext);
 
 /**
- * This method clears the Multicast Listeners.
+ * Clears the Multicast Listeners.
  *
- * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled.
- *       Only used for test and certification.
+ * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE`,
+ * `OPENTHREAD_CONFIG_BACKBONE_ROUTER_MULTICAST_ROUTING_ENABLE`, and
+ * `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` are enabled.
  *
  * @param[in] aInstance A pointer to an OpenThread instance.
  *
@@ -254,10 +274,13 @@ void otBackboneRouterSetMulticastListenerCallback(otInstance *
 void otBackboneRouterMulticastListenerClear(otInstance *aInstance);
 
 /**
- * This method adds a Multicast Listener.
+ * Adds a Multicast Listener with a timeout value, in seconds.
  *
- * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled.
- *       Only used for test and certification.
+ * Pass `0` to use the default MLR timeout.
+ *
+ * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE`,
+ * `OPENTHREAD_CONFIG_BACKBONE_ROUTER_MULTICAST_ROUTING_ENABLE`, and
+ * `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` are enabled.
  *
  * @param[in] aInstance  A pointer to an OpenThread instance.
  * @param[in] aAddress   The Multicast Listener address.

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (232)
+#define OPENTHREAD_API_VERSION (233)
 
 /**
  * @addtogroup api-instance
@@ -250,7 +250,7 @@ void otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback a
 void otInstanceReset(otInstance *aInstance);
 
 /**
- * This method deletes all the settings stored on non-volatile memory, and then triggers platform reset.
+ * Deletes all the settings stored on non-volatile memory, and then triggers a platform reset.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  *

include/openthread/link.h

@@ -565,7 +565,7 @@ uint32_t otLinkGetSupportedChannelMask(otInstance *aInstance);
 otError otLinkSetSupportedChannelMask(otInstance *aInstance, uint32_t aChannelMask);
 
 /**
- * Get the IEEE 802.15.4 Extended Address.
+ * Gets the IEEE 802.15.4 Extended Address.
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  *
@@ -575,9 +575,9 @@ otError otLinkSetSupportedChannelMask(otInstance *aInstance, uint32_t aChannelMa
 const otExtAddress *otLinkGetExtendedAddress(otInstance *aInstance);
 
 /**
- * This function sets the IEEE 802.15.4 Extended Address.
+ * Sets the IEEE 802.15.4 Extended Address.
  *
- * This function succeeds only when Thread protocols are disabled.
+ * @note Only succeeds when Thread protocols are disabled.
  *
  * @param[in]  aInstance    A pointer to an OpenThread instance.
  * @param[in]  aExtAddress  A pointer to the IEEE 802.15.4 Extended Address.

include/openthread/platform/radio.h

@@ -536,7 +536,7 @@ otError otPlatRadioGetCcaEnergyDetectThreshold(otInstance *aInstance, int8_t *aT
 otError otPlatRadioSetCcaEnergyDetectThreshold(otInstance *aInstance, int8_t aThreshold);
 
 /**
- * Get the external FEM's Rx LNA gain in dBm.
+ * Gets the external FEM's Rx LNA gain in dBm.
  *
  * @param[in]  aInstance  The OpenThread instance structure.
  * @param[out] aGain     The external FEM's Rx LNA gain in dBm.
@@ -549,7 +549,7 @@ otError otPlatRadioSetCcaEnergyDetectThreshold(otInstance *aInstance, int8_t aTh
 otError otPlatRadioGetFemLnaGain(otInstance *aInstance, int8_t *aGain);
 
 /**
- * Set the external FEM's Rx LNA gain in dBm.
+ * Sets the external FEM's Rx LNA gain in dBm.
  *
  * @param[in] aInstance  The OpenThread instance structure.
  * @param[in] aGain      The external FEM's Rx LNA gain in dBm.

include/openthread/thread.h

@@ -328,7 +328,7 @@ uint32_t otThreadGetChildTimeout(otInstance *aInstance);
 void otThreadSetChildTimeout(otInstance *aInstance, uint32_t aTimeout);
 
 /**
- * Get the IEEE 802.15.4 Extended PAN ID.
+ * Gets the IEEE 802.15.4 Extended PAN ID.
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  *
@@ -340,9 +340,9 @@ void otThreadSetChildTimeout(otInstance *aInstance, uint32_t aTimeout);
 const otExtendedPanId *otThreadGetExtendedPanId(otInstance *aInstance);
 
 /**
- * Set the IEEE 802.15.4 Extended PAN ID.
+ * Sets the IEEE 802.15.4 Extended PAN ID.
  *
- * This function can only be called while Thread protocols are disabled.  A successful
+ * @note Can only be called while Thread protocols are disabled. A successful
  * call to this function invalidates the Active and Pending Operational Datasets in
  * non-volatile memory.
  *
@@ -593,9 +593,9 @@ const char *otThreadGetNetworkName(otInstance *aInstance);
 otError otThreadSetNetworkName(otInstance *aInstance, const char *aNetworkName);
 
 /**
- * Get the Thread Domain Name.
+ * Gets the Thread Domain Name.
  *
- * This function is only available since Thread 1.2.
+ * @note Available since Thread 1.2.
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  *
@@ -607,10 +607,9 @@ otError otThreadSetNetworkName(otInstance *aInstance, const char *aNetworkName);
 const char *otThreadGetDomainName(otInstance *aInstance);
 
 /**
- * Set the Thread Domain Name.
+ * Sets the Thread Domain Name. Only succeeds when Thread protocols are disabled.
  *
- * This function is only available since Thread 1.2.
- * This function succeeds only when Thread protocols are disabled.
+ * @note Available since Thread 1.2.
  *
  * @param[in]  aInstance     A pointer to an OpenThread instance.
  * @param[in]  aDomainName   A pointer to the Thread Domain Name.
@@ -624,9 +623,11 @@ const char *otThreadGetDomainName(otInstance *aInstance);
 otError otThreadSetDomainName(otInstance *aInstance, const char *aDomainName);
 
 /**
- * Set/Clear the Interface Identifier manually specified for the Thread Domain Unicast Address.
+ * Sets or clears the Interface Identifier manually specified for the Thread Domain Unicast Address.
  *
- * This function is only available since Thread 1.2 when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled.
+ * Available when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled.
+ *
+ * @note Only available since Thread 1.2.
  *
  * @param[in]  aInstance   A pointer to an OpenThread instance.
  * @param[in]  aIid        A pointer to the Interface Identifier to set or NULL to clear.
@@ -639,9 +640,11 @@ otError otThreadSetDomainName(otInstance *aInstance, const char *aDomainName);
 otError otThreadSetFixedDuaInterfaceIdentifier(otInstance *aInstance, const otIp6InterfaceIdentifier *aIid);
 
 /**
- * Get the Interface Identifier manually specified for the Thread Domain Unicast Address.
+ * Gets the Interface Identifier manually specified for the Thread Domain Unicast Address.
  *
- * This function is only available since Thread 1.2 when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled.
+ * Available when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled.
+ *
+ * @note Only available since Thread 1.2.
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  *