[dns-client] update API docs (#8962)
This commit updates `otDnsClient` API documentation making the service
resolution `otDnsClientResolveService()` behavior more clear, in
particular that it sends queries for SRV/TXT records. The new
documents also highlight how records in Additional Data section
in a query response is parsed and provided in the callbacks and that
servers/resolvers may not provide the records.
diff --git a/include/openthread/dns_client.h b/include/openthread/dns_client.h
index 87ed2ba..c790bc1 100644
--- a/include/openthread/dns_client.h
+++ b/include/openthread/dns_client.h
@@ -434,9 +434,9 @@
*
* This function MUST only be used from `otDnsBrowseCallback`.
*
- * A browse DNS response should include the SRV, TXT, and AAAA records for the service instances that are enumerated
- * (note that it is a SHOULD and not a MUST requirement). This function tries to retrieve this info for a given service
- * instance when available.
+ * A browse DNS response can include SRV, TXT, and AAAA records for the service instances that are enumerated. This is
+ * a SHOULD and not a MUST requirement, and servers/resolvers are not required to provide this. This function attempts
+ * to retrieve this info for a given service instance when available.
*
* - If no matching SRV record is found in @p aResponse, `OT_ERROR_NOT_FOUND` is returned. In this case, no additional
* records (no TXT and/or AAAA) are read.
@@ -523,6 +523,18 @@
* the config for this query. In a non-NULL @p aConfig, some of the fields can be left unspecified (value zero). The
* unspecified fields are then replaced by the values from the default config.
*
+ * The function sends queries for SRV and/or TXT records for the given service instance. The `mServiceMode` field in
+ * `otDnsQueryConfig` determines which records to query (SRV only, TXT only, or both SRV and TXT) and how to perform
+ * the query (together in the same message, separately in parallel, or in optimized mode where client will try in the
+ * same message first and then separately if it fails to get a response).
+ *
+ * The SRV record provides information about service port, priority, and weight along with the host name associated
+ * with the service instance. This function DOES NOT perform address resolution for the host name discovered from SRV
+ * record. The server/resolver may provide AAAA/A record(s) for the host name in the Additional Data section of the
+ * response to SRV/TXT query and this information can be retrieved using `otDnsServiceResponseGetServiceInfo()` in
+ * `otDnsServiceCallback`. Users of this API MUST NOT assume that host address will always be available from
+ * `otDnsServiceResponseGetServiceInfo()`.
+ *
* @param[in] aInstance A pointer to an OpenThread instance.
* @param[in] aInstanceLabel The service instance label.
* @param[in] aServiceName The service name (together with @p aInstanceLabel form full instance name).
@@ -569,6 +581,12 @@
*
* This function MUST only be used from `otDnsServiceCallback`.
*
+ * A service resolution DNS response may include AAAA records in its Additional Data section for host name associated
+ * with the service instance that is resolved. This is a SHOULD and not a MUST requirement so servers/resolvers are
+ * not required to provide this. This function attempts to retrieve AAAA record(s) if included in the response. If it
+ * is not included `mHostAddress` is set to all zero (unspecified address). If the caller wants to resolve the host
+ * address it can call `otDnsClientResolveAddress()` with the host name to start an address resolution query.
+ *
* - If a matching SRV record is found in @p aResponse, @p aServiceInfo is updated.
* - If no matching SRV record is found, `OT_ERROR_NOT_FOUND` is returned unless the query config for this query
* used `OT_DNS_SERVICE_MODE_TXT` for `mServiceMode` (meaning the request was only for TXT record). In this case, we
diff --git a/include/openthread/instance.h b/include/openthread/instance.h
index b6bb248..54343a1 100644
--- a/include/openthread/instance.h
+++ b/include/openthread/instance.h
@@ -53,7 +53,7 @@
* @note This number versions both OpenThread platform and user APIs.
*
*/
-#define OPENTHREAD_API_VERSION (313)
+#define OPENTHREAD_API_VERSION (314)
/**
* @addtogroup api-instance
