Merge topic 'patch-FindGnuTLS'

6dff939916 FindGnuTLS: Update documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10650

Modules/FindGnuTLS.cmake

@@ -5,33 +5,80 @@
 FindGnuTLS
 ----------
 
-Find the GNU Transport Layer Security library (gnutls)
+Finds the GNU Transport Layer Security library (GnuTLS).  The GnuTLS
+package includes the main libraries (libgnutls and libdane), as well as the
+optional gnutls-openssl compatibility extra library.  They are all distributed
+as part of the same release.  This module checks for the presence of the main
+libgnutls library and provides usage requirements for integrating GnuTLS into
+CMake projects.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-.. versionadded:: 3.16
+This module provides the following :ref:`Imported Targets`:
 
-This module defines :prop_tgt:`IMPORTED` target ``GnuTLS::GnuTLS``, if
-gnutls has been found.
+``GnuTLS::GnuTLS``
+  .. versionadded:: 3.16
+
+  Target encapsulating the GnuTLS usage requirements, available if GnuTLS is
+  found.
 
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-``GNUTLS_FOUND``
-  System has gnutls
-``GNUTLS_INCLUDE_DIR``
-  The gnutls include directory
+This module defines the following variables:
+
+``GnuTLS_FOUND``
+  Boolean indicating whether the (requested version of) GnuTLS is found.  For
+  backward compatibility, the ``GNUTLS_FOUND`` variable is also set to the same
+  value.
+
+``GNUTLS_VERSION``
+  .. versionadded:: 3.16
+
+  The version of GnuTLS found.
+
+``GNUTLS_INCLUDE_DIRS``
+  Include directories needed to use GnuTLS.
+
 ``GNUTLS_LIBRARIES``
-  The libraries needed to use gnutls
+  Libraries needed to link against to use GnuTLS.
+
 ``GNUTLS_DEFINITIONS``
-  Compiler switches required for using gnutls
-``GNUTLS_VERSION``
-  version of gnutls.
-#]=======================================================================]
+  Compiler options required for using GnuTLS.
+
+Cache Variables
+^^^^^^^^^^^^^^^
 
-# Note that this doesn't try to find the gnutls-extra package.
+The following cache variables may also be set:
 
+``GNUTLS_INCLUDE_DIR``
+  The directory containing the ``gnutls/gnutls.h`` header file.
+
+``GNUTLS_LIBRARY``
+  The path to the GnuTLS library.
+
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+These variables are provided for backward compatibility:
+
+``GNUTLS_VERSION_STRING``
+  .. deprecated:: 3.16
+    Superseded by ``GNUTLS_VERSION``.
+
+  The version of GnuTLS found.
+
+Examples
+^^^^^^^^
+
+Finding GnuTLS and linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(GnuTLS)
+  target_link_libraries(project_target PRIVATE GnuTLS::GnuTLS)
+#]=======================================================================]
 
 if (GNUTLS_INCLUDE_DIR AND GNUTLS_LIBRARY)
   # in cache already
@@ -71,7 +118,7 @@ find_package_handle_standard_args(GnuTLS
                                   REQUIRED_VARS GNUTLS_LIBRARY GNUTLS_INCLUDE_DIR
                                   VERSION_VAR GNUTLS_VERSION_STRING)
 
-if(GNUTLS_FOUND)
+if(GnuTLS_FOUND)
   set(GNUTLS_LIBRARIES    ${GNUTLS_LIBRARY})
   set(GNUTLS_INCLUDE_DIRS ${GNUTLS_INCLUDE_DIR})