update rdoc and NEWS.

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

NEWS

@@ -34,6 +34,10 @@ with all sufficient information, see the ChangeLog file.
     * extended methods:
       * IO.pipe can take a block.
 
+    * new modules:
+      * IO::WaitReadable
+      * IO::WaitWritable
+
   * Process
     * extended methods:
       * Process.spawn accepts [:child, FD] for a redirect target.

ext/.document

@@ -8,6 +8,37 @@ iconv/iconv.c
 io/wait/wait.c
 nkf/lib/kconv.rb
 nkf/nkf.c
+openssl/ossl.c
+openssl/ossl_asn1.c
+openssl/ossl_bn.c
+openssl/ossl_cipher.c
+openssl/ossl_config.c
+openssl/ossl_digest.c
+openssl/ossl_engine.c
+openssl/ossl_hmac.c
+openssl/ossl_ns_spki.c
+openssl/ossl_ocsp.c
+openssl/ossl_pkcs5.c
+openssl/ossl_pkcs7.c
+openssl/ossl_pkcs12.c
+openssl/ossl_pkey.c
+openssl/ossl_pkey_dh.c
+openssl/ossl_pkey_dsa.c
+openssl/ossl_pkey_ec.c
+openssl/ossl_pkey_rsa.c
+openssl/ossl_rand.c
+openssl/ossl_ssl.c
+openssl/ossl_ssl_session.c
+openssl/ossl_x509.c
+openssl/ossl_x509attr.c
+openssl/ossl_x509cert.c
+openssl/ossl_x509crl.c
+openssl/ossl_x509ext.c
+openssl/ossl_x509name.c
+openssl/ossl_x509req.c
+openssl/ossl_x509revoked.c
+openssl/ossl_x509store.c
+openssl/lib/openssl/buffering.rb
 readline/readline.c
 socket/init.c
 socket/raddrinfo.c

ext/openssl/lib/openssl/buffering.rb

@@ -100,6 +100,37 @@ module Buffering
     ret
   end
 
+  # Reads at most _maxlen_ bytes in the non-blocking manner.
+  #
+  # When no data can be read without blocking,
+  # It raises OpenSSL::SSL::SSLError extended by
+  # IO::WaitReadable or IO::WaitWritable.
+  #
+  # IO::WaitReadable means SSL needs to read internally.
+  # So read_nonblock should be called again after
+  # underlying IO is readable.
+  #
+  # IO::WaitWritable means SSL needs to write internally.
+  # So read_nonblock should be called again after
+  # underlying IO is writable.
+  #
+  # So OpenSSL::Buffering#read_nonblock needs two rescue clause as follows.
+  # 
+  #  begin
+  #    result = ssl.read_nonblock(maxlen)
+  #  rescue IO::WaitReadable
+  #    IO.select([io])
+  #    retry
+  #  rescue IO::WaitWritable
+  #    IO.select(nil, [io])
+  #    retry
+  #  end
+  #
+  # Note that one reason that read_nonblock write to a underlying IO
+  # is the peer requests a new TLS/SSL handshake.
+  # See openssl FAQ for more details.
+  # http://www.openssl.org/support/faq.html
+  #
   def read_nonblock(maxlen, buf=nil)
     if maxlen == 0
       if buf