[docs] CLI Dataset (#7944)

include/openthread/dataset.h

@@ -49,6 +49,8 @@ extern "C" {
  *
  * @{
  *
+ * For FTD and MTD builds, the Operational Dataset API includes functions to manage Active and Pending datasets
+ * and dataset TLVs.
  */
 
 #define OT_NETWORK_KEY_SIZE 16 ///< Size of the Thread Network Key (bytes)
@@ -339,7 +341,7 @@ typedef void (*otDatasetMgmtSetCallback)(otError aResult, void *aContext);
 bool otDatasetIsCommissioned(otInstance *aInstance);
 
 /**
- * This function gets the Active Operational Dataset.
+ * Gets the Active Operational Dataset.
  *
  * @param[in]   aInstance A pointer to an OpenThread instance.
  * @param[out]  aDataset  A pointer to where the Active Operational Dataset will be placed.
@@ -363,7 +365,7 @@ otError otDatasetGetActive(otInstance *aInstance, otOperationalDataset *aDataset
 otError otDatasetGetActiveTlvs(otInstance *aInstance, otOperationalDatasetTlvs *aDataset);
 
 /**
- * This function sets the Active Operational Dataset.
+ * Sets the Active Operational Dataset.
  *
  * If the dataset does not include an Active Timestamp, the dataset is only partially complete.
  *
@@ -439,7 +441,7 @@ otError otDatasetGetPending(otInstance *aInstance, otOperationalDataset *aDatase
 otError otDatasetGetPendingTlvs(otInstance *aInstance, otOperationalDatasetTlvs *aDataset);
 
 /**
- * This function sets the Pending Operational Dataset.
+ * Sets the Pending Operational Dataset.
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  * @param[in]  aDataset  A pointer to the Pending Operational Dataset.
@@ -465,7 +467,7 @@ otError otDatasetSetPending(otInstance *aInstance, const otOperationalDataset *a
 otError otDatasetSetPendingTlvs(otInstance *aInstance, const otOperationalDatasetTlvs *aDataset);
 
 /**
- * This function sends MGMT_ACTIVE_GET.
+ * Sends MGMT_ACTIVE_GET.
  *
  * @param[in]  aInstance           A pointer to an OpenThread instance.
  * @param[in]  aDatasetComponents  A pointer to a Dataset Components structure specifying which components to request.
@@ -484,7 +486,7 @@ otError otDatasetSendMgmtActiveGet(otInstance *                          aInstan
                                    const otIp6Address *                  aAddress);
 
 /**
- * This function sends MGMT_ACTIVE_SET.
+ * Sends MGMT_ACTIVE_SET.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  * @param[in]  aDataset   A pointer to operational dataset.
@@ -506,7 +508,7 @@ otError otDatasetSendMgmtActiveSet(otInstance *                aInstance,
                                    void *                      aContext);
 
 /**
- * This function sends MGMT_PENDING_GET.
+ * Sends MGMT_PENDING_GET.
  *
  * @param[in]  aInstance           A pointer to an OpenThread instance.
  * @param[in]  aDatasetComponents  A pointer to a Dataset Components structure specifying which components to request.
@@ -525,7 +527,7 @@ otError otDatasetSendMgmtPendingGet(otInstance *                          aInsta
                                     const otIp6Address *                  aAddress);
 
 /**
- * This function sends MGMT_PENDING_SET.
+ * Sends MGMT_PENDING_SET.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  * @param[in]  aDataset   A pointer to operational dataset.
@@ -566,9 +568,9 @@ otError otDatasetGeneratePskc(const char *           aPassPhrase,
                               otPskc *               aPskc);
 
 /**
- * This function sets an `otNetworkName` instance from a given null terminated C string.
+ * Sets an `otNetworkName` instance from a given null terminated C string.
  *
- * This function also validates that the given @p aNameString follows UTF-8 encoding and its length is not longer than
+ * @p aNameString must follow UTF-8 encoding and the Network Name length must not be longer than
  * `OT_NETWORK_NAME_MAX_SIZE`.
  *
  * @param[out] aNetworkName        A pointer to the `otNetworkName` to set.

include/openthread/dataset_ftd.h

@@ -50,7 +50,7 @@ extern "C" {
  */
 
 /**
- * This method creates a new Operational Dataset to use when forming a new network.
+ * For FTD only, creates a new Operational Dataset to use when forming a new network.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  * @param[out] aDataset   The Operational Dataset.
@@ -62,7 +62,7 @@ extern "C" {
 otError otDatasetCreateNewNetwork(otInstance *aInstance, otOperationalDataset *aDataset);
 
 /**
- * Get minimal delay timer.
+ * For FTD only, gets a minimal delay timer.
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  *
@@ -72,7 +72,7 @@ otError otDatasetCreateNewNetwork(otInstance *aInstance, otOperationalDataset *a
 uint32_t otDatasetGetDelayTimerMinimal(otInstance *aInstance);
 
 /**
- * Set minimal delay timer.
+ * For FTD only, sets a minimal delay timer.
  *
  * @note This API is reserved for testing and demo purposes only. Changing settings with
  * this API will render a production application non-compliant with the Thread Specification.

include/openthread/dataset_updater.h

@@ -45,20 +45,18 @@ extern "C" {
 /**
  * @addtogroup api-operational-dataset
  *
- * @brief
- *   This module includes functions for Dataset Updater.
- *
- *   The functions in this module are available when Dataset Updater feature is enabled (i.e.
- *   `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE` is set to 1). Further this feature is available only on an FTD build.
- *
  * @{
  *
+ * For FTD builds only, Dataset Updater includes functions to manage dataset updates.
+ *
  */
 
 /**
  * This callback function pointer is called when a Dataset update request finishes, reporting success or failure status
  * of the Dataset update request.
  *
+ * Available when `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE` is enabled.
+ *
  * @param[in] aError   The error status.
  *                     OT_ERROR_NONE            indicates successful Dataset update.
  *                     OT_ERROR_INVALID_STATE   indicates failure due invalid state (MLE being disabled).
@@ -73,6 +71,8 @@ typedef void (*otDatasetUpdaterCallback)(otError aError, void *aContext);
 /**
  * This function requests an update to Operational Dataset.
  *
+ * Available when `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE` is enabled.
+ *
  * @p aDataset should contain the fields to be updated and their new value. It must not contain Active or Pending
  * Timestamp fields. The Delay field is optional, if not provided a default value (1000 ms) would be used.
  *
@@ -96,6 +96,8 @@ otError otDatasetUpdaterRequestUpdate(otInstance *                aInstance,
 /**
  * This function cancels an ongoing (if any) Operational Dataset update request.
  *
+ * Available when `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE` is enabled.
+ *
  * @param[in]  aInstance         A pointer to an OpenThread instance.
  *
  */
@@ -104,6 +106,8 @@ void otDatasetUpdaterCancelUpdate(otInstance *aInstance);
 /**
  * This function indicates whether there is an ongoing Operation Dataset update request.
  *
+ * Available when `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE` is enabled.
+ *
  * @param[in]  aInstance         A pointer to an OpenThread instance.
  *
  * @retval TRUE    There is an ongoing update.

include/openthread/instance.h

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