From 93f2ba0a4f7e576441eb5feb17e4cb3d178d37a3 Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Wed, 22 Mar 2023 10:37:16 +0000
Subject: [PATCH] cmake, doc: Document compiler flags

---
 CMakeLists.txt | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 4dcf7b416f..d109f37c02 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -184,20 +184,22 @@ endif()
 
 include(TryAppendCFlags)
 if(MSVC)
-  try_append_c_flags(/W2)
-  try_append_c_flags(/wd4146)
+  # Keep the following commands ordered lexicographically.
+  try_append_c_flags(/W2) # Moderate warning level.
+  try_append_c_flags(/wd4146) # Disable warning C4146 "unary minus operator applied to unsigned type, result still unsigned".
 else()
+  # Keep the following commands ordered lexicographically.
   try_append_c_flags(-pedantic)
-  try_append_c_flags(-Wall)
-  try_append_c_flags(-Wcast-align)
-  try_append_c_flags(-Wcast-align=strict)
-  try_append_c_flags(-Wconditional-uninitialized)
-  try_append_c_flags(-Wextra)
+  try_append_c_flags(-Wall) # GCC >= 2.95 and probably many other compilers.
+  try_append_c_flags(-Wcast-align) # GCC >= 2.95.
+  try_append_c_flags(-Wcast-align=strict) # GCC >= 8.0.
+  try_append_c_flags(-Wconditional-uninitialized) # Clang >= 3.0 only.
+  try_append_c_flags(-Wextra) # GCC >= 3.4, this is the newer name of -W, which we don't use because older GCCs will warn about unused functions.
   try_append_c_flags(-Wnested-externs)
-  try_append_c_flags(-Wno-long-long)
-  try_append_c_flags(-Wno-overlength-strings)
-  try_append_c_flags(-Wno-unused-function)
-  try_append_c_flags(-Wreserved-identifier)
+  try_append_c_flags(-Wno-long-long) # GCC >= 3.0, -Wlong-long is implied by -pedantic.
+  try_append_c_flags(-Wno-overlength-strings) # GCC >= 4.2, -Woverlength-strings is implied by -pedantic.
+  try_append_c_flags(-Wno-unused-function) # GCC >= 3.0, -Wunused-function is implied by -Wall.
+  try_append_c_flags(-Wreserved-identifier) # Clang >= 13.0 only.
   try_append_c_flags(-Wshadow)
   try_append_c_flags(-Wstrict-prototypes)
   try_append_c_flags(-Wundef)