doc: update socket.bufferSize text

Edit text for clarity and readability.

PR-URL: https://github.com/nodejs/node/pull/30723
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 6 insertions, 8 deletions

diff --git a/doc/api/net.md b/doc/api/net.md
index 9bc9812d7c..7ec75e358f 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -548,19 +548,17 @@ added: v0.3.8
 
 * {integer}
 
+This property shows the number of characters buffered for writing. The buffer
+may contain strings whose length after encoding is not yet known. So this number
+is only an approximation of the number of bytes in the buffer.
+
 `net.Socket` has the property that `socket.write()` always works. This is to
 help users get up and running quickly. The computer cannot always keep up
 with the amount of data that is written to a socket. The network connection
 simply might be too slow. Node.js will internally queue up the data written to a
-socket and send it out over the wire when it is possible. (Internally it is
-polling on the socket's file descriptor for being writable).
-
-The consequence of this internal buffering is that memory may grow. This
-property shows the number of characters currently buffered to be written.
-(Number of characters is approximately equal to the number of bytes to be
-written, but the buffer may contain strings, and the strings are lazily
-encoded, so the exact number of bytes is not known.)
+socket and send it out over the wire when it is possible.
 
+The consequence of this internal buffering is that memory may grow.
 Users who experience large or growing `bufferSize` should attempt to
 "throttle" the data flows in their program with
 [`socket.pause()`][] and [`socket.resume()`][].