From eecc3d545bcefbf574e76174b18fd9edb611a2bf Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Mon, 21 Apr 2025 13:37:45 +0200
Subject: [PATCH] FindGLUT: Update documentation

- Synced module documentation with other similar find modules.
- Added examples section.
- Refactored the obsolete variables section to only mention in the
  result variables that GLUT_INCLUDE_DIRS should be used instead of
  the previously misused cache variable GLUT_INCLUDE_DIR. The
  GLUT_INCLUDE_DIR as such is not actually deprecated/obsolete as it is
  still used to find GLUT (only its previous usage way is
  changed/obsolete).
---
 Modules/FindGLUT.cmake | 52 +++++++++++++++++++++++-------------------
 1 file changed, 28 insertions(+), 24 deletions(-)

diff --git a/Modules/FindGLUT.cmake b/Modules/FindGLUT.cmake
index 3704e85a26..e29758dc1c 100644
--- a/Modules/FindGLUT.cmake
+++ b/Modules/FindGLUT.cmake
@@ -5,17 +5,18 @@
 FindGLUT
 --------
 
-Find OpenGL Utility Toolkit (GLUT) library and include files.
+Finds the OpenGL Utility Toolkit (GLUT) library, which provides a simple API for
+creating windows, handling input, and managing events in OpenGL applications.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-.. versionadded:: 3.1
-
-This module defines the :prop_tgt:`IMPORTED` targets:
+This module provides the following :ref:`Imported Targets`:
 
 ``GLUT::GLUT``
- Defined if the system has GLUT.
+  .. versionadded:: 3.1
+
+  Target encapsulating the GLUT usage requirements, available if GLUT is found.
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -23,45 +24,48 @@ Result Variables
 This module defines the following variables:
 
 ``GLUT_FOUND``
-  True if ``glut`` was found.
+  Boolean indicating whether GLUT is found.
 
 ``GLUT_INCLUDE_DIRS``
   .. versionadded:: 3.23
 
-  Where to find GL/glut.h, etc.
+  Include directories needed to use GLUT.  Starting with CMake 3.23, this
+  variable is intended to be used in target usage requirements instead of the
+  cache variable ``GLUT_INCLUDE_DIR``, which is intended for finding GLUT.
 
 ``GLUT_LIBRARIES``
-  List of libraries for using ``glut``.
+  List of libraries needed to link against for using GLUT.
 
 Cache Variables
 ^^^^^^^^^^^^^^^
 
-This module may set the following variables depending on platform.
+This module may set the following cache variables depending on platform.
 These variables may optionally be set to help this module find the
-correct files, but clients should not use these as results:
+correct files, but should not be used as result variables:
 
 ``GLUT_INCLUDE_DIR``
-  The full path to the directory containing ``GL/glut.h``,
-  not including ``GL/``.
+  The full path to the directory containing ``GL/glut.h`` (without the ``GL/``).
 
 ``GLUT_glut_LIBRARY``
-  The full path to the glut library.
-
-``GLUT_Xmu_LIBRARY``
-  The full path to the Xmu library.
+  The full path to the ``glut`` library.
 
 ``GLUT_Xi_LIBRARY``
-  The full path to the Xi Library.
+  The full path to the dependent ``Xi`` (X Input Device Extension) library on
+  some systems.
 
-Obsolete Variables
-^^^^^^^^^^^^^^^^^^
+``GLUT_Xmu_LIBRARY``
+  The full path to the dependent ``Xmu`` (X Miscellaneous Utilities) library on
+  some systems.
 
-The following variables may also be provided, for backwards compatibility:
+Examples
+^^^^^^^^
 
-``GLUT_INCLUDE_DIR``
-  This is one of above `Cache Variables`_, but prior to CMake 3.23 was
-  also a result variable.  Prefer to use ``GLUT_INCLUDE_DIRS`` instead
-  in CMake 3.23 and above.
+Finding GLUT and linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(GLUT)
+  target_link_libraries(project_target PRIVATE GLUT::GLUT)
 #]=======================================================================]
 
 include(${CMAKE_CURRENT_LIST_DIR}/SelectLibraryConfigurations.cmake)