FindOpenGL: Update documentation

- Added intro code block showing how to use this module.
- Added examples section.
- Moved CMake versions that introduced specific target or variable
  to the item instead of above the list, as there are multiple versions
  and to have option to extend the items further in the future.
- Synced the module descriptions a bit with the other find modules.
- OpenGL_FOUND variable used (CMake 3.3). Uppercased OPENGL_FOUND is
  also set to the same value by the find_package_handle_standard_args().

Modules/FindOpenGL.cmake

@@ -5,28 +5,56 @@
 FindOpenGL
 ----------
 
-FindModule for OpenGL and OpenGL Utility Library (GLU).
+Finds the OpenGL and OpenGL Utility Library (GLU), for using OpenGL in a
+CMake project:
+
+.. code-block:: cmake
+
+  find_package(OpenGL [COMPONENTS <components>...] [...])
+
+OpenGL (Open Graphics Library) is a cross-platform API for rendering 2D and
+3D graphics.  It is widely used in CAD, games, and visualization software.
+
+* *GL* refers to the core OpenGL library, which provides the fundamental
+  graphics rendering API.
+
+* *GLU* (OpenGL Utility Library) is a companion library that offers utility
+  functions built on top of OpenGL, such as tessellation and more complex
+  shape drawing.
 
 .. versionchanged:: 3.2
   X11 is no longer added as a dependency on Unix/Linux systems.
 
 .. versionadded:: 3.10
-  GLVND support on Linux.  See the :ref:`Linux Specific` section below.
+  GLVND (GL Vendor-Neutral Dispatch library) support on Linux.  See the
+  :ref:`Linux Specific` section below.
 
-Optional COMPONENTS
-^^^^^^^^^^^^^^^^^^^
+Components
+^^^^^^^^^^
 
-.. versionadded:: 3.10
+This module supports optional components which can be specified with the
+:command:`find_package` command:
+
+.. code-block:: cmake
 
-This module respects several optional COMPONENTS:
+  find_package(OpenGL [COMPONENTS <components>...])
+
+Supported components are:
 
 ``EGL``
-  The EGL interface between OpenGL, OpenGL ES and the underlying windowing system.
+  .. versionadded:: 3.10
+
+  The EGL interface between OpenGL, OpenGL ES and the underlying windowing
+  system.
 
 ``GLX``
+  .. versionadded:: 3.10
+
   An extension to X that interfaces OpenGL, OpenGL ES with X window system.
 
 ``OpenGL``
+  .. versionadded:: 3.10
+
   The cross platform API for 3D graphics.
 
 ``GLES2``
@@ -42,103 +70,177 @@ This module respects several optional COMPONENTS:
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-.. versionadded:: 3.8
-
-This module defines the :prop_tgt:`IMPORTED` targets:
+This module provides the following :ref:`Imported Targets`:
 
 ``OpenGL::GL``
-  Defined to the platform-specific OpenGL libraries if the system has OpenGL.
+  .. versionadded:: 3.8
+
+  Target encapsulating the usage requirements of platform-specific OpenGL
+  libraries, available if OpenGL is found.
+
 ``OpenGL::GLU``
-  Defined if the system has OpenGL Utility Library (GLU).
+  .. versionadded:: 3.8
 
-.. versionadded:: 3.10
-  Additionally, the following GLVND-specific library targets are defined:
+  Target encapsulating the OpenGL Utility Library (GLU) usage requirements,
+  available if GLU is found.
+
+Additionally, the following GLVND-specific library imported targets are
+provided:
 
 ``OpenGL::OpenGL``
-  Defined to libOpenGL if the system is GLVND-based.
+  .. versionadded:: 3.10
+
+  Target encapsulating the libOpenGL usage requirements, available if
+  system is GLVND-based and OpenGL is found.
+
 ``OpenGL::GLX``
-  Defined if the system has OpenGL Extension to the X Window System (GLX).
+  .. versionadded:: 3.10
+
+  Target encapsulating the usage requirements of the OpenGL Extension to the
+  the X Window System (GLX), available if OpenGL and GLX are found.
+
 ``OpenGL::EGL``
-  Defined if the system has EGL.
+  .. versionadded:: 3.10
+
+  Target encapsulating the EGL usage requirements, available if OpenGL and EGL
+  are found.
+
 ``OpenGL::GLES2``
   .. versionadded:: 3.27
 
-  Defined if the system has GLES2.
+  Target encapsulating the GLES2 usage requirements, available if OpenGL and
+  GLES2 are found.
+
 ``OpenGL::GLES3``
   .. versionadded:: 3.27
 
-  Defined if the system has GLES3.
+  Target encapsulating the GLES3 usage requirements, available if OpenGL and
+  GLES3 are found.
 
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
+
+``OpenGL_FOUND``
+  .. versionadded:: 3.3
+
+  Boolean indicating whether the OpenGL and all requested components are found.
 
-``OPENGL_FOUND``
- True, if the system has OpenGL and all components are found.
 ``OPENGL_XMESA_FOUND``
- True, if the system has XMESA.
+  Boolean indicating whether OpenGL XMESA is found.
+
 ``OPENGL_GLU_FOUND``
- True, if the system has GLU.
+  Boolean indicating whether GLU is found.
+
 ``OpenGL_OpenGL_FOUND``
- True, if the system has an OpenGL library.
+  .. versionadded:: 3.10
+
+  Boolean indicating whether GLVND OpenGL library is found.
+
 ``OpenGL_GLX_FOUND``
- True, if the system has GLX.
+  .. versionadded:: 3.10
+
+  Boolean indicating whether GLVND GLX is found.
+
 ``OpenGL_EGL_FOUND``
- True, if the system has EGL.
-``OpenGL::GLES2``
- Defined if the system has GLES2.
-``OpenGL::GLES3``
- Defined if the system has GLES3.
-``OPENGL_INCLUDE_DIR``
- Path to the OpenGL include directory.
- The ``OPENGL_INCLUDE_DIRS`` variable is preferred.
-``OPENGL_EGL_INCLUDE_DIRS``
- Path to the EGL include directory.
-``OPENGL_LIBRARIES``
- Paths to the OpenGL library, windowing system libraries, and GLU libraries.
- On Linux, this assumes GLX and is never correct for EGL-based targets.
- Clients are encouraged to use the ``OpenGL::*`` import targets instead.
+  .. versionadded:: 3.10
+
+  Boolean indicating whether GLVND EGL is found.
+
+``OpenGL_GLES2_FOUND``
+  .. versionadded:: 3.27
+
+  Boolean indicating whether GLES2 is found.
+
+``OpenGL_GLES3_FOUND``
+  .. versionadded:: 3.27
+
+  Boolean indicating whether GLES3 is found.
+
 ``OPENGL_INCLUDE_DIRS``
   .. versionadded:: 3.29
 
   Paths to the OpenGL include directories.
 
-.. versionadded:: 3.10
-  Variables for GLVND-specific libraries ``OpenGL``, ``EGL`` and ``GLX``.
+``OPENGL_EGL_INCLUDE_DIRS``
+  .. versionadded:: 3.10
+
+  Path to the EGL include directory.
 
-Cache variables
+``OPENGL_LIBRARIES``
+  Paths to the OpenGL library, windowing system libraries, and GLU libraries.
+  On Linux, this assumes GLX and is never correct for EGL-based targets.
+  Clients are encouraged to use the ``OpenGL::*`` imported targets instead.
+
+Cache Variables
 ^^^^^^^^^^^^^^^
 
 The following cache variables may also be set:
 
+``OPENGL_INCLUDE_DIR``
+  The path to the OpenGL include directory.
+  The ``OPENGL_INCLUDE_DIRS`` variable is preferred.
+
+``OPENGL_GLU_INCLUDE_DIR``
+  .. versionadded:: 3.29
+
+  Path to the OpenGL GLU include directory.
+
 ``OPENGL_egl_LIBRARY``
- Path to the EGL library.
+  .. versionadded:: 3.10
+
+  Path to the GLVND EGL library.
+
 ``OPENGL_glu_LIBRARY``
- Path to the GLU library.
+  Path to the GLU library.
+
 ``OPENGL_glx_LIBRARY``
- Path to the GLVND 'GLX' library.
+  .. versionadded:: 3.10
+
+  Path to the GLVND GLX library.
+
 ``OPENGL_opengl_LIBRARY``
- Path to the GLVND 'OpenGL' library
+  .. versionadded:: 3.10
+
+  Path to the GLVND OpenGL library
+
 ``OPENGL_gl_LIBRARY``
- Path to the OpenGL library.  New code should prefer the ``OpenGL::*`` import
- targets.
+  Path to the OpenGL library.
+
 ``OPENGL_gles2_LIBRARY``
   .. versionadded:: 3.27
 
   Path to the OpenGL GLES2 library.
+
 ``OPENGL_gles3_LIBRARY``
   .. versionadded:: 3.27
 
   Path to the OpenGL GLES3 library.
 
-``OPENGL_GLU_INCLUDE_DIR``
-  .. versionadded:: 3.29
+Hints
+^^^^^
 
-  Path to the OpenGL GLU include directory.
+This module accepts the following variables:
 
-.. versionadded:: 3.10
-  Variables for GLVND-specific libraries ``OpenGL``, ``EGL`` and ``GLX``.
+``OpenGL_GL_PREFERENCE``
+  .. versionadded:: 3.10
+
+  This variable is supported on Linux systems to specify the preferred way to
+  provide legacy GL interfaces in case multiple choices are available.  The
+  value may be one of:
+
+  ``GLVND``
+    If the GLVND OpenGL and GLX libraries are available, prefer them.
+    This forces ``OPENGL_gl_LIBRARY`` to be empty.
+
+    .. versionchanged:: 3.11
+      This is the default, unless policy :policy:`CMP0072` is set to ``OLD``
+      and no components are requested (since components
+      correspond to GLVND libraries).
+
+  ``LEGACY``
+    Prefer to use the legacy libGL library, if available.
 
 .. _`Linux Specific`:
 
@@ -160,21 +262,8 @@ not found and GLVND is available, the ``OpenGL::GL`` target will use GLVND
 variable will use the corresponding libraries).  Thus, for non-EGL-based
 Linux targets, the ``OpenGL::GL`` target is most portable.
 
-A ``OpenGL_GL_PREFERENCE`` variable may be set to specify the preferred way
+The ``OpenGL_GL_PREFERENCE`` variable may be set to specify the preferred way
 to provide legacy GL interfaces in case multiple choices are available.
-The value may be one of:
-
-``GLVND``
- If the GLVND OpenGL and GLX libraries are available, prefer them.
- This forces ``OPENGL_gl_LIBRARY`` to be empty.
-
- .. versionchanged:: 3.11
-  This is the default, unless policy :policy:`CMP0072` is set to ``OLD``
-  and no components are requested (since components
-  correspond to GLVND libraries).
-
-``LEGACY``
- Prefer to use the legacy libGL library, if available.
 
 For EGL targets the client must rely on GLVND support on the user's system.
 Linking should use the ``OpenGL::OpenGL OpenGL::EGL`` targets.  Using GLES*
@@ -189,7 +278,8 @@ macOS-Specific
 
 On macOS this module defaults to using the macOS-native framework
 version of OpenGL.  To use the X11 version of OpenGL on macOS, one
-can disable searching of frameworks.  For example:
+can disable searching of frameworks using the :variable:`CMAKE_FIND_FRAMEWORK`
+variable.  For example:
 
 .. code-block:: cmake
 
@@ -205,6 +295,33 @@ can disable searching of frameworks.  For example:
 An end user building this project may need to point CMake at their
 X11 installation, e.g., with ``-DOpenGL_ROOT=/opt/X11``.
 
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``OPENGL_FOUND``
+  .. deprecated:: 3.3
+    Superseded by the ``OpenGL_FOUND``, which has the same value.
+
+Examples
+^^^^^^^^
+
+Finding the OpenGL library and linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(OpenGL)
+  target_link_libraries(project_target PRIVATE OpenGL::OpenGL)
+
+See Also
+^^^^^^^^
+
+* The :module:`FindGLEW` module to find OpenGL Extension Wrangler Library
+  (GLEW).
+* The :module:`FindGLUT` module to find OpenGL Utility Toolkit (GLUT)
+  library.
+* The :module:`FindVulkan` module to find Vulkan graphics API.
 #]=======================================================================]
 
 set(_OpenGL_REQUIRED_VARS OPENGL_gl_LIBRARY)
@@ -582,7 +699,7 @@ unset(FPHSA_NAME_MISMATCHED)
 unset(_OpenGL_REQUIRED_VARS)
 
 # OpenGL:: targets
-if(OPENGL_FOUND)
+if(OpenGL_FOUND)
   set(OPENGL_INCLUDE_DIRS ${OPENGL_INCLUDE_DIR})
 
   # ::OpenGL is a GLVND library, and thus Linux-only: we don't bother checking