tls: improve documentation

include/vlc_tls.h

@@ -75,18 +75,28 @@ vlc_tls_t *vlc_tls_SessionCreate (vlc_tls_creds_t *, int fd, const char *host,
                                   const char *const *alpn);
 
 /**
- * Shuts a TLS session down.
+ * Destroys a TLS session down.
  *
- * Shuts a TLS session down (if it was succesfully established) and releases
- * all resources. The underlying connection is preserved. Use vlc_tls_Close()
- * instead to shut it down at the same.
+ * All resources associated with the TLS session are released.
+ *
+ * If the session was established succesfully, then shutdown cleanly, the
+ * underlying socket can be reused. Otherwise, it must be closed. Either way,
+ * this function does not close the underlying socket: Use vlc_tls_Close()
+ * instead to close it at the same.
  *
  * This function is non-blocking and is not a cancellation point.
  */
 VLC_API void vlc_tls_SessionDelete (vlc_tls_t *);
 
+/**
+ * Receives data through a TLS session.
+ */
 VLC_API int vlc_tls_Read(vlc_tls_t *, void *buf, size_t len, bool waitall);
 VLC_API char *vlc_tls_GetLine(vlc_tls_t *);
+
+/**
+ * Sends data through a TLS session.
+ */
 VLC_API int vlc_tls_Write(vlc_tls_t *, const void *buf, size_t len);
 
 /**

modules/misc/gnutls.c

@@ -159,9 +159,6 @@ static ssize_t vlc_gnutls_writev (gnutls_transport_ptr_t ptr,
 }
 #endif
 
-/**
- * Sends data through a TLS session.
- */
 static ssize_t gnutls_Send (vlc_tls_t *tls, const void *buf, size_t length)
 {
     gnutls_session_t session = tls->sys;
@@ -170,10 +167,6 @@ static ssize_t gnutls_Send (vlc_tls_t *tls, const void *buf, size_t length)
     return (val < 0) ? gnutls_Error (tls, val) : val;
 }
 
-
-/**
- * Receives data through a TLS session.
- */
 static ssize_t gnutls_Recv (vlc_tls_t *tls, void *buf, size_t length)
 {
     gnutls_session_t session = tls->sys;
@@ -190,12 +183,6 @@ static int gnutls_Shutdown(vlc_tls_t *tls, bool duplex)
     return (val < 0) ? gnutls_Error(tls, val) : 0;
 }
 
-/**
- * Terminates a TLS session.
- *
- * This terminates a TLS session and releases session data.
- * The underlying socket must be closed separately.
- */
 static void gnutls_Close (vlc_tls_t *tls)
 {
     gnutls_session_t session = tls->sys;