Merge topic 'patch-Use_wxWindows'

14334d7604 Use_wxWindows: Update documentation

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

Modules/FindwxWindows.cmake

@@ -11,7 +11,11 @@ FindwxWindows
 
 Finds the wxWidgets (formerly known as wxWindows) installation and determines
 the locations of its include directories and libraries, as well as the name of
-the library.
+the library:
+
+.. code-block:: cmake
+
+  find_package(wxWindows [...])
 
 wxWidgets 2.6.x is supported for monolithic builds, such as those compiled in
 the ``wx/build/msw`` directory using:
@@ -57,7 +61,7 @@ This module accepts the following variables before calling the
 Deprecated Variables
 ^^^^^^^^^^^^^^^^^^^^
 
-These variables are provided for backward compatibility:
+The following variables are provided for backward compatibility:
 
 ``CMAKE_WX_CAN_COMPILE``
   .. deprecated:: 1.8
@@ -78,7 +82,7 @@ These variables are provided for backward compatibility:
 Examples
 ^^^^^^^^
 
-Example: Finding wxWidgets in earlier CMake versions
+Example: Finding wxWidgets in Earlier CMake Versions
 """"""""""""""""""""""""""""""""""""""""""""""""""""
 
 In earlier versions of CMake, wxWidgets (wxWindows) could be found using:

Modules/Use_wxWindows.cmake

@@ -7,28 +7,54 @@ Use_wxWindows
 
 .. deprecated:: 2.8.10
 
-  Use :module:`find_package(wxWidgets) <FindwxWidgets>` instead.
+  This module should no longer be used.  Use :module:`find_package(wxWidgets)
+  <FindwxWidgets>` instead.
 
-This convenience include finds if wxWindows library is installed and sets the
-appropriate libraries, include directories, flags, etc.
+This module serves as a convenience wrapper for finding the wxWidgets library
+(formerly known as wxWindows) and propagates its usage requirements, such as
+libraries, include directories, and compiler flags, into the current directory
+scope for use by targets.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(Use_wxWindows)
 
 Examples
 ^^^^^^^^
 
-Include ``Use_wxWindows`` module in project's ``CMakeLists.txt``:
+In earlier versions of CMake, wxWidgets (wxWindows) could be found and used in
+the current directory like this:
 
 .. code-block:: cmake
+  :caption: ``CMakeLists.txt``
 
-  # CMakeLists.txt
   include(Use_wxWindows)
 
-When the GL support is required, set ``WXWINDOWS_USE_GL`` *before* including
-this module:
+To request OpenGL support, the ``WXWINDOWS_USE_GL`` variable could be set before
+including this module:
 
 .. code-block:: cmake
+  :caption: ``CMakeLists.txt``
 
   set(WXWINDOWS_USE_GL ON)
   include(Use_wxWindows)
+
+  add_library(example example.cxx)
+
+Starting with CMake 3.0, wxWidgets can be found using the
+:module:`FindwxWidgets` module, which provides the wxWidgets usage requirements
+either using result variables or imported target as of CMake 3.27:
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt``
+
+  find_package(wxWidgets)
+
+  add_library(example example.cxx)
+
+  target_link_libraries(example PRIVATE wxWidgets::wxWidgets)
 #]=======================================================================]
 
 # Author: Jan Woetzel <jw -at- mip.informatik.uni-kiel.de> (07/2003)