From 9e9b51369e1cab201bb690c19badeda42b517fad Mon Sep 17 00:00:00 2001
From: Cyprian Klimaszewski <kapitan.cypek@gmail.com>
Date: Sun, 11 Jan 2026 10:58:20 +0100
Subject: [PATCH] Cmake options to customise doxygen warnings. (#15071)

* Add: Cmake otion to hide line numbers in doxygen warnings.
* Add: Cmake options to specify output file for doxygen warnings.

Adds 3 options each one for each docs target, because doxygen deletes
content of the specified file before it begins to write into it.
---
 CMakeLists.txt                |  4 ++++
 Doxyfile.in                   |  4 ++--
 cmake/Options.cmake           | 20 ++++++++++++++++++++
 src/script/api/Doxyfile_AI.in |  4 ++--
 src/script/api/Doxyfile_GS.in |  4 ++--
 5 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index a39d2dea85..7f5dff10dd 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -75,6 +75,10 @@ add_custom_target(find_version
                 -DREV_MAJOR=${PROJECT_VERSION_MAJOR}
                 -DREV_MINOR=${PROJECT_VERSION_MINOR}
                 -DWINDOWS=${WIN32}
+                -DDOXYGEN_WARN_FORMAT_LINE=${DOXYGEN_WARN_FORMAT_LINE}
+                -DDOXYGEN_WARN_FILE=${DOXYGEN_WARN_FILE}
+                -DDOXYGEN_GS_WARN_FILE=${DOXYGEN_GS_WARN_FILE}
+                -DDOXYGEN_AI_WARN_FILE=${DOXYGEN_AI_WARN_FILE}
                 -P "${CMAKE_SOURCE_DIR}/cmake/scripts/FindVersion.cmake"
         WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
         BYPRODUCTS ${GENERATED_SOURCE_FILES}
diff --git a/Doxyfile.in b/Doxyfile.in
index 38aa129ca2..0652dbeb91 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -120,9 +120,9 @@ WARN_IF_DOC_ERROR      = YES
 WARN_IF_INCOMPLETE_DOC = YES
 WARN_NO_PARAMDOC       = YES
 WARN_AS_ERROR          = NO
-WARN_FORMAT            = "$file:$line: $text"
+WARN_FORMAT            = "$file:$${DOXYGEN_WARN_FORMAT_LINE}: $text"
 WARN_LINE_FORMAT       = "at line $line of file $file"
-WARN_LOGFILE           =
+WARN_LOGFILE           = ${DOXYGEN_WARN_FILE}
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
diff --git a/cmake/Options.cmake b/cmake/Options.cmake
index 38d708c717..cf4655a27c 100644
--- a/cmake/Options.cmake
+++ b/cmake/Options.cmake
@@ -61,12 +61,32 @@ function(set_options)
     option(OPTION_TOOLS_ONLY "Build only tools target" OFF)
     option(OPTION_DOCS_ONLY "Build only docs target" OFF)
     option(OPTION_ALLOW_INVALID_SIGNATURE "Allow loading of content with invalid signatures" OFF)
+    option(OPTION_LINE_IN_DOXYGEN_WARNINGS "Print line number in doxygen warnings" ON)
 
     if (OPTION_DOCS_ONLY)
         set(OPTION_TOOLS_ONLY ON PARENT_SCOPE)
     endif()
 
+    if (OPTION_LINE_IN_DOXYGEN_WARNINGS)
+        set(DOXYGEN_WARN_FORMAT_LINE "line" PARENT_SCOPE)
+    endif()
+
     option(OPTION_SURVEY_KEY "Survey-key to use for the opt-in survey (empty if you have none)" "")
+    option(OPTION_DOXYGEN_WARN_FILE "File to write doxygen warnings into (if empty warnings are written to standard error)" "")
+    option(OPTION_DOXYGEN_GS_WARN_FILE "File to write doxygen warnings from game script docs into (if empty warnings are written to standard error)" "")
+    option(OPTION_DOXYGEN_AI_WARN_FILE "File to write doxygen warnings from AI docs into (if empty warnings are written to standard error)" "")
+
+    if(OPTION_DOXYGEN_WARN_FILE)
+	    set(DOXYGEN_WARN_FILE ${CMAKE_BINARY_DIR}/${OPTION_DOXYGEN_WARN_FILE} PARENT_SCOPE)
+    endif()
+
+    if(OPTION_DOXYGEN_GS_WARN_FILE)
+        set(DOXYGEN_GS_WARN_FILE ${CMAKE_BINARY_DIR}/${OPTION_DOXYGEN_GS_WARN_FILE} PARENT_SCOPE)
+    endif()
+
+    if(OPTION_DOXYGEN_AI_WARN_FILE)
+        set(DOXYGEN_AI_WARN_FILE ${CMAKE_BINARY_DIR}/${OPTION_DOXYGEN_AI_WARN_FILE} PARENT_SCOPE)
+    endif()
 endfunction()
 
 # Show the values of the generic options.
diff --git a/src/script/api/Doxyfile_AI.in b/src/script/api/Doxyfile_AI.in
index 63536335fd..84f8640a2b 100644
--- a/src/script/api/Doxyfile_AI.in
+++ b/src/script/api/Doxyfile_AI.in
@@ -120,9 +120,9 @@ WARN_IF_DOC_ERROR      = YES
 WARN_IF_INCOMPLETE_DOC = YES
 WARN_NO_PARAMDOC       = YES
 WARN_AS_ERROR          = NO
-WARN_FORMAT            = "$file:$line: $text"
+WARN_FORMAT            = "$file:$${DOXYGEN_WARN_FORMAT_LINE}: $text"
 WARN_LINE_FORMAT       = "at line $line of file $file"
-WARN_LOGFILE           =
+WARN_LOGFILE           = ${DOXYGEN_AI_WARN_FILE}
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
diff --git a/src/script/api/Doxyfile_GS.in b/src/script/api/Doxyfile_GS.in
index 3865d771e3..b4e05129c6 100644
--- a/src/script/api/Doxyfile_GS.in
+++ b/src/script/api/Doxyfile_GS.in
@@ -120,9 +120,9 @@ WARN_IF_DOC_ERROR      = YES
 WARN_IF_INCOMPLETE_DOC = YES
 WARN_NO_PARAMDOC       = YES
 WARN_AS_ERROR          = NO
-WARN_FORMAT            = "$file:$line: $text"
+WARN_FORMAT            = "$file:$${DOXYGEN_WARN_FORMAT_LINE}: $text"
 WARN_LINE_FORMAT       = "at line $line of file $file"
-WARN_LOGFILE           =
+WARN_LOGFILE           = ${DOXYGEN_GS_WARN_FILE}
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------