From 86198d71e3f2d0684b4261e9c40baab7f3cff7a0 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Mon, 11 Apr 2022 17:04:38 +0200
Subject: [PATCH] Place MBEDTLS_CONFIG_FILE and such into a new section

Include this new section in the "full for documentation" (`realfull`)
configuration, so that these options are documented in the official
documentation build (`scripts/apidoc_full.sh`).

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 include/mbedtls/config.h | 20 ++++++++++++++++++--
 scripts/config.py        | 12 ++++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 81fc4c5f0..bf28de5fb 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -3620,7 +3620,7 @@
 /** \} name SECTION: mbed TLS modules */
 
 /**
- * \name SECTION: Module configuration options
+ * \name SECTION: General configuration options
  *
  * This section allows for the setting of module specific sizes and
  * configuration options. The default values are already present in the
@@ -3634,7 +3634,6 @@
  * \{
  */
 
-/* Meta configuration */
 /**
  * \def MBEDTLS_CONFIG_FILE
  *
@@ -3699,6 +3698,23 @@
  */
 //#define MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE "/dev/null"
 
+/** \} name SECTION: General configuration options */
+
+/**
+ * \name SECTION: Module configuration options
+ *
+ * This section allows for the setting of module specific sizes and
+ * configuration options. The default values are already present in the
+ * relevant header files and should suffice for the regular use cases.
+ *
+ * Our advice is to enable options and change their values here
+ * only if you have a good reason and know the consequences.
+ *
+ * Please check the respective header file for documentation on these
+ * parameters (to prevent duplicate documentation).
+ * \{
+ */
+
 /* MPI / BIGNUM options */
 //#define MBEDTLS_MPI_WINDOW_SIZE            6 /**< Maximum window size used. */
 //#define MBEDTLS_MPI_MAX_SIZE            1024 /**< Maximum number of bytes for usable MPIs. */
diff --git a/scripts/config.py b/scripts/config.py
index ded77854e..19b60e1b5 100755
--- a/scripts/config.py
+++ b/scripts/config.py
@@ -152,8 +152,16 @@ def is_full_section(section):
     return section.endswith('support') or section.endswith('modules')
 
 def realfull_adapter(_name, active, section):
-    """Activate all symbols found in the system and feature sections."""
-    if not is_full_section(section):
+    """Activate all symbols found in the global and boolean feature sections.
+
+    This is intended for building the documentation, including the
+    documentation of settings that are activated by defining an optional
+    preprocessor macro.
+
+    Do not activate definitions in the section containing symbols that are
+    supposed to be defined and documented in their own module.
+    """
+    if section == 'Module configuration options':
         return active
     return True