[PATCH v1 05/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/config.c

[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 config.c 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/config.c | 152 ++++++++++++++++++++++++++-------------------
 1 file changed, 88 insertions(+), 64 deletions(-)

diff --git a/src/tlshd/config.c b/src/tlshd/config.c
index bf57df17f48c..1afe1ff9bca0 100644
--- a/src/tlshd/config.c
+++ b/src/tlshd/config.c
@@ -1,6 +1,10 @@
+/**
+ * @file config.c
+ * @brief Parse tlshd's config file
+ */
+
 /*
- * Parse tlshd's config file.
- *
+ * @copyright
  * Copyright (c) 2022 Oracle and/or its affiliates.
  *
  * ktls-utils is free software; you can redistribute it and/or
@@ -44,16 +48,20 @@
 
 #include "tlshd.h"
 
+/**
+ * @var GKeyFile *tlshd_configuration
+ * In-memory parsed config file
+ */
 static GKeyFile *tlshd_configuration;
 
 /**
- * tlshd_config_init - Read tlshd's config file
- * @pathname: Pathname to config file
- * @legacy: Don't generate an error if the config file doesn't exist
+ * @brief Parse tlshd's config file
+ * @param[in]    pathname  Pathname to config file
+ * @param[in]    legacy    Don't generate an error if the specified
+ *			   config file doesn't exist
  *
- * Return values:
- *   %true: Config file read successfully
- *   %false: Unable to read config file
+ * @retval true   Config file parsed successfully
+ * @retval false  Unable to read config file
  */
 bool tlshd_config_init(const gchar *pathname, bool legacy)
 {
@@ -111,26 +119,49 @@ bool tlshd_config_init(const gchar *pathname, bool legacy)
 	return true;
 }
 
+/**
+ * @brief Release parsed config file data
+ */
 void tlshd_config_shutdown(void)
 {
 	g_key_file_free(tlshd_configuration);
 }
 
 /**
- * ALLPERMS exists in glibc, but not on musl, so we manually
- * define TLSHD_ACCESSPERMS instead of using ALLPERMS.
+ * @def TLSHD_ACCESSPERMS
+ * @brief ALLPERMS exists in glibc, but not on musl, so we manually
+ *	  define TLSHD_ACCESSPERMS instead of using ALLPERMS.
  */
 #define TLSHD_ACCESSPERMS	(S_IRWXU|S_IRWXG|S_IRWXO)
 
-/*
- * Expected file attributes
+/**
+ * @def TLSHD_OWNER
+ * @brief Expected owner of certificate and private key files
  */
 #define TLSHD_OWNER		0	/* root */
+
+/**
+ * @def TLSHD_CERT_MODE
+ * @brief Expected mode of certificate files
+ */
 #define TLSHD_CERT_MODE		(S_IRUSR|S_IWUSR|S_IRGRP|S_IROTH)
+
+/**
+ * @def TLSHD_PRIVKEY_MODE
+ * @brief Expected mode of private key files
+ */
 #define TLSHD_PRIVKEY_MODE	(S_IRUSR|S_IWUSR)
 
-/*
- * On success, caller must release buffer returned in @data by calling free(3)
+/**
+ * @brief Read one configuration file
+ * @param[in]    pathname  Pathname to file that is to be read
+ * @param[out]   data      Buffer containing all file content
+ * @param[in]    owner     Expected owner of file
+ * @param[in]    mode      Expected mode of file
+ *
+ * @retval true   File content retrieved successfully. Caller must
+ *		  release "data->data" by calling free(3)
+ * @retval false  File content not retrieved
  */
 static bool tlshd_config_read_datum(const char *pathname, gnutls_datum_t *data,
 				    uid_t owner, mode_t mode)
@@ -189,13 +220,13 @@ out:
 }
 
 /**
- * tlshd_config_get_truststore - Get truststore for {Client,Server}Hello from .conf
- * @peer_type: IN: peer type
- * @bundle: OUT: pathname to truststore
+ * @brief Get truststore to use for {Client,Server}Hello
+ * @param[in]     peer_type  peer type
+ * @param[out]    bundle     pathname to truststore
  *
- * Return values:
- *   %false: pathname not retrieved
- *   %true: pathname retrieved successfully; caller must free @bundle using free(3)
+ * @retval true   Trust store retrieved successfully. Caller must free
+ *		  "*bundle" using free(3)
+ * @retval false  Trust store not retrieved
  */
 bool tlshd_config_get_truststore(int peer_type, char **bundle)
 {
@@ -226,13 +257,13 @@ bool tlshd_config_get_truststore(int peer_type, char **bundle)
 }
 
 /**
- * tlshd_config_get_crl - Get CRL for {Client,Server}Hello from .conf
- * @peer_type: IN: peer type
- * @result: OUT: pathname to CRL
+ * @brief Get CRL for {Client,Server}Hello from .conf
+ * @param[in]     peer_type  peer type
+ * @param[out]    result     pathname to CRL
  *
- * Return values:
- *   %false: pathname not retrieved
- *   %true: pathname retrieved successfully; caller must free @result using free(3)
+ * @retval true   CRL retrieved successfully. Caller must free
+ *		  "*result" using free(3)
+ * @retval false  CRL not retrieved
  */
 bool tlshd_config_get_crl(int peer_type, char **result)
 {
@@ -308,16 +339,14 @@ static bool tlshd_cert_check_pk_alg(__attribute__ ((unused)) gnutls_datum_t *dat
 #endif /* HAVE_GNUTLS_MLDSA */
 
 /**
- * __tlshd_config_get_certs - Helper for tlshd_config_get_certs()
- * @peer_type: IN: peer type
- * @certs: OUT: in-memory certificates
- * @certs_len: IN: maximum number of certs to get, OUT: number of certs found
- * @pkgalg: IN: if non-NULL, indicates we want to retrieve the PQ cert,
- *	 OUT: if non-NULL, store the PQ public-key alg that was used in the PQ cert
+ * @brief Helper for tlshd_config_get_certs()
+ * @param[in]      peer_type  peer type
+ * @param[out]     certs      in-memory certificates
+ * @param[in,out]  certs_len  maximum number of certs to get, number of certs found
+ * @param[out]     pkalg      buffer for returning PQ algorithm
  *
- * Return values:
- *   %true: certificate retrieved successfully
- *   %false: certificate not retrieved
+ * @retval true   Certificate(s) retrieved successfully
+ * @retval false  Certificate(s) not retrieved
  */
 static bool __tlshd_config_get_certs(int peer_type, gnutls_pcert_st *certs,
 				     unsigned int *certs_len,
@@ -372,21 +401,20 @@ static bool __tlshd_config_get_certs(int peer_type, gnutls_pcert_st *certs,
 }
 
 /**
- * tlshd_config_get_certs - Get certs for {Client,Server} Hello from .conf
- * @peer_type: IN: peer type
- * @certs: OUT: in-memory certificates
- * @pq_certs_len: IN: maximum number of PQ certs to get, OUT: number of PQ certs found
- * @certs_len: IN: maximum number of certs to get, OUT: number of certs found
- * @pkgalg: OUT: the PQ public-key alg that was used in the PQ cert
+ * @brief Get certs for {Client,Server} Hello
+ * @param[in]      peer_type     peer type
+ * @param[out]     certs         in-memory certificates
+ * @param[in,out]  pq_certs_len  maximum number of PQ certs to get, number of PQ certs found
+ * @param[in,out]  certs_len     maximum number of certs to get, number of certs found
+ * @param[out]     pkalg         the PQ public-key alg that was used in the PQ cert
  *
- * Retrieve the PQ cert(s) first, then the RSA cert(s).  Both are stored in the
- * same list.  Note that @pq_certs_len is deducted from the available @certs_len
- * and is also used to determine the offset to store the RSA cert(s) in the
- * @certs array.
+ * Retrieve the PQ cert(s) first, then the RSA cert(s).  Both are
+ * stored in the same list.  Note that "pq_certs_len" is deducted
+ * from the available "certs_len" and is also used to determine
+ * the offset to store the RSA cert(s) in the "certs array".
  *
- * Return values:
- *   %true: certificate retrieved successfully
- *   %false: certificate not retrieved
+ * @retval true   Certificate(s) retrieved successfully
+ * @retval false  Certificate(s) not retrieved
  */
 bool tlshd_config_get_certs(int peer_type, gnutls_pcert_st *certs,
 			    unsigned int *pq_certs_len,
@@ -407,14 +435,13 @@ bool tlshd_config_get_certs(int peer_type, gnutls_pcert_st *certs,
 }
 
 /**
- * __tlshd_config_get_privkey - Helper for tlshd_config_get_privkey()
- * @peer_type: IN: peer type
- * @privkey: OUT: in-memory private key
- * @pq: IN: if true, retrieve the PQ private key
+ * @brief Helper for tlshd_config_get_privkey()
+ * @param[in]      peer_type  peer type
+ * @param[out]     privkey    in-memory private key
+ * @param[in]      pq         if true, retrieve the PQ private key
  *
- * Return values:
- *   %true: private key retrieved successfully
- *   %false: private key not retrieved
+ * @retval true   Private key retrieved successfully
+ * @retval false  Private key not retrieved
  */
 static bool __tlshd_config_get_privkey(int peer_type, gnutls_privkey_t *privkey, bool pq)
 {
@@ -463,16 +490,13 @@ static bool __tlshd_config_get_privkey(int peer_type, gnutls_privkey_t *privkey,
 }
 
 /**
- * tlshd_config_get_privkey - Get private key for {Client,Server}Hello from .conf
- * @peer_type: IN: peer type
- * @pq_privkey: OUT: in-memory PQ private key
- * @privkey: OUT: in-memory private key
+ * @brief Get private key for {Client,Server}Hello
+ * @param[in]      peer_type   peer type
+ * @param[out]     pq_privkey  in-memory PQ private key
+ * @param[out]     privkey     in-memory private key
  *
- * Retrieve the PQ private key first, then the RSA private key.
- *
- * Return values:
- *   %true: private key retrieved successfully
- *   %false: private key not retrieved
+ * @retval true   Private key retrieved successfully
+ * @retval false  Private key not retrieved
  */
 bool tlshd_config_get_privkey(int peer_type, gnutls_privkey_t *pq_privkey,
 			      gnutls_privkey_t *privkey)
-- 
2.51.0