From 47f557a8224a9401d72fb8b0733c4d7ffaa70e6c Mon Sep 17 00:00:00 2001
From: Abtin Keshavarzian <abtink@google.com>
Date: Mon, 15 Dec 2025 14:53:53 -0800
Subject: [PATCH] [dnssd] correct DNS upstream query cancellation documentation
 (#12210)

This commit clarifies the expected platform behavior for handling a
DNS upstream query cancellation.

The previous documentation was inconsistent. The documentation of
`otPlatDnsStartUpstreamQuery()` incorrectly stated that the platform
must not call `otPlatDnsUpstreamQueryDone()` on a cancelled
transaction, while the opposite was mentioned in
`otPlatDnsCancelUpstreamQuery()`.

This is now corrected to state that the platform MUST always invoke
the `otPlatDnsUpstreamQueryDone()` callback for every
`otPlatDnsStartUpstreamQuery()`, even if the query is cancelled using
`otPlatDnsCancelUpstreamQuery()`.
---
 include/openthread/instance.h     |  2 +-
 include/openthread/platform/dns.h | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/include/openthread/instance.h b/include/openthread/instance.h
index 4ad0ac418..360f76523 100644
--- a/include/openthread/instance.h
+++ b/include/openthread/instance.h
@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (560)
+#define OPENTHREAD_API_VERSION (561)
 
 /**
  * @addtogroup api-instance
diff --git a/include/openthread/platform/dns.h b/include/openthread/platform/dns.h
index e15f222e4..594fd7895 100644
--- a/include/openthread/platform/dns.h
+++ b/include/openthread/platform/dns.h
@@ -80,9 +80,9 @@ bool otPlatDnsIsUpstreamQueryAvailable(otInstance *aInstance);
  *
  * - In success case (and errors represented by DNS protocol messages), the platform is expected to call
  *   `otPlatDnsUpstreamQueryDone`.
- * - The OpenThread core may cancel a (possibly timeout) query transaction by calling
- *   `otPlatDnsCancelUpstreamQuery`, the platform must not call `otPlatDnsUpstreamQueryDone` on a
- *   cancelled transaction.
+ * - The OpenThread core may cancel a query transaction (possibly due to a timeout) by invoking
+ *   `otPlatDnsCancelUpstreamQuery()`. The platform MUST still call `otPlatDnsUpstreamQueryDone()` on a
+ *   cancelled transaction to release the transaction.
  *
  * @param[in] aInstance  The OpenThread instance structure.
  * @param[in] aTxn       A pointer to the opaque DNS query transaction object.
@@ -93,7 +93,7 @@ void otPlatDnsStartUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery *
 /**
  * Cancels a transaction of upstream query.
  *
- * The platform must call `otPlatDnsUpstreamQueryDone` to release the resources.
+ * The platform MUST call `otPlatDnsUpstreamQueryDone()` to release the transaction.
  *
  * @param[in] aInstance  The OpenThread instance structure.
  * @param[in] aTxn       A pointer to the opaque DNS query transaction object.
@@ -103,7 +103,7 @@ void otPlatDnsCancelUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery
 /**
  * The platform calls this function to finish DNS query.
  *
- * The transaction will be released, so the platform must not call on the same transaction twice. This function passes
+ * The transaction will be released, so the platform MUST NOT call on the same transaction twice. This function passes
  * the ownership of `aResponse` to OpenThread stack.
  *
  * Platform can pass NULL to close a transaction without a response.