[docs] add Doxygen tags for CLI commands (macfilter - `macfilter ad…

…dr`) (openthread#9424)
espressif · Sep 20, 2023 · 3905006 · 3905006
1 parent 753b305
commit 3905006
Show file tree

Hide file tree

Showing 3 changed files with 141 additions and 17 deletions.
diff --git 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 (358)
+#define OPENTHREAD_API_VERSION (359)
 
 /**
  * @addtogroup api-instance

diff --git a/include/openthread/link.h b/include/openthread/link.h
@@ -714,7 +714,7 @@ void otLinkSetMaxFrameRetriesIndirect(otInstance *aInstance, uint8_t aMaxFrameRe
 /**
  * Gets the address mode of MAC filter.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  *
@@ -726,7 +726,7 @@ otMacFilterAddressMode otLinkFilterGetAddressMode(otInstance *aInstance);
 /**
  * Sets the address mode of MAC filter.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  * @param[in]  aMode      The address mode to set.
@@ -737,7 +737,7 @@ void otLinkFilterSetAddressMode(otInstance *aInstance, otMacFilterAddressMode aM
 /**
  * Adds an Extended Address to MAC filter.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @param[in]  aInstance    A pointer to an OpenThread instance.
  * @param[in]  aExtAddress  A pointer to the Extended Address (MUST NOT be NULL).
@@ -751,7 +751,7 @@ otError otLinkFilterAddAddress(otInstance *aInstance, const otExtAddress *aExtAd
 /**
  * Removes an Extended Address from MAC filter.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * No action is performed if there is no existing entry in Filter matching the given Extended Address.
  *
@@ -764,7 +764,7 @@ void otLinkFilterRemoveAddress(otInstance *aInstance, const otExtAddress *aExtAd
 /**
  * Clears all the Extended Addresses from MAC filter.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  *
@@ -774,7 +774,7 @@ void otLinkFilterClearAddresses(otInstance *aInstance);
 /**
  * Gets an in-use address filter entry.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @param[in]      aInstance  A pointer to an OpenThread instance.
  * @param[in,out]  aIterator  A pointer to the MAC filter iterator context. To get the first in-use address filter
@@ -791,7 +791,7 @@ otError otLinkFilterGetNextAddress(otInstance *aInstance, otMacFilterIterator *a
  * Adds a fixed received signal strength (in dBm) entry for the messages from a given Extended Address in
  * MAC Filter.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @param[in]  aInstance    A pointer to an OpenThread instance.
  * @param[in]  aExtAddress  A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL.
@@ -806,7 +806,7 @@ otError otLinkFilterAddRssIn(otInstance *aInstance, const otExtAddress *aExtAddr
 /**
  * Removes a MAC Filter entry for fixed received signal strength setting for a given Extended Address.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * No action is performed if there is no existing entry in Filter matching the given Extended Address.
  *
@@ -819,7 +819,7 @@ void otLinkFilterRemoveRssIn(otInstance *aInstance, const otExtAddress *aExtAddr
 /**
  * Sets the default received signal strength (in dBm) on MAC Filter.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * The default RSS value is used for all received frames from addresses for which there is no explicit RSS-IN entry
  * in the Filter list (added using `otLinkFilterAddRssIn()`).
@@ -833,7 +833,7 @@ void otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss);
 /**
  * Clears any previously set default received signal strength (in dBm) on MAC Filter.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @param[in]  aInstance    A pointer to an OpenThread instance.
  *
@@ -843,7 +843,7 @@ void otLinkFilterClearDefaultRssIn(otInstance *aInstance);
 /**
  * Clears all the received signal strength entries (including default RSS-in) on MAC Filter.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  *
@@ -853,7 +853,7 @@ void otLinkFilterClearAllRssIn(otInstance *aInstance);
 /**
  * Gets an in-use RssIn filter entry.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @param[in]      aInstance  A pointer to an OpenThread instance.
  * @param[in,out]  aIterator  A pointer to the MAC filter iterator context. MUST NOT be NULL.
@@ -871,7 +871,7 @@ otError otLinkFilterGetNextRssIn(otInstance *aInstance, otMacFilterIterator *aIt
 /**
  * Enables/disables IEEE 802.15.4 radio filter mode.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * The radio filter is mainly intended for testing. It can be used to temporarily block all tx/rx on the 802.15.4 radio.
  * When radio filter is enabled, radio is put to sleep instead of receive (to ensure device does not receive any frame
@@ -887,7 +887,7 @@ void otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled);
 /**
  * Indicates whether the IEEE 802.15.4 radio filter is enabled or not.
  *
- * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled.
+ * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
  *
  * @retval TRUE   If the radio filter is enabled.
  * @retval FALSE  If the radio filter is disabled.

diff --git a/src/cli/cli_mac_filter.cpp b/src/cli/cli_mac_filter.cpp
@@ -137,10 +137,49 @@ template <> otError MacFilter::Process<Cmd("addr")>(Arg aArgs[])
     otError      error = OT_ERROR_NONE;
     otExtAddress extAddr;
 
+    /**
+     * @cli macfilter addr
+     * @code
+     * macfilter addr
+     * Allowlist
+     * 0f6127e33af6b403 : rss -95 (lqi 1)
+     * 0f6127e33af6b402
+     * Done
+     * @endcode
+     * @par
+     * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
+     * @par
+     * Provides the following information:
+     * - Current mode of the MAC filter list: Either `AllowList`, `DenyList,` or `Disabled`
+     * - A list of all the extended addresses in the filter. The received signal strength (rss) and
+     *   link quality indicator (lqi) are listed next to the address if these values have been set to be
+     *   different from the default values.
+     * @sa otLinkFilterGetAddressMode
+     */
     if (aArgs[0].IsEmpty())
     {
         OutputFilter(kAddressFilter);
     }
+    /**
+     * @cli macfilter addr add
+     * @code
+     * macfilter addr add 0f6127e33af6b403 -95
+     * Done
+     * @endcode
+     * @code
+     * macfilter addr add 0f6127e33af6b402
+     * Done
+     * @endcode
+     * @cparam macfilter addr add @ca{extaddr} [@ca{rss}]
+     * @par
+     * Is available only when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
+     * @par
+     * Adds an IEEE 802.15.4 Extended Address to the MAC filter list.
+     * If you specify the optional `rss` argument, this fixes the received signal strength for messages from the
+     * address. If you do not use the `rss` option, the address will use whatever default value you have set.
+     * If you have not set a default, the signal strength will be the over-air signal.
+     * @sa otLinkFilterAddAddress
+     */
     else if (aArgs[0] == "add")
     {
         SuccessOrExit(error = aArgs[1].ParseAsHexString(extAddr.m8));
@@ -156,21 +195,80 @@ template <> otError MacFilter::Process<Cmd("addr")>(Arg aArgs[])
             SuccessOrExit(error = otLinkFilterAddRssIn(GetInstancePtr(), &extAddr, rss));
         }
     }
+    /**
+     * @cli macfilter addr remove
+     * @code
+     * macfilter addr remove 0f6127e33af6b402
+     * Done
+     * @endcode
+     * @cparam macfilter addr remove @ca{extaddr}
+     * @par
+     * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
+     * @par
+     * This command removes the specified extended address from the MAC filter list.
+     * @note No action is performed if the specified extended address does not match an entry in the MAC filter list.
+     * @sa otLinkFilterRemoveAddress
+     */
     else if (aArgs[0] == "remove")
     {
         SuccessOrExit(error = aArgs[1].ParseAsHexString(extAddr.m8));
         otLinkFilterRemoveAddress(GetInstancePtr(), &extAddr);
     }
+    /**
+     * @cli macfilter addr clear
+     * @code
+     * macfilter addr clear
+     * Done
+     * @endcode
+     * @par
+     * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled.
+     * @par
+     * This command clears all the extended addresses from the MAC filter list.
+     * @note This command does not affect entries in the `RssIn` list. That list contains extended addresses where the
+     * `rss` has been set to a fixed value that differs from the default.
+     * @sa otLinkFilterClearAddresses
+     */
     else if (aArgs[0] == "clear")
     {
         otLinkFilterClearAddresses(GetInstancePtr());
     }
     else
     {
         static const char *const kModeCommands[] = {
-            "disable",   // (0) OT_MAC_FILTER_ADDRESS_MODE_DISABLED
+            /**
+             * @cli macfilter addr disable
+             * @code
+             * macfilter addr disable
+             * Done
+             * @endcode
+             * @par
+             * Disables MAC filter modes.
+             */
+            "disable", // (0) OT_MAC_FILTER_ADDRESS_MODE_DISABLED
+            /**
+             * @cli macfilter addr allowlist
+             * @code
+             * macfilter addr allowlist
+             * Done
+             * @endcode
+             * @par
+             * Enables the `allowlist` MAC filter mode, which means that only the MAC addresses in the MAC filter list
+             * will be allowed access.
+             * @sa otLinkFilterSetAddressMode
+             */
             "allowlist", // (1) OT_MAC_FILTER_ADDRESS_MODE_ALLOWLIST
-            "denylist",  // (2) OT_MAC_FILTER_ADDRESS_MODE_DENYLIST
+            /**
+             * @cli macfilter addr denylist
+             * @code
+             * macfilter addr denylist
+             * Done
+             * @endcode
+             * @par
+             * Enables the `denylist` MAC filter mode, which means that all MAC addresses in the MAC filter list
+             * will be denied access.
+             * @sa otLinkFilterSetAddressMode
+             */
+            "denylist", // (2) OT_MAC_FILTER_ADDRESS_MODE_DENYLIST
         };
 
         for (size_t index = 0; index < OT_ARRAY_LENGTH(kModeCommands); index++)
@@ -276,6 +374,32 @@ otError MacFilter::Process(Arg aArgs[])
     otError        error = OT_ERROR_INVALID_COMMAND;
     const Command *command;
 
+    /**
+     * @cli macfilter
+     * @code
+     * macfilter
+     * Address Mode: Allowlist
+     * 0f6127e33af6b403 : rss -95 (lqi 1)
+     * 0f6127e33af6b402
+     * RssIn List:
+     * 0f6127e33af6b403 : rss -95 (lqi 1)
+     * Default rss: -50 (lqi 3)
+     * Done
+     * @endcode
+     * @par
+     * Provides the following information:
+     * - `Address Mode`: Current mode of the MAC filter: Either `AllowList`, `DenyList,` or `Disabled`
+     * - A list of all the extended addresses in the MAC filter list. The received signal strength (rss) and
+     *   link quality indicator (lqi) are listed next to the address if these values have been set to be
+     *   different from the default values.
+     * - A separate list (`RssIn List`) that shows all the extended addresses where the `rss` has been set to
+     *   be different from the default value.
+     * - `Default rss`: Shows the default values, if applicable, for the `rss` and `lqi` settings.
+     * @note An extended address can be in the `RssIn` list without being in the MAC filter list.
+     * @sa otLinkFilterSetAddressMode
+     * @sa otLinkFilterGetNextAddress
+     * @sa otLinkFilterGetNextRssIn
+     */
     if (aArgs[0].IsEmpty())
     {
         OutputFilter(kAddressFilter | kRssFilter);