TestForANSIStreamHeaders: Update documentation

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

Modules/TestForANSIStreamHeaders.cmake

@@ -5,14 +5,52 @@
 TestForANSIStreamHeaders
 ------------------------
 
-Test for compiler support of ANSI stream headers iostream, etc.
+This module checks whether the ``CXX`` compiler supports standard library
+headers without the ``.h`` extension (e.g. ``<iostream>``).  Early
+versions of C++ (pre-C++98) didn't support including standard headers without
+extensions.
 
-check if the compiler supports the standard ANSI iostream header
+This module defines the following cache variable:
-(without the .h)
 
-::
+``CMAKE_NO_ANSI_STREAM_HEADERS``
+  A cache variable containing the result of the check.  It will be set to value
+  ``0`` if the standard headers can be included without the ``.h`` extension
+  (``C++ 98`` and newer), and to value ``1`` if ``.h`` is required
+  (``ANSI C++``).
 
-  CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
+.. note::
+
+  The C++ standard headers without extensions got formally introduced in the
+  ``C++ 98`` standard, making this issue obsolete.
+
+Examples
+^^^^^^^^
+
+Including this module will check how the C++ standard headers can be included
+and define the ``CMAKE_NO_ANSI_STREAM_HEADERS`` cache variable:
+
+.. code-block:: cmake
+
+  include(TestForANSIStreamHeaders)
+  file(
+    CONFIGURE
+    OUTPUT config.h
+    CONTENT "#cmakedefine CMAKE_NO_ANSI_STREAM_HEADERS"
+  )
+
+C++ program can then include the available header conditionally:
+
+.. code-block:: c++
+
+  #include "config.h"
+
+  #ifdef CMAKE_NO_ANSI_STREAM_HEADERS
+  #  include <iostream.h>
+  #else
+  #  include <iostream>
+  #endif
+
+  int main() { ... }
 #]=======================================================================]
 
 include(${CMAKE_CURRENT_LIST_DIR}/CheckIncludeFileCXX.cmake)