UsewxWidgets, Use_wxWindows: Update documentation

UsewxWidgets:
- Module description updated according to current code
- Mention of the link_libraries() command removed as it was always
  commented out and never used in this specific module file
- Added example, how to use IMPORTED target of the found package instead
  of this module - preparing it for deprecation in the future

Use_wxWindows:
- Mention of the UsewxWidgets module removed
- The STATUS message changed to DEPRECATION and message simplified

Modules/Use_wxWindows.cmake

@@ -7,39 +7,41 @@ Use_wxWindows
 
 .. deprecated:: 2.8.10
 
-  Use ``find_package(wxWidgets)`` and ``include(${wxWidgets_USE_FILE})`` instead.
+  Use :module:`find_package(wxWidgets) <FindwxWidgets>` instead.
 
-This convenience include finds if wxWindows is installed and set the
-appropriate libs, incdirs, flags etc.  author Jan Woetzel <jw -at-
-mip.informatik.uni-kiel.de> (07/2003)
+This convenience include finds if wxWindows library is installed and sets the
+appropriate libraries, include directories, flags, etc.
 
-USAGE:
+Examples
+^^^^^^^^
 
-::
+Include ``Use_wxWindows`` module in project's ``CMakeLists.txt``:
 
-   just include Use_wxWindows.cmake
-   in your projects CMakeLists.txt
+.. code-block:: cmake
 
-include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
+  # CMakeLists.txt
+  include(Use_wxWindows)
 
-::
+When the GL support is required, set ``WXWINDOWS_USE_GL`` *before* including
+this module:
 
-   if you are sure you need GL then
+.. code-block:: cmake
 
-set(WXWINDOWS_USE_GL 1)
-
-::
-
-   *before* you include this file.
+  set(WXWINDOWS_USE_GL ON)
+  include(Use_wxWindows)
 #]=======================================================================]
 
+# Author: Jan Woetzel <jw -at- mip.informatik.uni-kiel.de> (07/2003)
+
 # -----------------------------------------------------
 # 16.Feb.2004: changed INCLUDE to FIND_PACKAGE to read from users own non-system CMAKE_MODULE_PATH (Jan Woetzel JW)
 # 07/2006: rewrite as FindwxWidgets.cmake, kept for backward compatibility JW
 
-message(STATUS "Use_wxWindows.cmake is DEPRECATED. \n"
-"Please use find_package(wxWidgets) and include(${wxWidgets_USE_FILE}) instead. (JW)")
-
+message(
+  DEPRECATION
+  "Use_wxWindows module is DEPRECATED.\n"
+  "Please use find_package(wxWidgets) instead. (JW)"
+)
 
 # ------------------------
 

Modules/UsewxWidgets.cmake

@@ -5,39 +5,46 @@
 UsewxWidgets
 ------------
 
-Convenience include for using wxWidgets library.
+This module calls :command:`include_directories` and
+:command:`link_directories`, sets compile definitions for the current directory
+and appends some compile flags to use wxWidgets library after calling the
+:module:`find_package(wxWidgets) <FindwxWidgets>`.
 
-Determines if wxWidgets was FOUND and sets the appropriate libs,
-incdirs, flags, etc.  INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
-called.
+Examples
+^^^^^^^^
 
-USAGE
+Include ``UsewxWidgets`` module in project's ``CMakeLists.txt``:
 
 .. code-block:: cmake
 
-  # Note that for MinGW users the order of libs is important!
+  # Note that for MinGW users the order of libraries is important.
   find_package(wxWidgets REQUIRED net gl core base)
-  include(${wxWidgets_USE_FILE})
-  # and for each of your dependent executable/library targets:
-  target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
-
-
-
-DEPRECATED
 
-::
-
-  LINK_LIBRARIES is not called in favor of adding dependencies per target.
+  # Above also sets the wxWidgets_USE_FILE variable that points to this module.
+  include(${wxWidgets_USE_FILE})
 
+  # Link wxWidgets libraries for each dependent executable/library target.
+  target_link_libraries(<ProjectTarget> ${wxWidgets_LIBRARIES})
 
+As of CMake 3.27, a better approach is to link only the
+:module:`wxWidgets::wxWidgets <FindwxWidgets>` ``IMPORTED`` target to specific
+targets that require it, rather than including this module. Imported targets
+provide better control of the package usage properties, such as include
+directories and compile flags, by applying them only to the targets they are
+linked to, avoiding unnecessary propagation to all targets in the current
+directory.
 
-AUTHOR
+.. code-block:: cmake
 
-::
+  # CMakeLists.txt
+  find_package(wxWidgets)
 
-  Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
+  # Link the imported target for each dependent executable/library target.
+  target_link_libraries(<ProjectTarget> wxWidgets::wxWidgets)
 #]=======================================================================]
 
+# Author: Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
+
 if   (wxWidgets_FOUND)
   if   (wxWidgets_INCLUDE_DIRS)
     if(wxWidgets_INCLUDE_DIRS_NO_SYSTEM)