From 6dff9399163dd21699958cf580d0adb0f250d4bb Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Mon, 14 Apr 2025 12:47:03 +0200
Subject: FindGnuTLS: Update documentation

- Added examples section.
- Synced module documentation with other similar find modules.
- Documented some missing variables to make the result variables and
  cache variables sections consistent. The imported target is
  highlighted in the example.
- Added deprecated variables section.
- GnuTLS_FOUND variable used. GNUTLS_FOUND is also set to the same value
  as of CMake 3.3.
---
 Modules/FindGnuTLS.cmake | 77 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 62 insertions(+), 15 deletions(-)

diff --git a/Modules/FindGnuTLS.cmake b/Modules/FindGnuTLS.cmake
index 2f1033b..d9d8260 100644
--- a/Modules/FindGnuTLS.cmake
+++ b/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})
 
-- 
cgit v0.12