Detailed docs on Socket.Read* and NetworkStream.Receive* return values (#10983)

The wording is mostly borrowed from the `Stream.Read*` variants but saying `the peer socket performed a graceful shutdown` instead of `end of the stream has been reached`, which describes the EOF reason more specifically in this case.

---------

Co-authored-by: Genevieve Warren <[email protected]>

Author: antonfirsov

xml/System.Net.Sockets/NetworkStream.xml

@@ -1107,7 +1107,7 @@ The Close method frees both unmanaged and managed resources associated with the
       <Docs>
         <param name="asyncResult">An <see cref="T:System.IAsyncResult" /> that represents an asynchronous call.</param>
         <summary>Handles the end of an asynchronous read.</summary>
-        <returns>The number of bytes read from the <see cref="T:System.Net.Sockets.NetworkStream" />.</returns>
+        <returns>The number of bytes read from the <see cref="T:System.Net.Sockets.NetworkStream" />, between zero (0) and the number of bytes requested. The method returns zero (0) only if zero bytes were requested or if no more bytes are available because the peer socket performed a graceful shutdown. If zero bytes are requested, read operations might complete immediately or might not complete until at least one byte is available (but without consuming any data).</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -1466,7 +1466,7 @@ The Close method frees both unmanaged and managed resources associated with the
       <Docs>
         <param name="buffer">A region of memory to store data read from the <see cref="T:System.Net.Sockets.NetworkStream" />.</param>
         <summary>Reads data from the <see cref="T:System.Net.Sockets.NetworkStream" /> and stores it to a span of bytes in memory.</summary>
-        <returns>The number of bytes read from the <see cref="T:System.Net.Sockets.NetworkStream" />.</returns>
+        <returns>The total number of bytes read into the buffer, between zero (0) and the length of the buffer. The method returns zero (0) only if zero bytes were requested or if no more bytes are available because the peer socket performed a graceful shutdown.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -1543,7 +1543,7 @@ There is a failure reading from the network.</exception>
         <param name="size">The number of bytes to read from the <see cref="T:System.Net.Sockets.NetworkStream" />.</param>
         <param name="count">The number of bytes to read from the <see cref="T:System.Net.Sockets.NetworkStream" />.</param>
         <summary>Reads data from the <see cref="T:System.Net.Sockets.NetworkStream" /> and stores it to a byte array.</summary>
-        <returns>The number of bytes read from the <see cref="T:System.Net.Sockets.NetworkStream" />.</returns>
+        <returns>The total number of bytes read into the buffer between zero (0) and the requested count. The method returns zero (0) only if zero bytes were requested or if no more bytes are available because the peer socket performed a graceful shutdown.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -1695,7 +1695,7 @@ There is a failure reading from the network.</exception>
         <param name="buffer">The buffer to write the data to.</param>
         <param name="cancellationToken">The token to monitor for cancellation requests.</param>
         <summary>Reads data from the <see cref="T:System.Net.Sockets.NetworkStream" /> and stores it in a byte memory range as an asynchronous operation.</summary>
-        <returns>A <see cref="T:System.Threading.Tasks.ValueTask`1" /> that represents the asynchronous read operation. The value of its <see cref="P:System.Threading.Tasks.ValueTask`1.Result" /> property contains the total number of bytes read into <paramref name="buffer" />.</returns>
+        <returns>A <see cref="T:System.Threading.Tasks.ValueTask`1" /> that represents the asynchronous read operation. The value of its <see cref="P:System.Threading.Tasks.ValueTask`1.Result" /> property contains the total number of bytes read into <paramref name="buffer" /> between zero (0) and the number of bytes requested. The result value is zero (0) only if zero bytes were requested or if no more bytes are available because the peer socket performed a graceful shutdown. If zero bytes are requested, read operations may complete immediately or may not complete until at least one byte is available (but without consuming any data).</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -1766,7 +1766,7 @@ There is a failure reading from the network.</exception>
         <param name="count">The number of bytes to read from the <see cref="T:System.Net.Sockets.NetworkStream" />.</param>
         <param name="cancellationToken">The token to monitor for cancellation requests.</param>
         <summary>Reads data from the <see cref="T:System.Net.Sockets.NetworkStream" /> and stores it to a specified range of a byte array as an asynchronous operation.</summary>
-        <returns>A task that represents the asynchronous read operation. The value of its <see cref="P:System.Threading.Tasks.Task`1.Result" /> property contains the total number of bytes read into <paramref name="buffer" />.</returns>
+        <returns>A task that represents the asynchronous read operation. The value of its <see cref="P:System.Threading.Tasks.Task`1.Result" /> property contains the total number of bytes read into <paramref name="buffer" /> between zero (0) and the number of bytes requested. The result value is zero (0) only if zero bytes were requested or if no more bytes are available because the peer socket performed a graceful shutdown. If zero bytes are requested, read operations may complete immediately or may not complete until at least one byte is available (but without consuming any data).</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -1821,7 +1821,7 @@ There is a failure reading from the network.</exception>
       <Parameters />
       <Docs>
         <summary>Reads a byte from the <see cref="T:System.Net.Sockets.NetworkStream" /> and advances the position within the stream by one byte, or returns -1 if at the end of the stream.</summary>
-        <returns>The unsigned byte cast to an <see cref="T:System.Int32" />, or -1 if at the end of the stream.</returns>
+        <returns>The unsigned byte cast to an <see cref="T:System.Int32" />, or -1 if at the end of the stream because the peer socket performed a graceful shutdown.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[