[coap] reduce OT_COAP_MAX_RETRANSMIT to 20 (#5338)

Also add a note to clarify the set of valid CoAP transmission
parameters.

include/openthread/coap.h

@@ -60,7 +60,7 @@ extern "C" {
 
 #define OT_COAP_MAX_TOKEN_LENGTH 8 ///< Max token length as specified (RFC 7252).
 
-#define OT_COAP_MAX_RETRANSMIT 30 ///< Max retransmit supported by OpenThread.
+#define OT_COAP_MAX_RETRANSMIT 20 ///< Max retransmit supported by OpenThread.
 
 #define OT_COAP_MIN_ACK_TIMEOUT 1000 ///< Minimal ACK timeout in milliseconds supported by OpenThread.
 
@@ -368,6 +368,10 @@ typedef struct otCoapResource
 /**
  * This structure represents the CoAP transmission parameters.
  *
+ * @note mAckTimeout * ((2 ** (mMaxRetransmit + 1)) - 1) * (mAckRandomFactorNumerator / mAckRandomFactorDenominator)
+ *       must not exceed what can be represented by a uint32_t (0xffffffff). This limitation allows OpenThread to
+ *       avoid 64-bit arithmetic.
+ *
  */
 typedef struct otCoapTxParameters
 {

include/openthread/instance.h

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