[PATCH v1 14/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/tlshd.h

[Chuck Lever <cel@kernel.org>]

From: Chuck Lever <chuck.lever@oracle.com>

I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in tlshd.h to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
---
 src/tlshd/tlshd.h | 78 ++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 61 insertions(+), 17 deletions(-)

diff --git a/src/tlshd/tlshd.h b/src/tlshd/tlshd.h
index 7f3ec40add4c..5d8965be322c 100644
--- a/src/tlshd/tlshd.h
+++ b/src/tlshd/tlshd.h
@@ -1,6 +1,9 @@
+/**
+ * @file tlshd.h
+ * @brief Generic definitions and forward declarations for tlshd
+ */
+
 /*
- * Generic definitions and forward declarations for tlshd.
- *
  * ktls-utils is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
  * published by the Free Software Foundation; version 2.
@@ -18,6 +21,10 @@
 
 #include <linux/netlink.h>
 
+/**
+ * @def ARRAY_SIZE
+ * @brief Generate the number of elements in an array
+ */
 #define ARRAY_SIZE(a)		(sizeof(a) / sizeof((a)[0]))
 
 extern int tlshd_debug;
@@ -27,21 +34,27 @@ extern int tlshd_stderr;
 
 struct nl_sock;
 
+/**
+ * @struct tlshd_handshake_parms
+ * @brief Handshake parameters (global)
+ */
 struct tlshd_handshake_parms {
-	char		*peername;
-	char		*peeraddr;
-	int		sockfd;
-	int		ip_proto;
-	uint32_t	handshake_type;
-	unsigned int	timeout_ms;
-	uint32_t	auth_mode;
-	key_serial_t	keyring;
-	key_serial_t	x509_cert;
-	key_serial_t	x509_privkey;
-	GArray		*peerids;
-	GArray		*remote_peerids;
+	/*@{*/
+	char		*peername;	/**< Remote's DNS label */
+	char		*peeraddr;	/**< Remote's IP address */
+	int		sockfd;		/**< Socket on which to perform the handshake */
+	int		ip_proto;	/**< Transport protocol number */
+	uint32_t	handshake_type;	/**< Handshake interaction to perform */
+	unsigned int	timeout_ms;	/**< How long to wait for completion */
+	uint32_t	auth_mode;	/**< x.509, PSK, etc. */
+	key_serial_t	keyring;	/**< Keyring containing auth material */
+	key_serial_t	x509_cert;	/**< Key serial of our x.509 cert */
+	key_serial_t	x509_privkey;	/**< Key serial of our x.509 private key */
+	GArray		*peerids;	/**< Peer identities to present to servers */
+	GArray		*remote_peerids; /**< Peer identities presented by clients */
 
-	unsigned int	session_status;
+	unsigned int	session_status;	/**< Handshake completion status */
+	/*@}*/
 };
 
 enum peer_type {
@@ -134,6 +147,10 @@ extern void tlshd_quic_serverhello_handshake(struct tlshd_handshake_parms *parms
 #define TLSHD_QUIC_MAX_DATA_LEN		4096
 #define TLSHD_QUIC_MAX_ALPNS_LEN	128
 
+/**
+ * @struct tlshd_quic_msg
+ * @brief QUIC message format
+ */
 struct tlshd_quic_msg {
 	struct tlshd_quic_msg *next;
 	uint8_t data[TLSHD_QUIC_MAX_DATA_LEN];
@@ -141,6 +158,10 @@ struct tlshd_quic_msg {
 	uint8_t level;
 };
 
+/**
+ * @struct tlshd_quic_conn
+ * @brief QUIC connection object
+ */
 struct tlshd_quic_conn {
 	struct tlshd_handshake_parms *parms;
 	char alpns[TLSHD_QUIC_MAX_ALPNS_LEN];
@@ -161,16 +182,39 @@ struct tlshd_quic_conn {
 	struct tlshd_quic_msg recv_msg;
 };
 
-/* quic.c */
 extern int tlshd_quic_conn_create(struct tlshd_quic_conn **conn_p,
 				  struct tlshd_handshake_parms *parms);
 extern void tlshd_quic_conn_destroy(struct tlshd_quic_conn *conn);
 extern void tlshd_quic_start_handshake(struct tlshd_quic_conn *conn);
+
 #endif
 
+/**
+ * @def TLS_DEFAULT_PSK_TYPE
+ * @brief Default type of pre-shared key
+ */
 #define TLS_DEFAULT_PSK_TYPE	"psk"
+
+/**
+ * @def TLS_NO_PEERID
+ * @brief No peer ID provided via keyring
+ */
 #define TLS_NO_PEERID		(0)
+
+/**
+ * @def TLS_NO_CERT
+ * @brief No certificate provided via keyring
+ */
 #define TLS_NO_CERT		(0)
+
+/**
+ * @def TLS_NO_PRIVKEY
+ * @brief No private key provided via keyring
+ */
 #define TLS_NO_PRIVKEY		(0)
-/* Max number of (chained) certs to load */
+
+/**
+ * @def TLSHD_MAX_CERTS
+ * @brief Maximum number of (chained) certs to load
+ */
 #define TLSHD_MAX_CERTS		10
-- 
2.51.0