Document OpenSSL::SSL::SSLSocket#sync_closetopic/doc-ssl-sync-close

Add rdoc for OpenSSL::SSL::SSLSocket#sync_close, and mention it in the
example code in the rdoc for OpenSSL namespace.  [GH ruby/openssl#11]

1 files changed, 6 insertions, 0 deletions

diff --git a/ext/openssl/ossl.c b/ext/openssl/ossl.c
index 83baa7b6..1af9b247 100644
--- a/ext/openssl/ossl.c
+++ b/ext/openssl/ossl.c
@@ -1063,15 +1063,21 @@ static void Init_ossl_locks(void)
  * SSLSocket#connect must be called to initiate the SSL handshake and start
  * encryption.  A key and certificate are not required for the client socket.
  *
+ * Note that SSLSocket#close doesn't close the underlying socket by default. Set
+ * SSLSocket#sync_close to true if you want.
+ *
  *   require 'socket'
  *
  *   tcp_socket = TCPSocket.new 'localhost', 5000
  *   ssl_client = OpenSSL::SSL::SSLSocket.new tcp_socket, context
+ *   ssl_client.sync_close = true
  *   ssl_client.connect
  *
  *   ssl_client.puts "hello server!"
  *   puts ssl_client.gets
  *
+ *   ssl_client.close # shutdown the TLS connection and close tcp_socket
+ *
  * === Peer Verification
  *
  * An unverified SSL connection does not provide much security.  For enhanced