From 1d72b4da10cd01bea9c819422d1688961b054d23 Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Sun, 23 Mar 2025 17:23:58 +0100
Subject: [PATCH] TestCXXAcceptsFlag: Update documentation

- Also CheckCompilerFlag module suggested in the deprecation notice
- Lowercase style used for macro
- Descriptions extended
- Added examples
---
 Modules/CMakeBackwardCompatibilityCXX.cmake |  2 +-
 Modules/TestCXXAcceptsFlag.cmake            | 45 +++++++++++++++++----
 2 files changed, 39 insertions(+), 8 deletions(-)

diff --git a/Modules/CMakeBackwardCompatibilityCXX.cmake b/Modules/CMakeBackwardCompatibilityCXX.cmake
index 4491c968f3..b0e6c16e7c 100644
--- a/Modules/CMakeBackwardCompatibilityCXX.cmake
+++ b/Modules/CMakeBackwardCompatibilityCXX.cmake
@@ -48,7 +48,7 @@ if(NOT CMAKE_SKIP_COMPATIBILITY_TESTS)
     # if CMAKE_TRY_ANSI_CXX_FLAGS has something in it, see
     # if the compiler accepts it
     if(NOT CMAKE_TRY_ANSI_CXX_FLAGS STREQUAL "")
-      CHECK_CXX_ACCEPTS_FLAG(${CMAKE_TRY_ANSI_CXX_FLAGS} CMAKE_CXX_ACCEPTS_FLAGS)
+      check_cxx_accepts_flag(${CMAKE_TRY_ANSI_CXX_FLAGS} CMAKE_CXX_ACCEPTS_FLAGS)
       # if the compiler liked the flag then set CMAKE_ANSI_CXXFLAGS
       # to the flag
       if(CMAKE_CXX_ACCEPTS_FLAGS)
diff --git a/Modules/TestCXXAcceptsFlag.cmake b/Modules/TestCXXAcceptsFlag.cmake
index 239db61386..a39f8b3b63 100644
--- a/Modules/TestCXXAcceptsFlag.cmake
+++ b/Modules/TestCXXAcceptsFlag.cmake
@@ -7,18 +7,49 @@ TestCXXAcceptsFlag
 
 .. deprecated:: 3.0
 
-  See :module:`CheckCXXCompilerFlag`.
+  This module should no longer be used.  It has been superseded by the
+  :module:`CheckCXXCompilerFlag` module.  As of CMake 3.19, the
+  :module:`CheckCompilerFlag` module is also available for checking flags across
+  multiple languages.
 
-Check if the CXX compiler accepts a flag.
+This module provides a macro to test whether the C++ (CXX) compiler supports
+specific flags.
+
+Macros
+^^^^^^
+
+.. command:: check_cxx_accepts_flag
+
+  Checks whether the CXX compiler accepts the specified flags:
+
+  .. code-block:: cmake
+
+    check_cxx_accepts_flag(<flags> <result-variable>)
+
+  ``<flags>``
+    One or more compiler flags to test.  For multiple flags, provide them as a
+    space-separated string.
+
+  ``<result-variable>``
+    Name of an internal cache variable that stores the result.  It is set to
+    boolean true if the compiler accepts the flags and false otherwise.
+
+Examples
+^^^^^^^^
+
+Checking if the C++ compiler supports specific flags:
 
 .. code-block:: cmake
 
- CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
+  include(TestCXXAcceptsFlag)
+  check_cxx_accepts_flag("-fno-common -fstack-clash-protection" HAVE_FLAGS)
 
-``<flags>``
- the flags to try
-``<variable>``
- variable to store the result
+Migrating to the :module:`CheckCompilerFlag` module:
+
+.. code-block:: cmake
+
+  include(CheckCompilerFlag)
+  check_compiler_flag(CXX "-fno-common;-fstack-clash-protection" HAVE_FLAGS)
 #]=======================================================================]
 
 macro(CHECK_CXX_ACCEPTS_FLAG FLAGS  VARIABLE)