Clarify socket_write() (#4474)

The note was not parseable for me, and the use of "buffer" for both the
network buffers and the input data (in the same sentence) made it too
confusing for me to interpret initially.

reference/sockets/functions/socket-write.xml

@@ -46,8 +46,8 @@
       <para>
        The optional parameter <parameter>length</parameter> can specify an
        alternate length of bytes written to the socket. If this length is
-       greater than the buffer length, it is silently truncated to the length
-       of the buffer.
+       greater than <parameter>data</parameter>'s length,
+       it is silently truncated to the length of <parameter>data</parameter>.
       </para>
      </listitem>
     </varlistentry>
@@ -102,10 +102,11 @@
   <note>
    <para>
     <function>socket_write</function> does not necessarily write all bytes
-    from the given buffer. It's valid that, depending on the network
+    from <parameter>data</parameter>. It's valid that, depending on the network
     buffers etc., only a certain amount of data, even one byte, is written
-    though your buffer is greater. You have to watch out so you don't
-    unintentionally forget to transmit the rest of your data.
+    despite <parameter>data</parameter> being longer.
+    A loop must be used to ensure that the rest of <parameter>data</parameter>
+    is transmitted.
    </para>
   </note>
  </refsect1>