[vlc-commits] tls: improve documentation

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Sun Dec 20 23:52:48 2015 +0200| [10de5cffda0c8f3fb68fef80366b305c8f7dbcce] | committer: Rémi Denis-Courmont

tls: improve documentation

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=10de5cffda0c8f3fb68fef80366b305c8f7dbcce
---

 include/vlc_tls.h     |   18 ++++++++++++++----
 modules/misc/gnutls.c |   13 -------------
 2 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/include/vlc_tls.h b/include/vlc_tls.h
index 59647e8..1092efb 100644
--- a/include/vlc_tls.h
+++ b/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);
 
 /**
diff --git a/modules/misc/gnutls.c b/modules/misc/gnutls.c
index 1262e5a..7519629 100644
--- a/modules/misc/gnutls.c
+++ b/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;