curl_ws_meta.md: polish and better vocabulary

Assisted-by: Hendrik Hübner
Closes #22233

diff --git a/docs/libcurl/curl_ws_meta.md b/docs/libcurl/curl_ws_meta.md
index 978520afd8d028dbd92faf9d8e3b14cf052ac404..7fb2551a5ed3f3312ceb02185572924e0cc074ed 100644 (file)
--- a/docs/libcurl/curl_ws_meta.md
+++ b/docs/libcurl/curl_ws_meta.md
@@ -29,9 +29,9 @@ const struct curl_ws_frame *curl_ws_meta(CURL *curl);
 
 # DESCRIPTION
 
-When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on
-received WebSocket traffic, curl_ws_meta(3) can be called from within
-the callback to provide additional information about the current frame.
+When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on received
+WebSocket traffic, curl_ws_meta(3) can be called from within the callback to
+provide additional information about the current frame.
 
 This function only works from within the callback, and only when receiving
 WebSocket data.
@@ -41,6 +41,14 @@ what transfer the question is about, but as there is no such pointer provided
 to the callback by libcurl itself, applications that want to use
 curl_ws_meta(3) need to pass it on to the callback on its own.
 
+WebSocket messages are split into *frames*. A WebSocket message can be made up
+of an arbitrary number of frames. Each WebSocket frame payload can be up to
+2^63-1 bytes. When libcurl delivers WebSocket data, it splits each frame into
+*chunks*; each chunk is therefore part of a frame, or at most a full frame.
+
+Each callback delivers data for a single chunk that is then part of a single
+frame.
+
 # struct curl_ws_frame
 
 ~~~c
@@ -64,13 +72,15 @@ See the list below.
 
 ## `offset`
 
-When this chunk is a continuation of frame data already delivered, this is
-the offset into the final frame data where this piece belongs to.
+When this chunk is a continuation of frame data already delivered in a
+previous callback, this is the offset into the complete frame payload where
+this chunk's data belongs.
 
 ## `bytesleft`
 
-If this is not a complete fragment, the *bytesleft* field informs about how
-many additional bytes are expected to arrive before this fragment is complete.
+When this is not a complete frame nor the last chunk for a frame, the
+*bytesleft* field informs about how many additional bytes are expected to
+arrive before this frame is complete.
 
 ## `len`
 
@@ -118,12 +128,12 @@ libcurl does not verify that the payload is valid UTF-8.
 
 Can only occur in conjunction with CURLWS_TEXT or CURLWS_BINARY.
 
-This is not the final fragment of the message, it implies that there is
-another fragment coming as part of the same message. The application must
-reassemble the fragments to receive the complete message.
+This is not the final *frame* of the message, it implies that there is another
+*frame* coming as part of the same message. The application must reassemble
+the frames to receive the complete message.
 
-Only a single fragmented message can be transmitted at a time, but it may
-be interrupted by CURLWS_CLOSE, CURLWS_PING or CURLWS_PONG frames.
+Only a single multi-frame message can be transmitted at a time, but it may be
+interrupted by CURLWS_CLOSE, CURLWS_PING or CURLWS_PONG frames.
 
 # %PROTOCOLS%