improve upgrade documentation to clarify what the application can or cannot do on the socket

doc/libmicrohttpd.texi

@@ -2116,8 +2116,9 @@ Create a response suitable for switching protocols.  Returns @code{MHD_YES} on s
 
 When creating this type of response, the ``Connection: Upgrade''
 header will be set automatically for you.  MHD requires that you
-additionally set a ``Upgrade:'' header.  The ``Upgrade'' header
-must simply exist, which value is used is up to the application.
+additionally set an ``Upgrade:'' header.  The ``Upgrade'' header
+must simply exist, the specific value is completely up to the
+application.
 
 @end deftypefun
 
@@ -2143,10 +2144,10 @@ buffer of bytes MHD read ``by accident'' from the socket already.  This can happ
 number of bytes in @code{extra_in}
 
 @item sock
-the socket which the application can now use directly for some bi-directional communication with the client
+the socket which the application can now use directly for some bi-directional communication with the client. The application can henceforth use @code{recv()} and @code{send()} or @code{read()} and @code{write()} system calls on the socket.  However, @code{ioctl()} and @code{setsockopt()} functions will not work as expected when using HTTPS.  Such operations may be supported in the future via @code{MHD_upgrade_action}.   Most importantly, the application must never call @code{close()} on this socket.  Closing the socket must be done using @code{MHD_upgrade_action}.  However, while close is forbidden, the application may call @code{shutdown()} on the socket.
 
 @item urh
-argument for calls to @code{MHD_upgrade_action}.  Applications must eventually use this function to perform the close() action on the socket.
+argument for calls to @code{MHD_upgrade_action}.  Applications must eventually use this function to perform the @code{close()} action on the socket.
 @end table
 
 @end deftypefn

src/include/microhttpd.h

@@ -2341,10 +2341,13 @@ MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh,
  *        that is directly connected to the client and thus certain
  *        operations (TCP-specific setsockopt(), getsockopt(), etc.)
  *        may not work as expected (as the socket could be from a
- *        socketpair() or a TCP-loopback)
+ *        socketpair() or a TCP-loopback).  The application is expected
+ *        to perform read()/recv() and write()/send() calls on the socket.
+ *        The application may also call shutdown(), but must not call
+ *        close() directly.
  * @param urh argument for #MHD_upgrade_action()s on this @a connection.
- *        Applications must eventually use this callback to perform the
- *        close() action on the @a sock.
+ *        Applications must eventually use this callback to (indirectly)
+ *        perform the close() action on the @a sock.
  */
 typedef void
 (*MHD_UpgradeHandler)(void *cls,
@@ -2381,7 +2384,7 @@ typedef void
  * information and then be used any number of times (as long as the
  * header information is not connection-specific).
  *
- * @param upgrade_handler function to call with the 'upgraded' socket
+ * @param upgrade_handler function to call with the "upgraded" socket
  * @param upgrade_handler_cls closure for @a upgrade_handler
  * @return NULL on error (i.e. invalid arguments, out of memory)
  */