diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c
index 09c837cc97052f0604e8fb3a10e5bd5c0aa0f362..7b9228fdfc27becf6b694da932508e1ae7bb5d4b 100644
--- a/ssl/ssl_lib.c
+++ b/ssl/ssl_lib.c
@@ -657,6 +657,12 @@ int SSL_write(SSL *s,const char *buf,int num)
 
 int SSL_shutdown(SSL *s)
 	{
+	/* Note that this function behaves different from what one might
+	 * expect.  Return values are 0 for no success (yet),
+	 * 1 for success; but calling it once is usually not enough,
+	 * even if blocking I/O is used (see ssl3_shutdown).
+	 */
+
 	if (s->handshake_func == 0)
 		{
 		SSLerr(SSL_F_SSL_SHUTDOWN, SSL_R_UNINITIALIZED);