ssl: update rdoc for SSLSocket#pending and #wait_readable

Clarify how they (do not) interact with read buffers.

SSLSocket#pending corresponds to SSL_pending(). It reports data that is
already processed and is immediately available to read from the OpenSSL
library's internal buffer.

SSLSocket#wait_readable does not check for buffered data, either in the
OpenSSL library or in OpenSSL::Buffering, so it may block even when
data is already available to read.

This is different from IO#wait_readable. I considered changing
SSLSocket#wait_readable to check these buffers, but rejected it because
it is also used when the caller specifically needs to wait for new
records from the peer, particularly after SSLSocket#write_nonblock
returns :wait_readable.

Author: rhenium

ext/openssl/ossl_ssl.c

@@ -2440,7 +2440,14 @@ ossl_ssl_get_state(VALUE self)
  * call-seq:
  *    ssl.pending => Integer
  *
- * The number of bytes that are immediately available for reading.
+ * Returns the number of bytes buffered by the OpenSSL library and immediately
+ * available for reading with #sysread.
+ *
+ * This does not include data read ahead and buffered by SSLSocket. It may
+ * therefore return 0 even when data is available for reading with methods
+ * that are aware of the SSLSocket buffer, such as #read or #gets.
+ *
+ * See also the man page SSL_pending(3).
  */
 static VALUE
 ossl_ssl_pending(VALUE self)

lib/openssl/ssl.rb

@@ -223,14 +223,23 @@ def close_on_exec?
         to_io.close_on_exec?
       end
 
+      # Calls IO#wait on the underlying socket.
+      #
+      # Note that this method may block even when there is data immediately
+      # available to read, unlike IO#wait_readable.
       def wait(*args)
         to_io.wait(*args)
       end
 
+      # Calls IO#wait_readable on the underlying socket.
+      #
+      # Note that this method may block even when there is data immediately
+      # available to read, unlike IO#wait_readable.
       def wait_readable(*args)
         to_io.wait_readable(*args)
       end
 
+      # Calls IO#wait_writable on the underlying socket.
       def wait_writable(*args)
         to_io.wait_writable(*args)
       end