From 38d4fddcd859d23f9876895e56100d7c4dc9aa67 Mon Sep 17 00:00:00 2001
From: Andrzej Kurek <Andrzej.Kurek@arm.com>
Date: Tue, 28 Dec 2021 16:22:52 +0100
Subject: [PATCH 1/4] Add missing asterisk to doxygen closures

Clarify section names next to closing braces
Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
---
 include/mbedtls/asn1.h                | 8 +++++---
 include/mbedtls/ctr_drbg.h            | 2 +-
 include/mbedtls/entropy.h             | 2 +-
 include/mbedtls/hkdf.h                | 2 +-
 include/mbedtls/hmac_drbg.h           | 2 +-
 include/mbedtls/mbedtls_config.h      | 8 ++++----
 include/mbedtls/memory_buffer_alloc.h | 2 +-
 include/mbedtls/pem.h                 | 2 +-
 include/mbedtls/platform.h            | 2 +-
 include/mbedtls/platform_time.h       | 1 +
 include/mbedtls/ssl.h                 | 2 +-
 include/mbedtls/ssl_cache.h           | 2 +-
 include/mbedtls/ssl_cookie.h          | 2 +-
 include/mbedtls/x509.h                | 6 +++---
 include/mbedtls/x509_crl.h            | 4 ++--
 include/mbedtls/x509_crt.h            | 4 ++--
 include/mbedtls/x509_csr.h            | 4 ++--
 17 files changed, 29 insertions(+), 26 deletions(-)

diff --git a/include/mbedtls/asn1.h b/include/mbedtls/asn1.h
index 4746c1cb4..b64af10ca 100644
--- a/include/mbedtls/asn1.h
+++ b/include/mbedtls/asn1.h
@@ -58,7 +58,7 @@
 /** Buffer too small when writing ASN.1 data structure. */
 #define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL                    -0x006C
 
-/* \} name */
+/** \} name ASN1 Error codes */
 
 /**
  * \name DER constants
@@ -118,8 +118,8 @@
 #define MBEDTLS_ASN1_TAG_PC_MASK             0x20
 #define MBEDTLS_ASN1_TAG_VALUE_MASK          0x1F
 
-/* \} name */
-/* \} addtogroup asn1_module */
+/** \} name DER constants */
+/** \} addtogroup asn1_module */
 
 /** Returns the size of the binary string, without the trailing \\0 */
 #define MBEDTLS_OID_SIZE(x) (sizeof(x) - 1)
@@ -626,6 +626,8 @@ void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry );
  */
 void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head );
 
+/** \} name Functions to parse ASN.1 data structures */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 959a5d57c..2b66b534a 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -135,7 +135,7 @@
 /**< The maximum size of seed or reseed buffer in bytes. */
 #endif
 
-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */
 
 #define MBEDTLS_CTR_DRBG_PR_OFF             0
 /**< Prediction resistance is disabled. */
diff --git a/include/mbedtls/entropy.h b/include/mbedtls/entropy.h
index fede05ffa..14e8b31c7 100644
--- a/include/mbedtls/entropy.h
+++ b/include/mbedtls/entropy.h
@@ -69,7 +69,7 @@
 #define MBEDTLS_ENTROPY_MAX_GATHER      128     /**< Maximum amount requested from entropy sources */
 #endif
 
-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */
 
 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
 #define MBEDTLS_ENTROPY_BLOCK_SIZE      64      /**< Block size of entropy accumulator (SHA-512) */
diff --git a/include/mbedtls/hkdf.h b/include/mbedtls/hkdf.h
index e6bfe0560..2e225cb3b 100644
--- a/include/mbedtls/hkdf.h
+++ b/include/mbedtls/hkdf.h
@@ -35,7 +35,7 @@
  */
 /** Bad input parameters to function. */
 #define MBEDTLS_ERR_HKDF_BAD_INPUT_DATA  -0x5F80
-/* \} name */
+/** \} name */
 
 #ifdef __cplusplus
 extern "C" {
diff --git a/include/mbedtls/hmac_drbg.h b/include/mbedtls/hmac_drbg.h
index 0f1653f7a..37702b595 100644
--- a/include/mbedtls/hmac_drbg.h
+++ b/include/mbedtls/hmac_drbg.h
@@ -71,7 +71,7 @@
 #define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT    384     /**< Maximum size of (re)seed buffer */
 #endif
 
-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */
 
 #define MBEDTLS_HMAC_DRBG_PR_OFF   0   /**< No prediction resistance       */
 #define MBEDTLS_HMAC_DRBG_PR_ON    1   /**< Prediction resistance enabled  */
diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h
index 0558ee001..1885380ef 100644
--- a/include/mbedtls/mbedtls_config.h
+++ b/include/mbedtls/mbedtls_config.h
@@ -256,7 +256,7 @@
  */
 //#define MBEDTLS_DEPRECATED_REMOVED
 
-/* \} name SECTION: System support */
+/** \} name SECTION: System support */
 
 /**
  * \name SECTION: mbed TLS feature support
@@ -1829,7 +1829,7 @@
  * Comment this macro to disallow using RSASSA-PSS in certificates.
  */
 #define MBEDTLS_X509_RSASSA_PSS_SUPPORT
-/* \} name SECTION: mbed TLS feature support */
+/** \} name SECTION: mbed TLS feature support */
 
 /**
  * \name SECTION: mbed TLS modules
@@ -3021,7 +3021,7 @@
  */
 #define MBEDTLS_X509_CSR_WRITE_C
 
-/* \} name SECTION: mbed TLS modules */
+/** \} name SECTION: mbed TLS modules */
 
 /**
  * \name SECTION: Module configuration options
@@ -3319,4 +3319,4 @@
  */
 //#define MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED
 
-/* \} name SECTION: Customisation configuration options */
+/** \} name SECTION: Customisation configuration options */
diff --git a/include/mbedtls/memory_buffer_alloc.h b/include/mbedtls/memory_buffer_alloc.h
index d4737f5c4..857fa5e9c 100644
--- a/include/mbedtls/memory_buffer_alloc.h
+++ b/include/mbedtls/memory_buffer_alloc.h
@@ -38,7 +38,7 @@
 #define MBEDTLS_MEMORY_ALIGN_MULTIPLE       4 /**< Align on multiples of this value */
 #endif
 
-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */
 
 #define MBEDTLS_MEMORY_VERIFY_NONE         0
 #define MBEDTLS_MEMORY_VERIFY_ALLOC        (1 << 0)
diff --git a/include/mbedtls/pem.h b/include/mbedtls/pem.h
index baceb0762..a2b73f8cf 100644
--- a/include/mbedtls/pem.h
+++ b/include/mbedtls/pem.h
@@ -51,7 +51,7 @@
 #define MBEDTLS_ERR_PEM_FEATURE_UNAVAILABLE               -0x1400
 /** Bad input parameters to function. */
 #define MBEDTLS_ERR_PEM_BAD_INPUT_DATA                    -0x1480
-/* \} name */
+/** \} name PEM Error codes */
 
 #ifdef __cplusplus
 extern "C" {
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index 277a85c7d..11a9ca1b6 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -119,7 +119,7 @@ extern "C" {
 #endif /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */
 
 
-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */
 
 /*
  * The function pointers for calloc and free.
diff --git a/include/mbedtls/platform_time.h b/include/mbedtls/platform_time.h
index 8d4b95d1d..0af62e8d0 100644
--- a/include/mbedtls/platform_time.h
+++ b/include/mbedtls/platform_time.h
@@ -73,4 +73,5 @@ int mbedtls_platform_set_time( mbedtls_time_t (*time_func)( mbedtls_time_t* time
 }
 #endif
 
+/** \} name SECTION: Module settings */
 #endif /* platform_time.h */
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 072ebbe46..54a4a0970 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -380,7 +380,7 @@
 #define MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY 16
 #endif
 
-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */
 
 /*
  * Length of the verify data for secure renegotiation
diff --git a/include/mbedtls/ssl_cache.h b/include/mbedtls/ssl_cache.h
index 6a81ac990..cb016fe70 100644
--- a/include/mbedtls/ssl_cache.h
+++ b/include/mbedtls/ssl_cache.h
@@ -47,7 +47,7 @@
 #define MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES      50   /*!< Maximum entries in cache */
 #endif
 
-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */
 
 #ifdef __cplusplus
 extern "C" {
diff --git a/include/mbedtls/ssl_cookie.h b/include/mbedtls/ssl_cookie.h
index 86698b050..34452aae6 100644
--- a/include/mbedtls/ssl_cookie.h
+++ b/include/mbedtls/ssl_cookie.h
@@ -42,7 +42,7 @@
 #define MBEDTLS_SSL_COOKIE_TIMEOUT     60 /**< Default expiration delay of DTLS cookies, in seconds if HAVE_TIME, or in number of cookies issued */
 #endif
 
-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */
 
 #ifdef __cplusplus
 extern "C" {
diff --git a/include/mbedtls/x509.h b/include/mbedtls/x509.h
index 9a4be95a3..22d0a2c93 100644
--- a/include/mbedtls/x509.h
+++ b/include/mbedtls/x509.h
@@ -93,7 +93,7 @@
 #define MBEDTLS_ERR_X509_BUFFER_TOO_SMALL                 -0x2980
 /** A fatal error occurred, eg the chain is too long or the vrfy callback failed. */
 #define MBEDTLS_ERR_X509_FATAL_ERROR                      -0x3000
-/* \} name */
+/** \} name X509 Error codes */
 
 /**
  * \name X509 Verify codes
@@ -121,8 +121,8 @@
 #define MBEDTLS_X509_BADCRL_BAD_PK           0x040000  /**< The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA). */
 #define MBEDTLS_X509_BADCRL_BAD_KEY          0x080000  /**< The CRL is signed with an unacceptable key (eg bad curve, RSA too short). */
 
-/* \} name */
-/* \} addtogroup x509_module */
+/** \} name X509 Verify codes */
+/** \} addtogroup x509_module */
 
 /*
  * X.509 v3 Subject Alternative Name types.
diff --git a/include/mbedtls/x509_crl.h b/include/mbedtls/x509_crl.h
index 52bd43cd3..0339db861 100644
--- a/include/mbedtls/x509_crl.h
+++ b/include/mbedtls/x509_crl.h
@@ -176,8 +176,8 @@ void mbedtls_x509_crl_init( mbedtls_x509_crl *crl );
  */
 void mbedtls_x509_crl_free( mbedtls_x509_crl *crl );
 
-/* \} name */
-/* \} addtogroup x509_module */
+/** \} name Structures and functions for parsing CRLs */
+/** \} addtogroup x509_module */
 
 #ifdef __cplusplus
 }
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index 3c11a9989..e157efa8d 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -955,8 +955,8 @@ void mbedtls_x509_crt_restart_free( mbedtls_x509_crt_restart_ctx *ctx );
 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
 #endif /* MBEDTLS_X509_CRT_PARSE_C */
 
-/* \} name */
-/* \} addtogroup x509_module */
+/** \} name Structures and functions for parsing and writing X.509 certificates */
+/** \} addtogroup x509_module */
 
 #if defined(MBEDTLS_X509_CRT_WRITE_C)
 /**
diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h
index f80a1a130..7ec5ecaa1 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -154,8 +154,8 @@ void mbedtls_x509_csr_init( mbedtls_x509_csr *csr );
 void mbedtls_x509_csr_free( mbedtls_x509_csr *csr );
 #endif /* MBEDTLS_X509_CSR_PARSE_C */
 
-/* \} name */
-/* \} addtogroup x509_module */
+/** \} name Structures and functions for X.509 Certificate Signing Requests (CSR) */
+/** \} addtogroup x509_module */
 
 #if defined(MBEDTLS_X509_CSR_WRITE_C)
 /**

From a0defed667aa9c41863f407d4cb493f1b1c917b2 Mon Sep 17 00:00:00 2001
From: Andrzej Kurek <Andrzej.Kurek@arm.com>
Date: Thu, 30 Dec 2021 12:33:31 +0100
Subject: [PATCH 2/4] doxygen: move addtogroup closures to include more
 elements

Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
---
 include/mbedtls/asn1.h     | 2 +-
 include/mbedtls/x509.h     | 3 ++-
 include/mbedtls/x509_crt.h | 3 ++-
 include/mbedtls/x509_csr.h | 3 ++-
 4 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/include/mbedtls/asn1.h b/include/mbedtls/asn1.h
index b64af10ca..30b0ed242 100644
--- a/include/mbedtls/asn1.h
+++ b/include/mbedtls/asn1.h
@@ -119,7 +119,6 @@
 #define MBEDTLS_ASN1_TAG_VALUE_MASK          0x1F
 
 /** \} name DER constants */
-/** \} addtogroup asn1_module */
 
 /** Returns the size of the binary string, without the trailing \\0 */
 #define MBEDTLS_OID_SIZE(x) (sizeof(x) - 1)
@@ -627,6 +626,7 @@ void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry );
 void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head );
 
 /** \} name Functions to parse ASN.1 data structures */
+/** \} addtogroup asn1_module */
 
 #ifdef __cplusplus
 }
diff --git a/include/mbedtls/x509.h b/include/mbedtls/x509.h
index 22d0a2c93..3c76fec78 100644
--- a/include/mbedtls/x509.h
+++ b/include/mbedtls/x509.h
@@ -252,7 +252,6 @@ typedef struct mbedtls_x509_time
 mbedtls_x509_time;
 
 /** \} name Structures for parsing X.509 certificates, CRLs and CSRs */
-/** \} addtogroup x509_module */
 
 /**
  * \brief          Store the certificate DN in printable form into buf;
@@ -308,6 +307,8 @@ int mbedtls_x509_time_is_past( const mbedtls_x509_time *to );
  */
 int mbedtls_x509_time_is_future( const mbedtls_x509_time *from );
 
+/** \} addtogroup x509_module */
+
 /*
  * Internal module functions. You probably do not want to use these unless you
  * know you do.
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index e157efa8d..51883dc86 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -956,7 +956,6 @@ void mbedtls_x509_crt_restart_free( mbedtls_x509_crt_restart_ctx *ctx );
 #endif /* MBEDTLS_X509_CRT_PARSE_C */
 
 /** \} name Structures and functions for parsing and writing X.509 certificates */
-/** \} addtogroup x509_module */
 
 #if defined(MBEDTLS_X509_CRT_WRITE_C)
 /**
@@ -1186,6 +1185,8 @@ int mbedtls_x509write_crt_pem( mbedtls_x509write_cert *ctx, unsigned char *buf,
 #endif /* MBEDTLS_PEM_WRITE_C */
 #endif /* MBEDTLS_X509_CRT_WRITE_C */
 
+/** \} addtogroup x509_module */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h
index 7ec5ecaa1..20a516e02 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -155,7 +155,6 @@ void mbedtls_x509_csr_free( mbedtls_x509_csr *csr );
 #endif /* MBEDTLS_X509_CSR_PARSE_C */
 
 /** \} name Structures and functions for X.509 Certificate Signing Requests (CSR) */
-/** \} addtogroup x509_module */
 
 #if defined(MBEDTLS_X509_CSR_WRITE_C)
 /**
@@ -297,6 +296,8 @@ int mbedtls_x509write_csr_pem( mbedtls_x509write_csr *ctx, unsigned char *buf, s
 #endif /* MBEDTLS_PEM_WRITE_C */
 #endif /* MBEDTLS_X509_CSR_WRITE_C */
 
+/** \} addtogroup x509_module */
+
 #ifdef __cplusplus
 }
 #endif

From 01404dfaa278a6c24934b2606e0711999f0e246a Mon Sep 17 00:00:00 2001
From: Andrzej Kurek <Andrzej.Kurek@arm.com>
Date: Thu, 30 Dec 2021 12:34:00 +0100
Subject: [PATCH 3/4] doxygen: remove empty platform_time configuration section

Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
---
 include/mbedtls/platform_time.h | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/include/mbedtls/platform_time.h b/include/mbedtls/platform_time.h
index 0af62e8d0..8bef55378 100644
--- a/include/mbedtls/platform_time.h
+++ b/include/mbedtls/platform_time.h
@@ -28,14 +28,6 @@
 extern "C" {
 #endif
 
-/**
- * \name SECTION: Module settings
- *
- * The configuration options you can set for this module are in this section.
- * Either change them in mbedtls_config.h or define them on the compiler command line.
- * \{
- */
-
 /*
  * The time_t datatype
  */
@@ -73,5 +65,4 @@ int mbedtls_platform_set_time( mbedtls_time_t (*time_func)( mbedtls_time_t* time
 }
 #endif
 
-/** \} name SECTION: Module settings */
 #endif /* platform_time.h */

From cead70dbe52600e0e0d82cfc5cc7c4dced060b19 Mon Sep 17 00:00:00 2001
From: Andrzej Kurek <andrzej.kurek@arm.com>
Date: Mon, 24 Jan 2022 10:48:10 -0500
Subject: [PATCH 4/4] doxygen: fix missing asterisk in ecp.h

Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
---
 include/mbedtls/ecp.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index 5b26084d4..989557367 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -299,7 +299,7 @@ mbedtls_ecp_group;
 #define MBEDTLS_ECP_FIXED_POINT_OPTIM  1   /**< Enable fixed-point speed-up. */
 #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
 
-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */
 
 #else  /* MBEDTLS_ECP_ALT */
 #include "ecp_alt.h"