Merge topic 'deprecation'

c8e8c9cc7c Help: Date deprecation of deprecated commands.
19998d7b3c Help: Use 'deprecated' template, and date deprecation of modules
dc1bb33578 Help: Add version number to deprecation note

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2523

27 files changed, 77 insertions, 48 deletions

diff --git a/Help/command/build_name.rst b/Help/command/build_name.rst
index f717db1..2a1fbae 100644
--- a/Help/command/build_name.rst
+++ b/Help/command/build_name.rst
@@ -1,7 +1,7 @@
 build_name
 ----------
 
-Disallowed.  See CMake Policy :policy:`CMP0036`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0036`.
 
 Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.
 
diff --git a/Help/command/exec_program.rst b/Help/command/exec_program.rst
index 6dfdad3..bc9b069 100644
--- a/Help/command/exec_program.rst
+++ b/Help/command/exec_program.rst
@@ -1,7 +1,9 @@
 exec_program
 ------------
 
-Deprecated.  Use the :command:`execute_process` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`execute_process` command instead.
 
 Run an executable program during the processing of the CMakeList.txt
 file.
diff --git a/Help/command/export_library_dependencies.rst b/Help/command/export_library_dependencies.rst
index 2cb437e..9753abf 100644
--- a/Help/command/export_library_dependencies.rst
+++ b/Help/command/export_library_dependencies.rst
@@ -1,7 +1,7 @@
 export_library_dependencies
 ---------------------------
 
-Disallowed.  See CMake Policy :policy:`CMP0033`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0033`.
 
 Use :command:`install(EXPORT)` or :command:`export` command.
 
diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst
index 1850be6..f5fb46d 100644
--- a/Help/command/install_files.rst
+++ b/Help/command/install_files.rst
@@ -1,7 +1,9 @@
 install_files
 -------------
 
-Deprecated.  Use the :command:`install(FILES)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`install(FILES)` command instead.
 
 This command has been superceded by the :command:`install` command.  It is
 provided for compatibility with older CMake code.  The ``FILES`` form is
diff --git a/Help/command/install_programs.rst b/Help/command/install_programs.rst
index 79aa486..fab6482 100644
--- a/Help/command/install_programs.rst
+++ b/Help/command/install_programs.rst
@@ -1,7 +1,9 @@
 install_programs
 ----------------
 
-Deprecated. Use the :command:`install(PROGRAMS)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`install(PROGRAMS)` command instead.
 
 This command has been superceded by the :command:`install` command.  It is
 provided for compatibility with older CMake code.  The ``FILES`` form is
diff --git a/Help/command/install_targets.rst b/Help/command/install_targets.rst
index 49ca696..c9efdce 100644
--- a/Help/command/install_targets.rst
+++ b/Help/command/install_targets.rst
@@ -1,7 +1,9 @@
 install_targets
 ---------------
 
-Deprecated. Use the :command:`install(TARGETS)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`install(TARGETS)` command instead.
 
 This command has been superceded by the :command:`install` command.  It is
 provided for compatibility with older CMake code.
diff --git a/Help/command/load_command.rst b/Help/command/load_command.rst
index a1576e8..dc23599 100644
--- a/Help/command/load_command.rst
+++ b/Help/command/load_command.rst
@@ -1,7 +1,7 @@
 load_command
 ------------
 
-Disallowed.  See CMake Policy :policy:`CMP0031`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0031`.
 
 Load a command into a running CMake.
 
diff --git a/Help/command/make_directory.rst b/Help/command/make_directory.rst
index 27ecf51..8469b0a 100644
--- a/Help/command/make_directory.rst
+++ b/Help/command/make_directory.rst
@@ -1,7 +1,9 @@
 make_directory
 --------------
 
-Deprecated. Use the :command:`file(MAKE_DIRECTORY)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`file(MAKE_DIRECTORY)` command instead.
 
 ::
 
diff --git a/Help/command/output_required_files.rst b/Help/command/output_required_files.rst
index 5e13557..8bc6a73 100644
--- a/Help/command/output_required_files.rst
+++ b/Help/command/output_required_files.rst
@@ -1,7 +1,7 @@
 output_required_files
 ---------------------
 
-Disallowed.  See CMake Policy :policy:`CMP0032`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0032`.
 
 Approximate C preprocessor dependency scanning.
 
diff --git a/Help/command/remove.rst b/Help/command/remove.rst
index 4628277..543d016 100644
--- a/Help/command/remove.rst
+++ b/Help/command/remove.rst
@@ -1,7 +1,9 @@
 remove
 ------
 
-Deprecated. Use the :command:`list(REMOVE_ITEM)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`list(REMOVE_ITEM)` command instead.
 
 ::
 
diff --git a/Help/command/subdir_depends.rst b/Help/command/subdir_depends.rst
index 5676c8f..0c1b3c1 100644
--- a/Help/command/subdir_depends.rst
+++ b/Help/command/subdir_depends.rst
@@ -1,7 +1,7 @@
 subdir_depends
 --------------
 
-Disallowed.  See CMake Policy :policy:`CMP0029`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0029`.
 
 Does nothing.
 
diff --git a/Help/command/subdirs.rst b/Help/command/subdirs.rst
index 43b87d4..530951b 100644
--- a/Help/command/subdirs.rst
+++ b/Help/command/subdirs.rst
@@ -1,7 +1,9 @@
 subdirs
 -------
 
-Deprecated. Use the :command:`add_subdirectory` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`add_subdirectory` command instead.
 
 Add a list of subdirectories to the build.
 
diff --git a/Help/command/use_mangled_mesa.rst b/Help/command/use_mangled_mesa.rst
index 6f4d7ac..4d9e12b 100644
--- a/Help/command/use_mangled_mesa.rst
+++ b/Help/command/use_mangled_mesa.rst
@@ -1,7 +1,7 @@
 use_mangled_mesa
 ----------------
 
-Disallowed.  See CMake Policy :policy:`CMP0030`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0030`.
 
 Copy mesa headers for use in combination with system GL.
 
diff --git a/Help/command/utility_source.rst b/Help/command/utility_source.rst
index ee34492..94d6a4e 100644
--- a/Help/command/utility_source.rst
+++ b/Help/command/utility_source.rst
@@ -1,7 +1,7 @@
 utility_source
 --------------
 
-Disallowed.  See CMake Policy :policy:`CMP0034`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0034`.
 
 Specify the source tree of a third-party utility.
 
diff --git a/Help/command/variable_requires.rst b/Help/command/variable_requires.rst
index 9cf9f3f..b4742a5 100644
--- a/Help/command/variable_requires.rst
+++ b/Help/command/variable_requires.rst
@@ -1,7 +1,7 @@
 variable_requires
 -----------------
 
-Disallowed.  See CMake Policy :policy:`CMP0035`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0035`.
 
 Use the :command:`if` command instead.
 
diff --git a/Help/command/write_file.rst b/Help/command/write_file.rst
index 40e7557..4d476bd 100644
--- a/Help/command/write_file.rst
+++ b/Help/command/write_file.rst
@@ -1,7 +1,9 @@
 write_file
 ----------
 
-Deprecated. Use the :command:`file(WRITE)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`file(WRITE)` command instead.
 
 ::
 
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst
index 0cc5fca..aec9ba5 100644
--- a/Help/manual/cmake-commands.7.rst
+++ b/Help/manual/cmake-commands.7.rst
@@ -145,8 +145,9 @@ These commands are available only in CTest scripts.
 Deprecated Commands
 ===================
 
-These commands are available only for compatibility with older
-versions of CMake.  Do not use them in new code.
+These commands are deprecated since CMake version 3.0.
+They are available only for backward compatibility.
+Do not use them in new code.
 
 .. toctree::
    :maxdepth: 1
diff --git a/Modules/CMakeDetermineVSServicePack.cmake b/Modules/CMakeDetermineVSServicePack.cmake
index b0911b4..9edc309 100644
--- a/Modules/CMakeDetermineVSServicePack.cmake
+++ b/Modules/CMakeDetermineVSServicePack.cmake
@@ -5,7 +5,9 @@
 CMakeDetermineVSServicePack
 ---------------------------
 
-Deprecated.  Do not use.
+.. deprecated:: 3.0
+
+  Do not use.
 
 The functionality of this module has been superseded by the
 :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable that contains
@@ -170,4 +172,3 @@ function(DetermineVSServicePack _pack)
         endif()
     endif()
 endfunction()
-
diff --git a/Modules/CMakeExpandImportedTargets.cmake b/Modules/CMakeExpandImportedTargets.cmake
index 4b97c37..ae26cc2 100644
--- a/Modules/CMakeExpandImportedTargets.cmake
+++ b/Modules/CMakeExpandImportedTargets.cmake
@@ -5,7 +5,9 @@
 CMakeExpandImportedTargets
 --------------------------
 
-Deprecated.  Do not use.
+.. deprecated:: 3.4
+
+  Do not use.
 
 This module was once needed to expand imported targets to the underlying
 libraries they reference on disk for use with the :command:`try_compile`
diff --git a/Modules/CMakeForceCompiler.cmake b/Modules/CMakeForceCompiler.cmake
index ec17c2e..7ac09dc 100644
--- a/Modules/CMakeForceCompiler.cmake
+++ b/Modules/CMakeForceCompiler.cmake
@@ -5,7 +5,9 @@
 CMakeForceCompiler
 ------------------
 
-Deprecated.  Do not use.
+.. deprecated:: 3.6
+
+  Do not use.
 
 The macros provided by this module were once intended for use by
 cross-compiling toolchain files when CMake was not able to automatically
diff --git a/Modules/FindCUDA.cmake b/Modules/FindCUDA.cmake
index 2c8dd81..0f5cab4 100644
--- a/Modules/FindCUDA.cmake
+++ b/Modules/FindCUDA.cmake
@@ -2,19 +2,22 @@
 FindCUDA
 --------
 
-.. note::
-
-  The FindCUDA module has been superseded by first-class support
-  for the CUDA language in CMake.  It is no longer necessary to
-  use this module or call ``find_package(CUDA)``.  This module
-  now exists only for compatibility with projects that have not
-  been ported.
-
-  Instead, list ``CUDA`` among the languages named in the top-level
-  call to the :command:`project` command, or call the
-  :command:`enable_language` command with ``CUDA``.
-  Then one can add CUDA (``.cu``) sources to programs directly
-  in calls to :command:`add_library` and :command:`add_executable`.
+.. deprecated:: 3.10
+
+  Superseded by first-class support for the CUDA language in CMake.
+
+Replacement
+^^^^^^^^^^^
+
+It is no longer necessary to use this module or call ``find_package(CUDA)``.
+Instead, list ``CUDA`` among the languages named in the top-level
+call to the :command:`project` command, or call the
+:command:`enable_language` command with ``CUDA``.
+Then one can add CUDA (``.cu``) sources to programs directly
+in calls to :command:`add_library` and :command:`add_executable`.
+
+Documentation of Deprecated Usage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Tools for building CUDA C files: libraries and build dependencies.
 
diff --git a/Modules/FindPythonInterp.cmake b/Modules/FindPythonInterp.cmake
index 6a47c15..d1f7b31 100644
--- a/Modules/FindPythonInterp.cmake
+++ b/Modules/FindPythonInterp.cmake
@@ -5,12 +5,12 @@
 FindPythonInterp
 ----------------
 
-Find python interpreter
-
 .. deprecated:: 3.12
 
   Use :module:`FindPython3`, :module:`FindPython2` or :module:`FindPython` instead.
 
+Find python interpreter
+
 This module finds if Python interpreter is installed and determines
 where the executables are.  This code sets the following variables:
 
diff --git a/Modules/FindPythonLibs.cmake b/Modules/FindPythonLibs.cmake
index 2be5d71..1d62ac4 100644
--- a/Modules/FindPythonLibs.cmake
+++ b/Modules/FindPythonLibs.cmake
@@ -5,12 +5,12 @@
 FindPythonLibs
 --------------
 
-Find python libraries
-
 .. deprecated:: 3.12
 
   Use :module:`FindPython3`, :module:`FindPython2` or :module:`FindPython` instead.
 
+Find python libraries
+
 This module finds if Python is installed and determines where the
 include files and libraries are.  It also determines what the name of
 the library is.  This code sets the following variables:
diff --git a/Modules/FindwxWindows.cmake b/Modules/FindwxWindows.cmake
index 7f25671..35840f5 100644
--- a/Modules/FindwxWindows.cmake
+++ b/Modules/FindwxWindows.cmake
@@ -5,13 +5,15 @@
 FindwxWindows
 -------------
 
+.. deprecated:: 3.0
+
+  Replaced by :module:`FindwxWidgets`.
+
 Find wxWindows (wxWidgets) installation
 
 This module finds if wxWindows/wxWidgets is installed and determines
 where the include files and libraries are.  It also determines what
-the name of the library is.  Please note this file is DEPRECATED and
-replaced by FindwxWidgets.cmake.  This code sets the following
-variables:
+the name of the library is.  This code sets the following variables:
 
 ::
 
diff --git a/Modules/TestCXXAcceptsFlag.cmake b/Modules/TestCXXAcceptsFlag.cmake
index 75f1fc3..92a362e 100644
--- a/Modules/TestCXXAcceptsFlag.cmake
+++ b/Modules/TestCXXAcceptsFlag.cmake
@@ -5,7 +5,9 @@
 TestCXXAcceptsFlag
 ------------------
 
-Deprecated.  See :module:`CheckCXXCompilerFlag`.
+.. deprecated:: 3.0
+
+  See :module:`CheckCXXCompilerFlag`.
 
 Check if the CXX compiler accepts a flag.
 
diff --git a/Modules/Use_wxWindows.cmake b/Modules/Use_wxWindows.cmake
index f25ae89..a5e8879 100644
--- a/Modules/Use_wxWindows.cmake
+++ b/Modules/Use_wxWindows.cmake
@@ -5,9 +5,9 @@
 Use_wxWindows
 -------------
 
-Deprecated.  Use ``find_package(wxWidgets)`` and
-``include(${wxWidgets_USE_FILE})`` instead.
+.. deprecated:: 3.14
 
+  Use ``find_package(wxWidgets)`` and ``include(${wxWidgets_USE_FILE})`` instead.
 
 This convenience include finds if wxWindows is installed and set the
 appropriate libs, incdirs, flags etc.  author Jan Woetzel <jw -at-
@@ -67,4 +67,3 @@ if(WXWINDOWS_FOUND)
 else()
   message(SEND_ERROR "wxWindows not found by Use_wxWindows.cmake")
 endif()
-
diff --git a/Modules/WriteBasicConfigVersionFile.cmake b/Modules/WriteBasicConfigVersionFile.cmake
index 0ccb6b2..1f13096 100644
--- a/Modules/WriteBasicConfigVersionFile.cmake
+++ b/Modules/WriteBasicConfigVersionFile.cmake
@@ -5,7 +5,10 @@
 WriteBasicConfigVersionFile
 ---------------------------
 
+.. deprecated:: 3.0
 
+  Use the identical command :command:`write_basic_package_version_file()`
+  from module :module:`CMakePackageConfigHelpers`.
 
 ::
 
@@ -15,8 +18,6 @@ WriteBasicConfigVersionFile
     )
 
 
-
-Deprecated, see WRITE_BASIC_PACKAGE_VERSION_FILE(), it is identical.
 #]=======================================================================]
 
 function(WRITE_BASIC_CONFIG_VERSION_FILE _filename)