curl_ws_recv.md: expand a little on the fragments the API delivers

Closes #16720

diff --git a/docs/libcurl/curl_ws_recv.md b/docs/libcurl/curl_ws_recv.md
index 2409335f0d87033de671137338f682bc9b5e0f2d..8c5cd55a4c3729c9a44906684556cbcc91d038ae 100644 (file)
--- a/docs/libcurl/curl_ws_recv.md
+++ b/docs/libcurl/curl_ws_recv.md
@@ -30,26 +30,26 @@ CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen,
 
 # DESCRIPTION
 
-Retrieves as much as possible of a received WebSocket frame into the
-*buffer*, but not more than *buflen* bytes. *recv* is set to the
-number of bytes actually stored.
+Retrieves as much as possible of a received WebSocket frame into the *buffer*,
+but not more than *buflen* bytes. *recv* is set to the number of bytes
+actually stored.
 
 If the function call is successful, the *meta* pointer gets set to point to a
 *const struct curl_ws_frame* that contains information about the received
 data. That struct must not be freed and its contents must not be relied upon
-anymore once another WebSocket function is called. See curl_ws_meta(3) for more
-details on that struct.
+anymore once another WebSocket function is called. See curl_ws_meta(3) for
+more details on that struct.
 
 The application must check `meta->bytesleft` to determine whether the complete
 frame has been received. If more payload is pending, the application must call
 this function again with an updated *buffer* and *buflen* to resume receiving.
-This may for example happen when the data does not fit into the provided buffer
-or when not all frame data has been delivered over the network yet.
+This may for example happen when the data does not fit into the provided
+buffer or when not all frame data has been delivered over the network yet.
 
 If the application wants to read the metadata without consuming any payload,
 it may call this function with a *buflen* of zero. Setting *buffer* to a NULL
-pointer is permitted in this case. Note that frames without payload are consumed
-by this action.
+pointer is permitted in this case. Note that frames without payload are
+consumed by this action.
 
 If the received message consists of multiple fragments, the *CURLWS_CONT* bit
 is set in all frames except the final one. The appropriate *CURLWS_TEXT* or
@@ -60,6 +60,11 @@ to correctly handle control frames (i.e. CLOSE, PING and PONG) arriving in
 between consecutive fragments of a fragmented TEXT or BINARY message. See
 curl_ws_meta(3) for more details on *CURLWS_CONT*.
 
+The WebSocket protocol consists of *messages* that can be delivered over the
+wire as one or more *frames* - but since a frame can be too large to buffer in
+memory, libcurl may need to deliver partial frames to the application.
+Fragments, or chunks, of frames.
+
 # %PROTOCOLS%
 
 # EXAMPLE