From 1d2b549e80663dd521e64b97f0a07e62bbcb88d9 Mon Sep 17 00:00:00 2001 From: jrhodie <139580534+jrhodie@users.noreply.github.com> Date: Tue, 28 Nov 2023 21:54:10 -0800 Subject: [PATCH] [cli] add Doxygen for SRP server (#9653) --- src/cli/cli_srp_client.cpp | 28 +++--- src/cli/cli_srp_server.cpp | 192 ++++++++++++++++++++++++++++++++++--- 2 files changed, 193 insertions(+), 27 deletions(-) diff --git a/src/cli/cli_srp_client.cpp b/src/cli/cli_srp_client.cpp index a153059caff..e329032585e 100644 --- a/src/cli/cli_srp_client.cpp +++ b/src/cli/cli_srp_client.cpp @@ -146,7 +146,7 @@ template <> otError SrpClient::Process(Arg aArgs[]) #endif // OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE /** - * @cli srp client callback (enable/disable, get) + * @cli srp client callback (get,enable,disable) * @code * srp client callback enable * Done @@ -196,7 +196,7 @@ template <> otError SrpClient::Process(Arg aArgs[]) OutputHostInfo(0, *otSrpClientGetHostInfo(GetInstancePtr())); } /** - * @cli srp client host name (set, get) + * @cli srp client host name (get,set) * @code * srp client host name dev4312 * Done @@ -210,7 +210,7 @@ template <> otError SrpClient::Process(Arg aArgs[]) * 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. + * Gets or sets the host name of the SRP client. * @sa otSrpClientSetHostName */ else if (aArgs[0] == "name") @@ -412,8 +412,8 @@ template <> otError SrpClient::Process(Arg aArgs[]) * @endcode * @par * Clears all host information and all services. - * @sa otSrpClientClearHostAndServices * @sa otSrpClientBuffersFreeAllServices + * @sa otSrpClientClearHostAndServices */ else if (aArgs[0] == "clear") { @@ -431,7 +431,7 @@ template <> otError SrpClient::Process(Arg aArgs[]) } /** - * @cli srp client leaseinterval (set, get) + * @cli srp client leaseinterval (get,set) * @code * srp client leaseinterval 3600 * Done @@ -443,9 +443,9 @@ template <> otError SrpClient::Process(Arg aArgs[]) * @endcode * @cparam srp client leaseinterval [@ca{interval}] * @par - * Sets or gets the lease interval in seconds. - * @sa otSrpClientSetLeaseInterval + * Gets or sets the lease interval in seconds. * @sa otSrpClientGetLeaseInterval + * @sa otSrpClientSetLeaseInterval */ template <> otError SrpClient::Process(Arg aArgs[]) { @@ -453,7 +453,7 @@ template <> otError SrpClient::Process(Arg aArgs[]) } /** - * @cli srp client keyleaseinterval (set, get) + * @cli srp client keyleaseinterval (get,set) * @code * srp client keyleaseinterval 864000 * Done @@ -465,9 +465,9 @@ template <> otError SrpClient::Process(Arg aArgs[]) * @endcode * @cparam srp client keyleaseinterval [@ca{interval}] * @par - * Sets or gets the key lease interval in seconds. - * @sa otSrpClientSetKeyLeaseInterval + * Gets or sets the key lease interval in seconds. * @sa otSrpClientGetKeyLeaseInterval + * @sa otSrpClientSetKeyLeaseInterval */ template <> otError SrpClient::Process(Arg aArgs[]) { @@ -639,7 +639,7 @@ template <> otError SrpClient::Process(Arg aArgs[]) } #if OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE /** - * @cli srp client service key (set, get) + * @cli srp client service key (get,set) * @code * srp client service key enable * Done @@ -905,7 +905,7 @@ template <> otError SrpClient::Process(Arg aArgs[]) } /** - * @cli srp client ttl (set, get) + * @cli srp client ttl (get,set) * @code * srp client ttl 3600 * Done @@ -917,9 +917,9 @@ template <> otError SrpClient::Process(Arg aArgs[]) * @endcode * @cparam srp client ttl [@ca{value}] * @par - * Sets or gets the `ttl`(time to live) value in seconds. - * @sa otSrpClientSetTtl + * Gets or sets the `ttl`(time to live) value in seconds. * @sa otSrpClientGetTtl + * @sa otSrpClientSetTtl */ template <> otError SrpClient::Process(Arg aArgs[]) { diff --git a/src/cli/cli_srp_server.cpp b/src/cli/cli_srp_server.cpp index 5a96d5fe63f..98213d5246e 100644 --- a/src/cli/cli_srp_server.cpp +++ b/src/cli/cli_srp_server.cpp @@ -43,6 +43,26 @@ namespace ot { namespace Cli { +/** + * @cli srp server addrmode (get,set) + * @code + * srp server addrmode anycast + * Done + * @endcode + * @code + * srp server addrmode + * anycast + * Done + * @endcode + * @cparam srp server addrmode [@ca{anycast}|@ca{unicast}] + * @par + * Gets or sets the address mode used by the SRP server. + * @par + * The address mode tells the SRP server how to determine its address and port number, + * which then get published in the Thread network data. + * @sa otSrpServerGetAddressMode + * @sa otSrpServerSetAddressMode + */ template <> otError SrpServer::Process(Arg aArgs[]) { otError error = OT_ERROR_INVALID_ARGS; @@ -75,32 +95,53 @@ template <> otError SrpServer::Process(Arg aArgs[]) } #if OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE + /** - * @cli srp server auto + * @cli srp server auto (enable,disable) + * @code + * srp server auto enable + * Done + * @endcode * @code * srp server auto - * Disabled + * Enabled * Done * @endcode - * @par api_copy - * #otSrpServerIsAutoEnableMode + * @cparam srp server auto [@ca{enable}|@ca{disable}] + * @par + * Enables or disables the auto-enable mode on the SRP server. + * @par + * When this mode is enabled, the Border Routing Manager controls if and when + * to enable or disable the SRP server. + * @par + * This command requires that `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` be enabled. + * @sa otSrpServerIsAutoEnableMode + * @sa otSrpServerSetAutoEnableMode */ template <> otError SrpServer::Process(Arg aArgs[]) { - /** - * @cli srp server auto enable - * @code - * srp server auto enable - * Done - * @endcode - * @par api_copy - * #otSrpServerSetAutoEnableMode - */ return Interpreter::GetInterpreter().ProcessEnableDisable(aArgs, otSrpServerIsAutoEnableMode, otSrpServerSetAutoEnableMode); } #endif +/** + * @cli srp server domain (get,set) + * @code + * srp server domain thread.service.arpa. + * Done + * @endcode + * @code + * srp server domain + * thread.service.arpa. + * Done + * @endcode + * @cparam srp server domain [@ca{domain-name}] + * @par + * Gets or sets the domain name of the SRP server. + * @sa otSrpServerGetDomain + * @sa otSrpServerSetDomain + */ template <> otError SrpServer::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -117,6 +158,23 @@ template <> otError SrpServer::Process(Arg aArgs[]) return error; } +/** + * @cli srp server state + * @code + * srp server state + * running + * Done + * @endcode + * @par + * Returns one of the following possible states of the SRP server: + * * `disabled`: The SRP server is not enabled. + * * `stopped`: The SRP server is enabled but not active due to existing + * SRP servers that are already active in the Thread network. + * The SRP server may become active when the existing + * SRP servers are no longer active within the Thread network. + * * `running`: The SRP server is active and can handle service registrations. + * @sa otSrpServerGetState + */ template <> otError SrpServer::Process(Arg aArgs[]) { static const char *const kStateStrings[] = { @@ -145,6 +203,17 @@ template <> otError SrpServer::Process(Arg aArgs[]) return OT_ERROR_NONE; } +/** + * @cli srp server (enable,disable) + * @code + * srp server disable + * Done + * @endcode + * @cparam srp server [@ca{enable}|@ca{disable}] + * @par + * Enables or disables the SRP server. + * @sa otSrpServerSetEnabled + */ template <> otError SrpServer::Process(Arg aArgs[]) { OT_UNUSED_VARIABLE(aArgs); @@ -178,6 +247,26 @@ template <> otError SrpServer::Process(Arg aArgs[]) return error; } +/** + * @cli srp server lease (get,set) + * @code + * srp server lease 1800 7200 86400 1209600 + * Done + * @endcode + * @code + * srp server lease + * min lease: 1800 + * max lease: 7200 + * min key-lease: 86400 + * max key-lease: 1209600 + * Done + * @endcode + * @cparam srp server lease [@ca{min-lease} @ca{max-lease} @ca{min-key-lease} @ca{max-key-lease}] + * @par + * Gets or sets the SRP server lease values in number of seconds. + * @sa otSrpServerGetLeaseConfig + * @sa otSrpServerSetLeaseConfig + */ template <> otError SrpServer::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -206,6 +295,24 @@ template <> otError SrpServer::Process(Arg aArgs[]) return error; } +/** + * @cli srp server host + * @code + * srp server host + * srp-api-test-1.default.service.arpa. + * deleted: false + * addresses: [fdde:ad00:beef:0:0:ff:fe00:fc10] + * srp-api-test-0.default.service.arpa. + * deleted: false + * addresses: [fdde:ad00:beef:0:0:ff:fe00:fc10] + * Done + * @endcode + * @par + * Returns information about all registered hosts. + * @sa otSrpServerGetNextHost + * @sa otSrpServerHostGetAddresses + * @sa otSrpServerHostGetFullName + */ template <> otError SrpServer::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -268,6 +375,46 @@ void SrpServer::OutputHostAddresses(const otSrpServerHost *aHost) OutputFormat("]"); } +/** + * @cli srp server service + * @code + * srp server service + * srp-api-test-1._ipps._tcp.default.service.arpa. + * deleted: false + * subtypes: (null) + * port: 49152 + * priority: 0 + * weight: 0 + * ttl: 7200 + * lease: 7200 + * key-lease: 1209600 + * TXT: [616263, xyz=585960] + * host: srp-api-test-1.default.service.arpa. + * addresses: [fdde:ad00:beef:0:0:ff:fe00:fc10] + * srp-api-test-0._ipps._tcp.default.service.arpa. + * deleted: false + * subtypes: _sub1,_sub2 + * port: 49152 + * priority: 0 + * weight: 0 + * ttl: 3600 + * lease: 3600 + * key-lease: 1209600 + * TXT: [616263, xyz=585960] + * host: srp-api-test-0.default.service.arpa. + * addresses: [fdde:ad00:beef:0:0:ff:fe00:fc10] + * Done + * @endcode + * @par + * Returns information about registered services. + * @par + * The `TXT` record is displayed + * as an array of entries. If an entry contains a key, the key is printed in + * ASCII format. The value portion is printed in hexadecimal bytes. + * @sa otSrpServerServiceGetInstanceName + * @sa otSrpServerServiceGetServiceName + * @sa otSrpServerServiceGetSubTypeServiceNameAt + */ template <> otError SrpServer::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -340,6 +487,25 @@ template <> otError SrpServer::Process(Arg aArgs[]) return error; } +/** + * @cli srp server seqnum (get,set) + * @code + * srp server seqnum 20 + * Done + * @endcode + * @code + * srp server seqnum + * 20 + * Done + * @endcode + * @cparam srp server seqnum [@ca{seqnum}] + * @par + * Gets or sets the sequence number used with the anycast address mode. + * The sequence number is included in the "DNS/SRP Service Anycast Address" + * entry that is published in the Network Data. + * @sa otSrpServerGetAnycastModeSequenceNumber + * @sa otSrpServerSetAnycastModeSequenceNumber + */ template <> otError SrpServer::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE;