CheckPIESupported: Update documentation

- The module purpose explanation extended to clarify what this module
  enables and what gets configured when not using this module.
- Examples extended with include() and some minor adjustments
- Policy CMP0083 info described with a note directive

Modules/CheckPIESupported.cmake

@@ -7,10 +7,16 @@ CheckPIESupported
 
 .. versionadded:: 3.14
 
-Check whether the linker supports Position Independent Code (PIE) or No
+This module provides the ``check_pie_supported()`` function to check whether the
-Position Independent Code (NO_PIE) for executables.
+linker supports Position Independent Code (PIE) or No Position Independent Code
-Use this to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
+(NO_PIE) for executables.
-property for executables will be honored at link time.
+
+When setting the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property,
+PIC-related compile and link options are added when building library objects,
+and PIE-related compile options are added when building objects of executable
+targets, regardless of this module.  Use this module to ensure that the
+``POSITION_INDEPENDENT_CODE`` target property for executables is also honored at
+link time.
 
 .. command:: check_pie_supported
 
@@ -36,14 +42,16 @@ property for executables will be honored at link time.
 
       ``OBJC``, ``OBJCXX``, ``CUDA``, and ``HIP`` are supported.
 
-It makes no sense to use this module when :policy:`CMP0083` is set to ``OLD``,
+  .. note::
-so the command will return an error in this case.  See policy :policy:`CMP0083`
+
-for details.
+    To use ``check_pie_supported()``, policy :policy:`CMP0083` must be set to
+    ``NEW``; otherwise, a fatal error will occur.
 
 Variables
 ^^^^^^^^^
 
-For each language checked, two boolean cache variables are defined.
+For each language checked, the ``check_pie_supported()`` function defines two
+boolean cache variables:
 
  ``CMAKE_<lang>_LINK_PIE_SUPPORTED``
    Set to true if ``PIE`` is supported by the linker and false otherwise.
@@ -53,21 +61,44 @@ For each language checked, two boolean cache variables are defined.
 Examples
 ^^^^^^^^
 
+To enable PIE on an executable target at link time as well, include this module
+and call ``check_pie_supported()`` before setting the
+``POSITION_INDEPENDENT_CODE`` target property.  This will determine whether the
+linker for each checked language supports PIE-related link options.  For
+example:
+
 .. code-block:: cmake
 
+  add_executable(foo ...)
+
+  include(CheckPIESupported)
   check_pie_supported()
   set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
 
+Since not all linkers require or support PIE-related link options (for example,
+``MSVC``), retrieving any error messages might be useful for logging purposes:
+
 .. code-block:: cmake
 
-  # Retrieve any error message.
+  add_executable(foo ...)
+
+  include(CheckPIESupported)
   check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
   set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
   if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
-    message(WARNING "PIE is not supported at link time: ${output}.\n"
+    message(WARNING "PIE is not supported at link time:\n${output}"
                     "PIE link options will not be passed to linker.")
   endif()
 
+Setting the ``POSITION_INDEPENDENT_CODE`` target property on an executable
+without this module will set PIE-related compile options but not PIE-related
+link options, which might not be sufficient in certain cases:
+
+.. code-block:: cmake
+
+  add_executable(foo ...)
+  set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
+
 #]=======================================================================]