From 7b68936daf1e177b6b19682eb8bcd1d13d3f774c Mon Sep 17 00:00:00 2001
From: Kody Stribrny <89810515+kstribrnAmzn@users.noreply.github.com>
Date: Thu, 8 Feb 2024 15:45:07 -0800
Subject: [PATCH] Correct TransportRecv_t documentation (#275)

Description
-----------
Corrections highlight the non-blocking
expectations of the TransportRecv method.

Test Steps
-----------
No manual steps taken. I'm going to let the doxygen CI verify this.

Checklist:
----------
<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
- [ X ] I have tested my changes. No regression in existing tests.
  - Testing with CI
- [ X ] I have modified and/or added unit-tests to cover the code
changes in this Pull Request.
  - Not applicable

Related Issue
-----------
https://github.com/FreeRTOS/coreMQTT/issues/261

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.
---
 source/interface/transport_interface.h | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/source/interface/transport_interface.h b/source/interface/transport_interface.h
index 634885e7a..59d1720ec 100644
--- a/source/interface/transport_interface.h
+++ b/source/interface/transport_interface.h
@@ -195,14 +195,11 @@ typedef struct NetworkContext NetworkContext_t;
  * @transportcallback
  * @brief Transport interface for receiving data on the network.
  *
- * @note It is RECOMMENDED that the transport receive implementation
- * does NOT block when requested to read a single byte. A single byte
- * read request can be made by the caller to check whether there is a
- * new frame available on the network for reading.
- * However, the receive implementation MAY block for a timeout period when
- * it is requested to read more than 1 byte. This is because once the caller
- * is aware that a new frame is available to read on the network, then
- * the likelihood of reading more than one byte over the network becomes high.
+ * @note It is HIGHLY RECOMMENDED that the transport receive
+ * implementation does NOT block.
+ * coreMQTT will continue to call the transport interface if it receives
+ * a partial packet until it accumulates enough data to get the complete
+ * MQTT packet.
  *
  * @param[in] pNetworkContext Implementation-defined network context.
  * @param[in] pBuffer Buffer to receive the data into.