[cli] add Doxygen tags to SRP commands (#9615)

2026-07-28 14:47:46 +00:00 · 2023-11-20 16:18:25 -08:00
parent beea7bac68
commit 364e315768
1 changed files with 375 additions and 0 deletions
@@ -71,6 +71,17 @@ template <> otError SrpClient::Process<Cmd("autostart")>(Arg aArgs[])
    otError error = OT_ERROR_NONE;
    bool    enable;

+    /**
+     * @cli srp client autostart (get)
+     * @code
+     * srp client autostart
+     * Disabled
+     * Done
+     * @endcode
+     * @par
+     * Indicates the current state of auto-start mode (enabled or disabled).
+     * @sa otSrpClientIsAutoStartModeEnabled
+     */
    if (aArgs[0].IsEmpty())
    {
        OutputEnabledDisabledStatus(otSrpClientIsAutoStartModeEnabled(GetInstancePtr()));
@@ -79,10 +90,50 @@ template <> otError SrpClient::Process<Cmd("autostart")>(Arg aArgs[])

    SuccessOrExit(error = Interpreter::ParseEnableOrDisable(aArgs[0], enable));

+    /**
+     * @cli srp client autostart enable
+     * @code
+     * srp client autostart enable
+     * Done
+     * @endcode
+     * @par
+     * Enables auto-start mode.
+     * @par
+     * When auto-start is enabled, the SRP client monitors Thread
+     * network data to discover SRP servers, to select the preferred
+     * server, and to automatically start and stop the client when
+     * an SRP server is detected.
+     * @par
+     * Three categories of network data entries indicate the presence of an SRP sever,
+     * and are preferred in the following order:
+     *  -# Unicast entries in which the server address is included in the service
+     *  data. If there are multiple options, the option with the lowest numerical
+     *  IPv6 address is preferred.
+     *  -# Anycast entries that each have a sequence number. The largest sequence
+     *  number as specified by Serial Number Arithmetic Logic
+     *  in RFC-1982 is preferred.
+     *  -# Unicast entries in which the server address information is included
+     *  with the server data. If there are multiple options, the option with the
+     *  lowest numerical IPv6 address is preferred.
+     * @sa otSrpClientEnableAutoStartMode
+     */
    if (enable)
    {
        otSrpClientEnableAutoStartMode(GetInstancePtr(), /* aCallback */ nullptr, /* aContext */ nullptr);
    }
+    /**
+     * @cli srp client autostart disable
+     * @code
+     * srp client autostart disable
+     * Done
+     * @endcode
+     * @par
+     * Disables the auto-start mode.
+     * @par
+     * Disabling auto-start mode does not stop a running client.
+     * However, the SRP client stops monitoring Thread network data.
+     * @sa otSrpClientDisableAutoStartMode
+     */
    else
    {
        otSrpClientDisableAutoStartMode(GetInstancePtr());
@@ -94,6 +145,22 @@ exit:

 #endif // OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE

+/**
+ * @cli srp client callback (enable/disable, get)
+ * @code
+ * srp client callback enable
+ * Done
+ * @endcode
+ * @code
+ * srp client callback
+ * Enabled
+ * Done
+ * @endcode
+ * @cparam srp client callback [@ca{enable}|@ca{disable}]
+ * @par
+ * Gets or enables/disables printing callback events from the SRP client.
+ * @sa otSrpClientSetCallback
+ */
 template <> otError SrpClient::Process<Cmd("callback")>(Arg aArgs[])
 {
    otError error = OT_ERROR_NONE;
@@ -114,10 +181,38 @@ template <> otError SrpClient::Process<Cmd("host")>(Arg aArgs[])
 {
    otError error = OT_ERROR_NONE;

+    /**
+     * @cli srp client host
+     * @code
+     * srp client host
+     * name:"dev4312", state:Registered, addrs:[fd00:0:0:0:0:0:0:1234, fd00:0:0:0:0:0:0:beef]
+     * Done
+     * @endcode
+     * @par api_copy
+     * #otSrpClientGetHostInfo
+     */
    if (aArgs[0].IsEmpty())
    {
        OutputHostInfo(0, *otSrpClientGetHostInfo(GetInstancePtr()));
    }
+    /**
+     * @cli srp client host name (set, get)
+     * @code
+     * srp client host name dev4312
+     * Done
+     * @endcode
+     * @code
+     * srp client host name
+     * dev4312
+     * Done
+     * @endcode
+     * @cparam srp client host name [@ca{name}]
+     * To set the client host name when the host has either been removed or not yet
+     * registered with the server, use the `name` parameter.
+     * @par
+     * Sets or returns the host name of the SRP client.
+     * @sa otSrpClientSetHostName
+     */
    else if (aArgs[0] == "name")
    {
        if (aArgs[1].IsEmpty())
@@ -149,6 +244,24 @@ template <> otError SrpClient::Process<Cmd("host")>(Arg aArgs[])
            IgnoreError(otSrpClientSetHostName(GetInstancePtr(), hostName));
        }
    }
+    /**
+     * @cli srp client host state
+     * @code
+     * srp client host state
+     * Registered
+     * Done
+     * @endcode
+     * @par
+     * Returns the state of the SRP client host. Possible states:
+     *   * `ToAdd`: Item to be added/registered.
+     *	 * `Adding`: Item is being added/registered.
+     *   * `ToRefresh`: Item to be refreshed for lease renewal.
+     *   * `Refreshing`: Item is beig refreshed.
+     *   * `ToRemove`: Item to be removed.
+     *   * `Removing`: Item is being removed.
+     *   * `Registered`: Item is registered with server.
+     *   * `Removed`: Item has been removed.
+     */
    else if (aArgs[0] == "state")
    {
        VerifyOrExit(aArgs[1].IsEmpty(), error = OT_ERROR_INVALID_ARGS);
@@ -156,6 +269,24 @@ template <> otError SrpClient::Process<Cmd("host")>(Arg aArgs[])
    }
    else if (aArgs[0] == "address")
    {
+        /**
+         * @cli srp client host address (get)
+         * @code
+         * srp client host address
+         * auto
+         * Done
+         * @endcode
+         * @code
+         * srp client host address
+         * fd00:0:0:0:0:0:0:1234
+         * fd00:0:0:0:0:0:0:beef
+         * Done
+         * @endcode
+         * @par
+         * Indicates whether auto address mode is enabled. If auto address mode is not
+         * enabled, then the list of SRP client host addresses is returned.
+         * @sa otSrpClientGetHostInfo
+         */
        if (aArgs[1].IsEmpty())
        {
            const otSrpClientHostInfo *hostInfo = otSrpClientGetHostInfo(GetInstancePtr());
@@ -172,6 +303,33 @@ template <> otError SrpClient::Process<Cmd("host")>(Arg aArgs[])
                }
            }
        }
+        /**
+         * @cli srp client host address (set)
+         * @code
+         * srp client host address auto
+         * Done
+         * @endcode
+         * @code
+         * srp client host address fd00::cafe
+         * Done
+         * @endcode
+         * @cparam srp client host address [auto|@ca{address...}]
+         *   * Use the `auto` parameter to enable auto host address mode.
+         *     When enabled, the client automatically uses all Thread `netif`
+         *     unicast addresses except for link-local and mesh-local
+         *     addresses. If there is no valid address, the mesh local
+         *     EID address gets added. The SRP client automatically
+         *     re-registers if addresses on the Thread `netif` are
+         *     added or removed.
+         *   * Explicitly specify the list of host addresses, separating
+         *     each address by a space. You can set this list while the client is
+         *     running. This will also disable auto host address mode.
+         * @par
+         * Enable auto host address mode or explicitly set the list of host
+         * addresses.
+         * @sa otSrpClientEnableAutoHostAddress
+         * @sa otSrpClientSetHostAddresses
+         */
        else if (aArgs[1] == "auto")
        {
            error = otSrpClientEnableAutoHostAddress(GetInstancePtr());
@@ -209,6 +367,25 @@ template <> otError SrpClient::Process<Cmd("host")>(Arg aArgs[])
            IgnoreError(otSrpClientSetHostAddresses(GetInstancePtr(), hostAddressArray, numAddresses));
        }
    }
+    /**
+     * @cli srp client host remove
+     * @code
+     * srp client host remove 1
+     * Done
+     * @endcode
+     * @cparam srp client host remove [@ca{removekeylease}] [@ca{sendunregtoserver}]
+     *   * The parameter `removekeylease` is an optional boolean value that indicates
+     *     whether the host key lease should also be removed (default is `false`).
+     *   * The parameter `sendunregtoserver` is an optional boolean value that indicates
+     *     whether the client host should send an "update" message to the server
+     *     even when the client host information has not yet been registered with the
+     *     server (default is `false`). This parameter can be specified only if the
+     *     `removekeylease` parameter is specified first in the command.
+     * @par
+     * Removes SRP client host information and all services from the SRP server.
+     * @sa otSrpClientRemoveHostAndServices
+     * @sa otSrpClientSetHostName
+     */
    else if (aArgs[0] == "remove")
    {
        bool removeKeyLease    = false;
@@ -227,6 +404,17 @@ template <> otError SrpClient::Process<Cmd("host")>(Arg aArgs[])

        error = otSrpClientRemoveHostAndServices(GetInstancePtr(), removeKeyLease, sendUnregToServer);
    }
+    /**
+     * @cli srp client host clear
+     * @code
+     * srp client host clear
+     * Done
+     * @endcode
+     * @par
+     * Clears all host information and all services.
+     * @sa otSrpClientClearHostAndServices
+     * @sa otSrpClientBuffersFreeAllServices
+     */
    else if (aArgs[0] == "clear")
    {
        VerifyOrExit(aArgs[1].IsEmpty(), error = OT_ERROR_INVALID_ARGS);
@@ -242,11 +430,45 @@ exit:
    return error;
 }

+/**
+ * @cli srp client leaseinterval (set, get)
+ * @code
+ * srp client leaseinterval 3600
+ * Done
+ * @endcode
+ * @code
+ * srp client leaseinterval
+ * 3600
+ * Done
+ * @endcode
+ * @cparam srp client leaseinterval [@ca{interval}]
+ * @par
+ * Sets or gets the lease interval in seconds.
+ * @sa otSrpClientSetLeaseInterval
+ * @sa otSrpClientGetLeaseInterval
+ */
 template <> otError SrpClient::Process<Cmd("leaseinterval")>(Arg aArgs[])
 {
    return Interpreter::GetInterpreter().ProcessGetSet(aArgs, otSrpClientGetLeaseInterval, otSrpClientSetLeaseInterval);
 }

+/**
+ * @cli srp client keyleaseinterval (set, get)
+ * @code
+ * srp client keyleaseinterval 864000
+ * Done
+ * @endcode
+ * @code
+ * srp client keyleaseinterval
+ * 864000
+ * Done
+ * @endcode
+ * @cparam srp client keyleaseinterval [@ca{interval}]
+ * @par
+ * Sets or gets the key lease interval in seconds.
+ * @sa otSrpClientSetKeyLeaseInterval
+ * @sa otSrpClientGetKeyLeaseInterval
+ */
 template <> otError SrpClient::Process<Cmd("keyleaseinterval")>(Arg aArgs[])
 {
    return Interpreter::GetInterpreter().ProcessGetSet(aArgs, otSrpClientGetKeyLeaseInterval,
@@ -258,6 +480,19 @@ template <> otError SrpClient::Process<Cmd("server")>(Arg aArgs[])
    otError           error          = OT_ERROR_NONE;
    const otSockAddr *serverSockAddr = otSrpClientGetServerAddress(GetInstancePtr());

+    /**
+     * @cli srp client server
+     * @code
+     * srp client server
+     * &lsqb;fd00:0:0:0:d88a:618b:384d:e760&rsqb;:4724
+     * Done
+     * @endcode
+     * @par
+     * Gets the socket address (IPv6 address and port number) of the SRP server
+     * that is being used by the SRP client. If the client is not running, the address
+     * is unspecified (all zeros) with a port number of 0.
+     * @sa otSrpClientGetServerAddress
+     */
    if (aArgs[0].IsEmpty())
    {
        OutputSockAddrLine(*serverSockAddr);
@@ -266,10 +501,30 @@ template <> otError SrpClient::Process<Cmd("server")>(Arg aArgs[])

    VerifyOrExit(aArgs[1].IsEmpty(), error = OT_ERROR_INVALID_ARGS);

+    /**
+     * @cli srp client server address
+     * @code
+     * srp client server address
+     * fd00:0:0:0:d88a:618b:384d:e760
+     * Done
+     * @endcode
+     * @par
+     * Returns the server's IPv6 address.
+     */
    if (aArgs[0] == "address")
    {
        OutputIp6AddressLine(serverSockAddr->mAddress);
    }
+    /**
+     * @cli srp client server port
+     * @code
+     * srp client server port
+     * 4724
+     * Done
+     * @endcode
+     * @par
+     * Returns the server's port number.
+     */
    else if (aArgs[0] == "port")
    {
        OutputLine("%u", serverSockAddr->mPort);
@@ -288,14 +543,70 @@ template <> otError SrpClient::Process<Cmd("service")>(Arg aArgs[])
    otError error = OT_ERROR_NONE;
    bool    isRemove;

+    /**
+     * @cli srp client service
+     * @code
+     * srp client service
+     * instance:"ins2", name:"_test2._udp,_sub1,_sub2", state:Registered, port:111, priority:1, weight:1
+     * instance:"ins1", name:"_test1._udp", state:Registered, port:777, priority:0, weight:0
+     * Done
+     * @endcode
+     * @par api_copy
+     * #otSrpClientGetServices
+     */
    if (aArgs[0].IsEmpty())
    {
        OutputServiceList(0, otSrpClientGetServices(GetInstancePtr()));
    }
+    /**
+     * @cli srp client service add
+     * @code
+     * srp client service add ins1 _test1._udp 777
+     * Done
+     * @endcode
+     * @code
+     * srp client service add ins2 _test2._udp,_sub1,_sub2 111 1 1
+     * Done
+     * @endcode
+     * @cparam srp client service add @ca{instancename} @ca{servicename} <!--
+     * * -->                          @ca{port} [@ca{priority}] <!--
+     * * -->                          [@ca{weight}] [@ca{txt}]
+     * The `servicename` parameter can optionally include a list of service subtype labels that are
+     * separated by commas. The examples here use generic naming. The `priority` and `weight` (both are `uint16_t`
+     * values) parameters are optional, and if not provided zero is used. The optional `txt` parameter sets the TXT data
+     * associated with the service. The `txt` value must be in hex-string format and is treated as an already encoded
+     * TXT data byte sequence.
+     * @par
+     * Adds a service with a given instance name, service name, and port number.
+     * @sa otSrpClientAddService
+     */
    else if (aArgs[0] == "add")
    {
        error = ProcessServiceAdd(aArgs);
    }
+    /**
+     * @cli srp client service remove
+     * @code
+     * srp client service remove ins2 _test2._udp
+     * Done
+     * @endcode
+     * @cparam srp client service remove @ca{instancename} @ca{servicename}
+     * @par
+     * Requests a service to be unregistered with the SRP server.
+     * @sa otSrpClientRemoveService
+     */
+    /**
+     * @cli srp client service name clear
+     * @code
+     * srp client service clear ins2 _test2._udp
+     * Done
+     * @endcode
+     * @cparam srp client service clear @ca{instancename} @ca{servicename}
+     * @par
+     * Clears a service, immediately removing it from the client service list,
+     * with no interaction with the SRP server.
+     * @sa otSrpClientClearService
+     */
    else if ((isRemove = (aArgs[0] == "remove")) || (aArgs[0] == "clear"))
    {
        // `remove`|`clear` <instance-name> <service-name>
@@ -327,6 +638,23 @@ template <> otError SrpClient::Process<Cmd("service")>(Arg aArgs[])
        }
    }
 #if OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE
+    /**
+     * @cli srp client service key (set, get)
+     * @code
+     * srp client service key enable
+     * Done
+     * @endcode
+     * @code
+     * srp client service key
+     * Enabled
+     * Done
+     * @endcode
+     * @par
+     * Gets or sets the service key record inclusion mode in the SRP client.
+     * This command is intended for testing only, and requires that
+     * `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` be enabled.
+     * @sa otSrpClientIsServiceKeyRecordEnabled
+     */
    else if (aArgs[0] == "key")
    {
        // `key [enable/disable]`
@@ -508,6 +836,17 @@ void SrpClient::OutputService(uint8_t aIndentSize, const otSrpClientService &aSe
               aService.mPort, aService.mPriority, aService.mWeight);
 }

+/**
+ * @cli srp client start
+ * @code
+ * srp client start fd00::d88a:618b:384d:e760 4724
+ * Done
+ * @endcode
+ * @cparam srp client start @ca{serveraddr} @ca{serverport}
+ * @par
+ * Starts the SRP client operation.
+ * @sa otSrpClientStart
+ */
 template <> otError SrpClient::Process<Cmd("start")>(Arg aArgs[])
 {
    otError    error = OT_ERROR_NONE;
@@ -523,6 +862,16 @@ exit:
    return error;
 }

+/**
+ * @cli srp client state
+ * @code
+ * srp client state
+ * Enabled
+ * Done
+ * @endcode
+ * @par api_copy
+ * #otSrpClientIsRunning
+ */
 template <> otError SrpClient::Process<Cmd("state")>(Arg aArgs[])
 {
    otError error = OT_ERROR_NONE;
@@ -535,6 +884,15 @@ exit:
    return error;
 }

+/**
+ * @cli srp client stop
+ * @code
+ * srp client stop
+ * Done
+ * @endcode
+ * @par api_copy
+ * #otSrpClientStop
+ */
 template <> otError SrpClient::Process<Cmd("stop")>(Arg aArgs[])
 {
    otError error = OT_ERROR_NONE;
@@ -546,6 +904,23 @@ exit:
    return error;
 }

+/**
+ * @cli srp client ttl (set, get)
+ * @code
+ * srp client ttl 3600
+ * Done
+ * @endcode
+ * @code
+ * srp client ttl
+ * 3600
+ * Done
+ * @endcode
+ * @cparam srp client ttl [@ca{value}]
+ * @par
+ * Sets or gets the `ttl`(time to live) value in seconds.
+ * @sa otSrpClientSetTtl
+ * @sa otSrpClientGetTtl
+ */
 template <> otError SrpClient::Process<Cmd("ttl")>(Arg aArgs[])
 {
    return Interpreter::GetInterpreter().ProcessGetSet(aArgs, otSrpClientGetTtl, otSrpClientSetTtl);