[border-agent] update docs for set and clear ephemeral key APIs (open…

…thread#10854)

The docs are updated to mention that users can use the
`otBorderAgentDisconnect()` API to forcely disconnect from commissioner
sessions.

include/openthread/border_agent.h

@@ -187,6 +187,7 @@ otError otBorderAgentSetId(otInstance *aInstance, const otBorderAgentId *aId);
  *
  * The ephemeral key can be set when the Border Agent is already running and is not currently connected to any external
  * commissioner (i.e., it is in `OT_BORDER_AGENT_STATE_STARTED` state). Otherwise `OT_ERROR_INVALID_STATE` is returned.
+ * To terminate active commissioner sessions, use the `otBorderAgentDisconnect()` API.
  *
  * The given @p aKeyString is directly used as the ephemeral PSK (excluding the trailing null `\0` character ).
  * The @p aKeyString length must be between `OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH` and
@@ -230,7 +231,8 @@ otError otBorderAgentSetEphemeralKey(otInstance *aInstance,
  *
  * If a commissioner is connected using the ephemeral key and is currently active, calling this function does not
  * change its state. In this case the `otBorderAgentIsEphemeralKeyActive()` will continue to return `TRUE` until the
- * commissioner disconnects, or the ephemeral key timeout expires.
+ * commissioner disconnects, or the ephemeral key timeout expires. To terminate active commissioner sessions, use the
+ * `otBorderAgentDisconnect()` API.
  *
  * @param[in] aInstance    The OpenThread instance.
  */

include/openthread/instance.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (456)
+#define OPENTHREAD_API_VERSION (457)
 
 /**
  * @addtogroup api-instance

src/core/meshcop/border_agent.hpp

@@ -173,7 +173,8 @@ class BorderAgent : public InstanceLocator, private NonCopyable
      * Sets the ephemeral key for a given timeout duration.
      *
      * The ephemeral key can be set when the Border Agent is already running and is not currently connected to any
-     * external commissioner (i.e., it is in `kStateStarted` state).
+     * external commissioner (i.e., it is in `kStateStarted` state). To terminate active commissioner sessions,
+     * use the `Disconnect()` function.
      *
      * The given @p aKeyString is directly used as the ephemeral PSK (excluding the trailing null `\0` character). Its
      * length must be between `kMinEphemeralKeyLength` and `kMaxEphemeralKeyLength`, inclusive.
@@ -209,7 +210,8 @@ class BorderAgent : public InstanceLocator, private NonCopyable
      *
      * If a commissioner is connected using the ephemeral key and is currently active, calling this method does not
      * change its state. In this case the `IsEphemeralKeyActive()` will continue to return `true` until the commissioner
-     * disconnects, or the ephemeral key timeout expires.
+     * disconnects, or the ephemeral key timeout expires. To terminate active commissioner sessions, use the
+     * `Disconnect()` function.
      */
     void ClearEphemeralKey(void);