FindPostgreSQL: Update documentation

- Added examples section.
- Updated and synced descriptions.
- Added CMake version 3.20 that introduced the Server component.

Modules/FindPostgreSQL.cmake

@@ -5,41 +5,97 @@
 FindPostgreSQL
 --------------
 
-Find the PostgreSQL installation.
+Finds the PostgreSQL installation - the client library (``libpq``) and
+optionally the server.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-.. versionadded:: 3.14
+This module provides the following :ref:`Imported Targets`:
 
-This module defines :prop_tgt:`IMPORTED` target ``PostgreSQL::PostgreSQL``
-if PostgreSQL has been found.
+``PostgreSQL::PostgreSQL``
+  .. versionadded:: 3.14
+
+  Target encapsulating all usage requirements of the required ``libpq`` client
+  library and the optionally requested PostgreSQL server component.  This target
+  is available only if PostgreSQL is found.
 
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module will set the following variables in your project:
+This module defines the following variables:
 
 ``PostgreSQL_FOUND``
-  True if PostgreSQL is found.
+  Boolean indicating whether the minimum required version and components of
+  PostgreSQL have been found.
 ``PostgreSQL_LIBRARIES``
-  the PostgreSQL libraries needed for linking
+  The PostgreSQL libraries needed for linking.
 ``PostgreSQL_INCLUDE_DIRS``
-  the directories of the PostgreSQL headers
+  The include directories containing PostgreSQL headers.
 ``PostgreSQL_LIBRARY_DIRS``
-  the link directories for PostgreSQL libraries
+  The directories containing PostgreSQL libraries.
 ``PostgreSQL_VERSION_STRING``
-  the version of PostgreSQL found
+  The version of PostgreSQL found.
 ``PostgreSQL_TYPE_INCLUDE_DIR``
-  the directories of the PostgreSQL server headers
+  The include directory containing PostgreSQL server headers.
 
 Components
 ^^^^^^^^^^
 
-This module contains additional ``Server`` component, that forcibly checks
-for the presence of server headers. Note that ``PostgreSQL_TYPE_INCLUDE_DIR``
-is set regardless of the presence of the ``Server`` component in find_package call.
+This module supports the following additional components:
 
+``Server``
+  .. versionadded:: 3.20
+
+  Ensures that server headers are also found.  Note that
+  ``PostgreSQL_TYPE_INCLUDE_DIR`` variable is set regardless of whether this
+  component is specified in the ``find_package()`` call.
+
+Examples
+^^^^^^^^
+
+Finding the PostgreSQL client library and linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(PostgreSQL)
+  target_link_libraries(project_target PRIVATE PostgreSQL::PostgreSQL)
+
+Specifying a minimum required PostgreSQL version:
+
+.. code-block:: cmake
+
+  find_package(PostgreSQL 11)
+
+Finding the PostgreSQL client library and requiring server headers using the
+``Server`` component provides an imported target with all usage requirements,
+which can then be linked to a project target:
+
+.. code-block:: cmake
+
+  find_package(PostgreSQL COMPONENTS Server)
+  target_link_libraries(project_target PRIVATE PostgreSQL::PostgreSQL)
+
+When checking for PostgreSQL client library features, some capabilities are
+indicated by preprocessor macros in the ``libpq-fe.h`` header (e.g.
+``LIBPQ_HAS_PIPELINING``).  Others may require using the
+:command:`check_symbol_exists` command:
+
+.. code-block:: cmake
+
+  find_package(PostgreSQL)
+  target_link_libraries(project_target PRIVATE PostgreSQL::PostgreSQL)
+
+  # The PQservice() function is available as of PostgreSQL 18.
+  if(TARGET PostgreSQL::PostgreSQL)
+    include(CheckSymbolExists)
+    include(CMakePushCheckState)
+
+    cmake_push_check_state(RESET)
+    set(CMAKE_REQUIRED_LIBRARIES PostgreSQL::PostgreSQL)
+    check_symbol_exists(PQservice "libpq-fe.h" PROJECT_HAS_PQSERVICE)
+    cmake_pop_check_state()
+  endif()
 #]=======================================================================]
 
 # ----------------------------------------------------------------------------