Add even more documentation

knots/non-blocking.scm

@@ -32,6 +32,16 @@
 
 (define* (non-blocking-open-socket-for-uri uri
                                            #:key (verify-certificate? #t))
+  "Open a socket for URI and return it as a non-blocking port.
+
+For HTTPS URIs the TLS handshake is completed while the socket is
+still blocking (required because Guile's TLS wrapper does not support
+non-blocking handshakes), then the underlying socket is made
+non-blocking.  For plain HTTP the socket is made non-blocking
+immediately.
+
+@code{#:verify-certificate?} controls TLS certificate verification
+and defaults to @code{#t}."
   (define tls-wrap
     (@@ (web client) tls-wrap))