TestCXXAcceptsFlag: Update documentation

- Also CheckCompilerFlag module suggested in the deprecation notice
- Lowercase style used for macro
- Descriptions extended
- Added examples

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)

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> <variable>)
+    check_cxx_accepts_flag(<flags> <result-variable>)
 
   ``<flags>``
- the flags to try
+    One or more compiler flags to test.  For multiple flags, provide them as a
-``<variable>``
+    space-separated string.
- variable to store the result
+
+  ``<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
+
+  include(TestCXXAcceptsFlag)
+  check_cxx_accepts_flag("-fno-common -fstack-clash-protection" HAVE_FLAGS)
+
+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)