From c2eb4b58c0e89ceb7b12ff0ff6cb21f14713bd5b Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Tue, 11 Mar 2025 15:18:47 +0100
Subject: [PATCH] TestForSSTREAM: Update documentation

This describes the module in more details to make upgrading code easier.

Additionally, also the CMAKE_HAS_ANSI_STRING_STREAM cache variable is
described as it was already briefly documented at the
CMakeBackwardCompatibilityCXX module.
---
 Modules/TestForSSTREAM.cmake | 47 +++++++++++++++++++++++++++++++++---
 1 file changed, 43 insertions(+), 4 deletions(-)

diff --git a/Modules/TestForSSTREAM.cmake b/Modules/TestForSSTREAM.cmake
index 40fb373129..f335a8acfb 100644
--- a/Modules/TestForSSTREAM.cmake
+++ b/Modules/TestForSSTREAM.cmake
@@ -5,13 +5,52 @@
 TestForSSTREAM
 --------------
 
-Test for compiler support of ANSI sstream header
+This module checks whether the C++ standard header ``<sstream>`` exists and
+functions correctly.  In early versions of C++ (pre-C++98), this header was not
+formally standardized and may not have been available.
 
-check if the compiler supports the standard ANSI sstream header
+This module defines the following cache variables:
 
-::
+``CMAKE_NO_ANSI_STRING_STREAM``
+  A cache variable indicating whether the ``<sstream>`` header is available. It
+  will be set to value ``0`` if ``<sstream>`` is available (``C++ 98`` and
+  newer), and to value ``1`` if ``<sstream>`` is missing (``ANSI C++``).
 
-  CMAKE_NO_ANSI_STRING_STREAM - defined by the results
+``CMAKE_HAS_ANSI_STRING_STREAM``
+  A cache variable that is the opposite of ``CMAKE_NO_ANSI_STRING_STREAM``
+  (true if ``<sstream>`` is available and false if ``<sstream>`` is missing).
+
+.. note::
+
+  The ``<sstream>`` header was formally introduced in the ``C++ 98`` standard,
+  making this check obsolete for modern compilers.
+
+Examples
+^^^^^^^^
+
+Including this module will check for ``<sstream>`` support and define the
+``CMAKE_NO_ANSI_STRING_STREAM`` cache variable:
+
+.. code-block:: cmake
+
+  include(TestForSSTREAM)
+  file(
+    CONFIGURE
+    OUTPUT config.h
+    CONTENT "#cmakedefine CMAKE_NO_ANSI_STRING_STREAM"
+  )
+
+Then it can be used in a C++ program:
+
+.. code-block:: c++
+
+  #include "config.h"
+
+  #ifndef CMAKE_NO_ANSI_STRING_STREAM
+  #  include <sstream>
+  #endif
+
+  int main() { ... }
 #]=======================================================================]
 
 if(NOT DEFINED CMAKE_HAS_ANSI_STRING_STREAM)