From 21c10deb917120d1748f40141ad1abca86353f39 Mon Sep 17 00:00:00 2001
From: Alexandre Janniaux <ajanni@videolabs.io>
Date: Thu, 6 Jul 2023 09:33:58 +0200
Subject: [PATCH] vlc_tls: fix doxygen warnings

    include/vlc_tls.h:304: warning: The following parameter of
    vlc_tls_GetPollFD(vlc_tls_t *tls, short *events) is not documented:
        parameter 'tls'

    include/vlc_tls.h:335: warning: The following parameter of
    vlc_tls_Read(vlc_tls_t *session, void *buf, size_t len, bool waitall) is not documented:
        parameter 'session'

    include/vlc_tls.h:365: warning: The following parameter of
    vlc_tls_Shutdown(vlc_tls_t *tls, bool duplex) is not documented:
        parameter 'tls'

    include/vlc_tls.h:176: warning: argument 'hostname' of command @param is not found in the argument list of vlc_tls_ClientSessionCreate(vlc_tls_client_t *creds, vlc_tls_t *sock, const char *host, const char *service, const char *const *alpn, char **alp)

    include/vlc_tls.h:176: warning: The following parameter of vlc_tls_ClientSessionCreate(vlc_tls_client_t *creds, vlc_tls_t *sock, const char *host, const char *service, const char *const *alpn, char **alp) is not documented:
      parameter 'host'

    include/vlc_tls.h:237: warning: The following parameter of vlc_tls_ServerCreate(vlc_object_t *obj, const char *cert, const char *key) is not documented:
      parameter 'obj'

    include/vlc_tls.h:256: warning: The following parameter of vlc_tls_ServerSessionCreate(vlc_tls_server_t *creds, vlc_tls_t *sock, const char *const *alpn) is not documented:
      parameter 'sock'
---
 include/vlc_tls.h | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/include/vlc_tls.h b/include/vlc_tls.h
index 4f3ec00cc7..622a3ab9b6 100644
--- a/include/vlc_tls.h
+++ b/include/vlc_tls.h
@@ -195,7 +195,7 @@ VLC_API void vlc_tls_ClientDelete(vlc_tls_client_t *);
  **/
 VLC_API vlc_tls_t *vlc_tls_ClientSessionCreate(vlc_tls_client_t *creds,
                                                vlc_tls_t *sock,
-                                               const char *host,
+                                               const char *hostname,
                                                const char *service,
                                                const char *const *alpn,
                                                char **alp);
@@ -233,13 +233,14 @@ struct vlc_tls_server_operations
 /**
  * Allocates server TLS credentials.
  *
+ * @param tls the TLS stream object
  * @param cert path to an x509 certificate (required)
  * @param key path to the PKCS private key for the certificate,
  *            or NULL to use cert path
  *
  * @return TLS credentials object, or NULL on error.
  */
-VLC_API vlc_tls_server_t *vlc_tls_ServerCreate(vlc_object_t *,
+VLC_API vlc_tls_server_t *vlc_tls_ServerCreate(vlc_object_t *tls,
                                                const char *cert,
                                                const char *key);
 
@@ -263,6 +264,7 @@ static inline int vlc_tls_SessionHandshake(vlc_tls_server_t *crd,
  * This function is non-blocking and is not a cancellation point.
  *
  * @param creds server credentials, i.e. keys pair and X.509 certificates chain
+ * @param sock the TLS stream object
  * @param alpn NULL-terminated list of Application Layer Protocols
  *             to negotiate, or NULL to not negotiate protocols
  *
@@ -306,6 +308,7 @@ VLC_API void vlc_tls_SessionDelete (vlc_tls_t *);
  * This function is necessary both for receiving and sending data, therefore
  * it is reentrant. It is not a cancellation point.
  *
+ * @param tls the TLS stream object
  * @param events a pointer to a mask of poll events (e.g. POLLIN, POLLOUT)
  *               [IN/OUT]
  * @return the file descriptor to poll
@@ -333,6 +336,7 @@ static inline int vlc_tls_GetFD(vlc_tls_t *tls)
  *
  * This dequeues incoming data from a transport layer socket.
  *
+ * @param tls the TLS stream object
  * @param buf received buffer start address [OUT]
  * @param len buffer length (in bytes)
  * @param waitall whether to wait for the exact buffer length (true),
@@ -343,7 +347,7 @@ static inline int vlc_tls_GetFD(vlc_tls_t *tls)
  *
  * @return the number of bytes actually dequeued, or -1 on error.
  */
-VLC_API ssize_t vlc_tls_Read(vlc_tls_t *, void *buf, size_t len, bool waitall);
+VLC_API ssize_t vlc_tls_Read(vlc_tls_t *tls, void *buf, size_t len, bool waitall);
 
 /**
  * Receives a text line through a socket.
@@ -370,6 +374,7 @@ VLC_API ssize_t vlc_tls_Write(vlc_tls_t *, const void *buf, size_t len);
  * Data can still be received until a close notification is received from the
  * other end.
  *
+ * @param tls the TLS stream object
  * @param duplex whether to stop receiving data as well
  * @retval 0 the session was terminated securely and cleanly
  *           (the underlying socket can be reused for other purposes)