[docs] add Doxygen support for CLI comments (#7749)

include/openthread/border_agent.h

@@ -63,17 +63,17 @@ typedef enum otBorderAgentState
 } otBorderAgentState;
 
 /**
- * This function gets the state of Thread Border Agent role.
+ * Gets the #otBorderAgentState of the Thread Border Agent role.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  *
- * @returns State of the Border Agent.
+ * @returns The current #otBorderAgentState of the Border Agent.
  *
  */
 otBorderAgentState otBorderAgentGetState(otInstance *aInstance);
 
 /**
- * This function gets the UDP port of Thread Border Agent service.
+ * Gets the UDP port of the Thread Border Agent service.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  *

include/openthread/border_router.h

@@ -73,7 +73,7 @@ extern "C" {
 otError otBorderRoutingInit(otInstance *aInstance, uint32_t aInfraIfIndex, bool aInfraIfIsRunning);
 
 /**
- * This method enables/disables the Border Routing Manager.
+ * Enables or disables the Border Routing Manager.
  *
  * @note  The Border Routing Manager is disabled by default.
  *
@@ -87,10 +87,11 @@ otError otBorderRoutingInit(otInstance *aInstance, uint32_t aInfraIfIndex, bool
 otError otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled);
 
 /**
- * This method returns the off-mesh-routable (OMR) prefix.
+ * Gets the Off-Mesh-Routable (OMR) Prefix, for example `fdfc:1ff5:1512:5622::/64`.
  *
- * The randomly generated 64-bit prefix will be published
- * in the Thread network if there isn't already an OMR prefix.
+ * An OMR Prefix is a randomly generated 64-bit prefix that's published in the
+ * Thread network if there isn't already an OMR prefix. This prefix can be reached
+ * from the local Wi-Fi or Ethernet network.
  *
  * @param[in]   aInstance  A pointer to an OpenThread instance.
  * @param[out]  aPrefix    A pointer to where the prefix will be output to.
@@ -102,11 +103,10 @@ otError otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled);
 otError otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix);
 
 /**
- * This method returns the on-link prefix for the adjacent infrastructure link.
+ * Gets the On-Link Prefix for the adjacent infrastructure link, for example `fd41:2650:a6f5:0::/64`.
  *
- * The randomly generated 64-bit prefix will be advertised
- * on the infrastructure link if there isn't already a usable
- * on-link prefix being advertised on the link.
+ * An On-Link Prefix is a randomly generated 64-bit prefix that's advertised on the infrastructure
+ * link if there isn't already a usable on-link prefix being advertised on the link.
  *
  * @param[in]   aInstance  A pointer to an OpenThread instance.
  * @param[out]  aPrefix    A pointer to where the prefix will be output to.
@@ -118,12 +118,11 @@ otError otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix)
 otError otBorderRoutingGetOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix);
 
 /**
- * This function returns the local NAT64 prefix.
+ * Gets the local NAT64 Prefix of the Border Router.
  *
- * This prefix might not be advertised in the Thread network.
+ * NAT64 Prefix might not be advertised in the Thread network.
  *
- * This function is only available when `OPENTHREAD_CONFIG_BORDER_ROUTING_NAT64_ENABLE`
- * is enabled.
+ * `OPENTHREAD_CONFIG_BORDER_ROUTING_NAT64_ENABLE` must be enabled.
  *
  * @param[in]   aInstance   A pointer to an OpenThread instance.
  * @param[out]  aPrefix     A pointer to where the prefix will be output to.

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (221)
+#define OPENTHREAD_API_VERSION (222)
 
 /**
  * @addtogroup api-instance

include/openthread/joiner.h

@@ -94,7 +94,7 @@ typedef struct otJoinerDiscerner
 typedef void (*otJoinerCallback)(otError aError, void *aContext);
 
 /**
- * This function enables the Thread Joiner role.
+ * Enables the Thread Joiner role.
  *
  * @param[in]  aInstance         A pointer to an OpenThread instance.
  * @param[in]  aPskd             A pointer to the PSKd.
@@ -123,7 +123,7 @@ otError otJoinerStart(otInstance *     aInstance,
                       void *           aContext);
 
 /**
- * This function disables the Thread Joiner role.
+ * Disables the Thread Joiner role.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  *
@@ -131,7 +131,7 @@ otError otJoinerStart(otInstance *     aInstance,
 void otJoinerStop(otInstance *aInstance);
 
 /**
- * This function returns the Joiner State.
+ * Gets the Joiner State.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  *
@@ -146,12 +146,12 @@ void otJoinerStop(otInstance *aInstance);
 otJoinerState otJoinerGetState(otInstance *aInstance);
 
 /**
- * This function gets the Joiner ID.
+ * Gets the Joiner ID.
  *
  * If a Joiner Discerner is not set, Joiner ID is the first 64 bits of the result of computing SHA-256 over
  * factory-assigned IEEE EUI-64. Otherwise the Joiner ID is calculated from the Joiner Discerner value.
  *
- * The Joiner ID is also used as the device's IEEE 802.15.4 Extended Address during commissioning process.
+ * The Joiner ID is also used as the device's IEEE 802.15.4 Extended Address during the commissioning process.
  *
  * @param[in]   aInstance  A pointer to the OpenThread instance.
  *
@@ -161,13 +161,11 @@ otJoinerState otJoinerGetState(otInstance *aInstance);
 const otExtAddress *otJoinerGetId(otInstance *aInstance);
 
 /**
- * This function sets the Joiner Discerner.
+ * Sets the Joiner Discerner.
  *
- * The Joiner Discerner is used to calculate the Joiner ID used during commissioning/joining process.
- *
- * By default (when a discerner is not provided or set to NULL), Joiner ID is derived as first 64 bits of the result
- * of computing SHA-256 over factory-assigned IEEE EUI-64. Note that this is the main behavior expected by Thread
- * specification.
+ * The Joiner Discerner is used to calculate the Joiner ID during the Thread Commissioning process. For more
+ * information, refer to #otJoinerGetId.
+ * @note The Joiner Discerner takes the place of the Joiner EUI-64 during the joiner session of Thread Commissioning.
  *
  * @param[in]   aInstance    A pointer to the OpenThread instance.
  * @param[in]   aDiscerner   A pointer to a Joiner Discerner. If NULL clears any previously set discerner.
@@ -180,7 +178,7 @@ const otExtAddress *otJoinerGetId(otInstance *aInstance);
 otError otJoinerSetDiscerner(otInstance *aInstance, otJoinerDiscerner *aDiscerner);
 
 /**
- * This function gets the Joiner Discerner.
+ * Gets the Joiner Discerner. For more information, refer to #otJoinerSetDiscerner.
  *
  * @param[in]   aInstance       A pointer to the OpenThread instance.
  *

include/openthread/netdata_publisher.h

@@ -175,10 +175,10 @@ void otNetDataSetDnsSrpServicePublisherCallback(otInstance *
                                                 void *                                  aContext);
 
 /**
- * This function unpublishes any previously added "DNS/SRP (Anycast or Unicast) Service" entry from the Thread Network
+ * Unpublishes any previously added DNS/SRP (Anycast or Unicast) Service entry from the Thread Network
  * Data.
  *
- * This function requires the feature `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` to be enabled.
+ * `OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE` must be enabled.
  *
  * @param[in] aInstance  A pointer to an OpenThread instance.
  *
@@ -270,9 +270,9 @@ void otNetDataSetPrefixPublisherCallback(otInstance *                     aInsta
                                          void *                           aContext);
 
 /**
- * This function unpublishes a previously published prefix (on-mesh or external route).
+ * Unpublishes a previously published On-Mesh or External Route Prefix.
  *
- * This function requires the feature `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` to be enabled.
+ * `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE` must be enabled.
  *
  * @param[in] aInstance          A pointer to an OpenThread instance.
  * @param[in] aPrefix            The prefix to unpublish (MUST NOT be NULL).

include/openthread/platform/radio.h

@@ -442,7 +442,7 @@ const char *otPlatRadioGetVersionString(otInstance *aInstance);
 int8_t otPlatRadioGetReceiveSensitivity(otInstance *aInstance);
 
 /**
- * Get the factory-assigned IEEE EUI-64 for this interface.
+ * Gets the factory-assigned IEEE EUI-64 for this interface.
  *
  * @param[in]  aInstance   The OpenThread instance structure.
  * @param[out] aIeeeEui64  A pointer to the factory-assigned IEEE EUI-64.