[DOC] {read,write}_nonblock with exception: false

Update docs to reflect EOF behavior change of read_nonblock and
write_nonblock when using `exception: false`.

[Fix GH-1527]
Author:    Russell Davis <russell-stripe@users.noreply.github.com>

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@57690 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

4 files changed, 28 insertions, 15 deletions

diff --git a/ext/openssl/lib/openssl/buffering.rb b/ext/openssl/lib/openssl/buffering.rb
index b0dffefd3e..30df819715 100644
--- a/ext/openssl/lib/openssl/buffering.rb
+++ b/ext/openssl/lib/openssl/buffering.rb
@@ -166,7 +166,8 @@ module OpenSSL::Buffering
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that read_nonblock should not raise an IO::Wait*able exception, but
-  # return the symbol :wait_writable or :wait_readable instead.
+  # return the symbol :wait_writable or :wait_readable instead. At EOF, it will
+  # return nil instead of raising EOFError.
 
   def read_nonblock(maxlen, buf=nil, exception: true)
     if maxlen == 0
@@ -378,7 +379,8 @@ module OpenSSL::Buffering
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that write_nonblock should not raise an IO::Wait*able exception, but
-  # return the symbol :wait_writable or :wait_readable instead.
+  # return the symbol :wait_writable or :wait_readable instead. At EOF, it will
+  # return nil instead of raising EOFError.
 
   def write_nonblock(s, exception: true)
     flush
diff --git a/ext/openssl/ossl_ssl.c b/ext/openssl/ossl_ssl.c
index eef7dbece6..41d496ff85 100644
--- a/ext/openssl/ossl_ssl.c
+++ b/ext/openssl/ossl_ssl.c
@@ -1601,7 +1601,7 @@ ossl_ssl_connect(VALUE self)
  * By specifying `exception: false`, the options hash allows you to indicate
  * that connect_nonblock should not raise an IO::WaitReadable or
  * IO::WaitWritable exception, but return the symbol :wait_readable or
- * :wait_writable instead.
+ * :wait_writable instead. At EOF, it will return nil instead of raising EOFError.
  */
 static VALUE
 ossl_ssl_connect_nonblock(int argc, VALUE *argv, VALUE self)
@@ -1649,7 +1649,7 @@ ossl_ssl_accept(VALUE self)
  * By specifying `exception: false`, the options hash allows you to indicate
  * that accept_nonblock should not raise an IO::WaitReadable or
  * IO::WaitWritable exception, but return the symbol :wait_readable or
- * :wait_writable instead.
+ * :wait_writable instead. At EOF, it will return nil instead of raising EOFError.
  */
 static VALUE
 ossl_ssl_accept_nonblock(int argc, VALUE *argv, VALUE self)
diff --git a/ext/socket/lib/socket.rb b/ext/socket/lib/socket.rb
index 42c7edddec..b02449c8e7 100644
--- a/ext/socket/lib/socket.rb
+++ b/ext/socket/lib/socket.rb
@@ -315,7 +315,8 @@ class BasicSocket < IO
   #
   # By specifying `exception: false`, the _opts_ hash allows you to indicate
   # that sendmsg_nonblock should not raise an IO::WaitWritable exception, but
-  # return the symbol :wait_writable instead.
+  # return the symbol :wait_writable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   def sendmsg_nonblock(mesg, flags = 0, dest_sockaddr = nil, *controls,
                        exception: true)
     __sendmsg_nonblock(mesg, flags, dest_sockaddr, controls, exception)
@@ -363,7 +364,8 @@ class BasicSocket < IO
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that recv_nonblock should not raise an IO::WaitWritable exception, but
-  # return the symbol :wait_writable instead.
+  # return the symbol :wait_writable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   #
   # === See
   # * Socket#recvfrom
@@ -437,7 +439,8 @@ class BasicSocket < IO
   #
   # By specifying `exception: false`, the _opts_ hash allows you to indicate
   # that recvmsg_nonblock should not raise an IO::WaitWritable exception, but
-  # return the symbol :wait_writable instead.
+  # return the symbol :wait_writable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   def recvmsg_nonblock(dlen = nil, flags = 0, clen = nil,
                        scm_rights: false, exception: true)
     __recvmsg_nonblock(dlen, flags, clen, scm_rights, exception)
@@ -514,7 +517,8 @@ class Socket < BasicSocket
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that accept_nonblock should not raise an IO::WaitReadable exception, but
-  # return the symbol :wait_readable instead.
+  # return the symbol :wait_readable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   #
   # === See
   # * Socket#recvfrom
@@ -571,7 +575,8 @@ class Socket < BasicSocket
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that accept_nonblock should not raise an IO::WaitReadable exception, but
-  # return the symbol :wait_readable instead.
+  # return the symbol :wait_readable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   #
   # === See
   # * Socket#accept
@@ -1190,7 +1195,8 @@ class Socket < BasicSocket
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that connect_nonblock should not raise an IO::WaitWritable exception, but
-  # return the symbol :wait_writable instead.
+  # return the symbol :wait_writable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   #
   # === See
   #  # Socket#connect
@@ -1248,7 +1254,8 @@ class UDPSocket < IPSocket
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that recvmsg_nonblock should not raise an IO::WaitWritable exception, but
-  # return the symbol :wait_writable instead.
+  # return the symbol :wait_writable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   #
   # === See
   # * Socket#recvfrom
@@ -1289,7 +1296,8 @@ class TCPServer < TCPSocket
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that accept_nonblock should not raise an IO::WaitReadable exception, but
-  # return the symbol :wait_readable instead.
+  # return the symbol :wait_readable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   #
   # === See
   # * TCPServer#accept
@@ -1330,7 +1338,8 @@ class UNIXServer < UNIXSocket
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that accept_nonblock should not raise an IO::WaitReadable exception, but
-  # return the symbol :wait_readable instead.
+  # return the symbol :wait_readable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   #
   # === See
   # * UNIXServer#accept
diff --git a/prelude.rb b/prelude.rb
index 231c64e95a..5ebf1166ea 100644
--- a/prelude.rb
+++ b/prelude.rb
@@ -70,7 +70,8 @@ class IO
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that read_nonblock should not raise an IO::WaitReadable exception, but
-  # return the symbol :wait_readable instead.
+  # return the symbol :wait_readable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   def read_nonblock(len, buf = nil, exception: true)
     __read_nonblock(len, buf, exception)
   end
@@ -128,7 +129,8 @@ class IO
   #
   # By specifying `exception: false`, the options hash allows you to indicate
   # that write_nonblock should not raise an IO::WaitWritable exception, but
-  # return the symbol :wait_writable instead.
+  # return the symbol :wait_writable instead. At EOF, it will return nil instead
+  # of raising EOFError.
   def write_nonblock(buf, exception: true)
     __write_nonblock(buf, exception)
   end