doc: add info to set timeout configs to zero when timer is dummy (#128)

source/include/core_mqtt.h

@@ -60,7 +60,7 @@ struct MQTTDeserializedInfo;
 
 /**
  * @ingroup mqtt_callback_types
- * @brief Application provided callback to retrieve the current time in
+ * @brief Application provided function to query the current time in
  * milliseconds.
  *
  * @return The current time in milliseconds.
@@ -228,12 +228,13 @@ typedef struct MQTTDeserializedInfo
  *
  * This function must be called on a #MQTTContext_t before any other function.
  *
- * @note The #MQTTGetCurrentTimeFunc_t callback function must be defined. If
+ * @note The #MQTTGetCurrentTimeFunc_t function for querying time must be defined. If
  * there is no time implementation, it is the responsibility of the application
- * to provide a dummy function to always return 0, and provide 0 timeouts for
- * all calls to #MQTT_Connect, #MQTT_ProcessLoop, and #MQTT_ReceiveLoop. This
- * will result in loop functions running for a single iteration, and #MQTT_Connect
- * relying on #MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT to receive the CONNACK packet.
+ * to provide a dummy function to always return 0, provide 0 timeouts for
+ * all calls to #MQTT_Connect, #MQTT_ProcessLoop, and #MQTT_ReceiveLoop and configure
+ * the #MQTT_RECV_POLLING_TIMEOUT_MS and #MQTT_SEND_RETRY_TIMEOUT_MS configurations
+ * to be 0. This will result in loop functions running for a single iteration, and
+ * #MQTT_Connect relying on #MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT to receive the CONNACK packet.
  *
  * @param[in] pContext The context to initialize.
  * @param[in] pTransportInterface The transport interface to use with the context.
@@ -310,8 +311,9 @@ MQTTStatus_t MQTT_Init( MQTTContext_t * pContext,
  *    The network receive for CONNACK is retried up to the number of times
  *    configured by #MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT.
  *
- * @note If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then the
- * timeout MUST be set to 0.
+ * @note If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then a
+ * timeout value of 0 MUST be passed to the API, and the #MQTT_RECV_POLLING_TIMEOUT_MS
+ * and #MQTT_SEND_RETRY_TIMEOUT_MS timeout configurations MUST be set to 0.
  *
  * @param[in] pContext Initialized MQTT context.
  * @param[in] pConnectInfo MQTT CONNECT packet information.
@@ -596,8 +598,9 @@ MQTTStatus_t MQTT_Disconnect( MQTTContext_t * pContext );
  * alive.
  *
  * @note Passing a timeout value of 0 will run the loop for a single iteration.
- * If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then this
- * timeout MUST be set to 0.
+ * If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then the timeout
+ * passed to the API MUST be 0, and the #MQTT_RECV_POLLING_TIMEOUT_MS and
+ * #MQTT_SEND_RETRY_TIMEOUT_MS timeout configurations MUST be set to 0.
  *
  * @param[in] pContext Initialized and connected MQTT context.
  * @param[in] timeoutMs Minimum time in milliseconds that the receive loop will
@@ -656,8 +659,9 @@ MQTTStatus_t MQTT_ProcessLoop( MQTTContext_t * pContext,
  * keep alive.
  *
  * @note Passing a timeout value of 0 will run the loop for a single iteration.
- * If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then this
- * timeout MUST be set to 0.
+ * If a dummy #MQTTGetCurrentTimeFunc_t was passed to #MQTT_Init, then the timeout
+ * value passed to the API MUST be 0, and the #MQTT_RECV_POLLING_TIMEOUT_MS
+ * and #MQTT_SEND_RETRY_TIMEOUT_MS timeout configurations MUST be set to 0.
  *
  * @param[in] pContext Initialized and connected MQTT context.
  * @param[in] timeoutMs Minimum time in milliseconds that the receive loop will

source/include/core_mqtt_config_defaults.h

@@ -117,9 +117,13 @@
  * may be called multiple times until all of the expected number of bytes of the
  * packet are received. This timeout represents the maximum polling duration that
  * is allowed without any data reception from the network for the incoming packet.
+ *
  * If the timeout expires, the #MQTT_ProcessLoop and #MQTT_ReceiveLoop functions
  * return #MQTTRecvFailed.
  *
+ * @note If a dummy implementation of the #MQTTGetCurrentTimeFunc_t timer function,
+ * that always returns 0, is used, then #MQTT_RECV_POLLING_TIMEOUT_MS MUST be set to 0.
+ *
  * <b>Possible values:</b> Any positive 32 bit integer. Recommended to use a
  * small timeout value. <br>
  * <b>Default value:</b> `10`
@@ -142,6 +146,9 @@
  * If the timeout expires, the #MQTT_ProcessLoop and #MQTT_ReceiveLoop functions
  * return #MQTTSendFailed.
  *
+ * @note If a dummy implementation of the #MQTTGetCurrentTimeFunc_t timer function,
+ * that always returns 0, is used, then #MQTT_SEND_RETRY_TIMEOUT_MS MUST be set to 0.
+ *
  * <b>Possible values:</b> Any positive 32 bit integer. Recommended to use a small
  * timeout value. <br>
  * <b>Default value:</b> `10`