documented behaviour of recv on bufferd socket (#12374)

1 files changed, 18 insertions, 0 deletions

diff --git a/lib/pure/net.nim b/lib/pure/net.nim
index 9f8c8bc5a..878665690 100644
--- a/lib/pure/net.nim
+++ b/lib/pure/net.nim
@@ -1143,6 +1143,15 @@ proc recv*(socket: Socket, data: var string, size: int, timeout = -1,
            flags = {SocketFlag.SafeDisconn}): int =
   ## Higher-level version of ``recv``.
   ##
+  ## Reads **up to** ``size`` bytes from ``socket`` into ``buf``.
+  ##
+  ## For buffered sockets this function will attempt to read all the requested
+  ## data. It will read this data in ``BufferSize`` chunks.
+  ##
+  ## For unbuffered sockets this function makes no effort to read
+  ## all the data requested. It will return as much data as the operating system
+  ## gives it.
+  ##
   ## When 0 is returned the socket's connection has been closed.
   ##
   ## This function will throw an OSError exception when an error occurs. A value
@@ -1171,6 +1180,15 @@ proc recv*(socket: Socket, size: int, timeout = -1,
            flags = {SocketFlag.SafeDisconn}): string {.inline.} =
   ## Higher-level version of ``recv`` which returns a string.
   ##
+  ## Reads **up to** ``size`` bytes from ``socket`` into ``buf``.
+  ##
+  ## For buffered sockets this function will attempt to read all the requested
+  ## data. It will read this data in ``BufferSize`` chunks.
+  ##
+  ## For unbuffered sockets this function makes no effort to read
+  ## all the data requested. It will return as much data as the operating system
+  ## gives it.
+  ##
   ## When ``""`` is returned the socket's connection has been closed.
   ##
   ## This function will throw an OSError exception when an error occurs.