ssl: update rdoc for SSLSocket#pending and #wait_readable

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