From ef0119f57f33cb9ebcb887ae848d222207c0523a Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Tue, 11 Mar 2025 15:28:48 +0100
Subject: [PATCH] TestForSTDNamespace: Update documentation

This describes the module in more details to make upgrading code easier.
---
 Modules/TestForSTDNamespace.cmake | 43 ++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/Modules/TestForSTDNamespace.cmake b/Modules/TestForSTDNamespace.cmake
index e565e5c97d..f057d7ea6a 100644
--- a/Modules/TestForSTDNamespace.cmake
+++ b/Modules/TestForSTDNamespace.cmake
@@ -5,13 +5,48 @@
 TestForSTDNamespace
 -------------------
 
-Test for std:: namespace support
+This module checks whether the ``CXX`` compiler supports the ``std`` namespace
+for the C++ Standard Library.  Early versions of C++ (pre-C++98) did not have a
+requirement for a dedicated namespace of C++ Standard Template Library (STL)
+components (e.g. ``list``, etc.) and other parts of the C++ Standard Library
+(such as I/O streams ``cout``, ``endl``, etc), so they were available globally.
 
-check if the compiler supports std:: on stl classes
+This module defines the following cache variable:
 
-::
+``CMAKE_NO_STD_NAMESPACE``
+  A cache variable containing the result of the check.  It will be set to value
+  ``0`` if the ``std`` namespace is supported (``C++ 98`` and newer), and to
+  value ``1`` if not (``ANSI C++``).
 
-  CMAKE_NO_STD_NAMESPACE - defined by the results
+.. note::
+
+  The ``std`` namespace got formally introduced in ``C++ 98`` standard, making
+  this issue obsolete.
+
+Examples
+^^^^^^^^
+
+Including this module will check for the ``std`` namespace support and define
+the ``CMAKE_NO_STD_NAMESPACE`` cache variable:
+
+.. code-block:: cmake
+
+  include(TestForSTDNamespace)
+  file(
+    CONFIGURE
+    OUTPUT config.h
+    CONTENT "#cmakedefine CMAKE_NO_STD_NAMESPACE"
+  )
+
+which can be then used in a C++ program to define the missing namespace:
+
+.. code-block:: c++
+
+  #include "config.h"
+
+  #ifdef CMAKE_NO_STD_NAMESPACE
+  #  define std
+  #endif
 #]=======================================================================]
 
 if(NOT DEFINED CMAKE_STD_NAMESPACE)