Help: Enhance UseSWIG module documentation

* Add section headings
* Add TOC (HTML only)
* Move `swig_link_libraries()` to "Deprecated commands"
  section at end of docs, document as deprecated in favor of
  `target_link_libraries()` in all cases.

1 files changed, 47 insertions, 15 deletions

diff --git a/Modules/UseSWIG.cmake b/Modules/UseSWIG.cmake
index e0e01f5..ca16bc2 100644
--- a/Modules/UseSWIG.cmake
+++ b/Modules/UseSWIG.cmake
@@ -8,7 +8,14 @@ UseSWIG
 This file provides support for ``SWIG``. It is assumed that :module:`FindSWIG`
 module has already been loaded.
 
-Defines the following command for use with ``SWIG``:
+.. only:: html
+
+  .. contents::
+
+CMake Commands
+^^^^^^^^^^^^^^
+
+The following command is defined for use with ``SWIG``:
 
 .. command:: swig_add_library
 
@@ -125,20 +132,8 @@ Defines the following command for use with ``SWIG``:
     to prevent interference between targets or losing other important files,
     each target should have its own dedicated output directory.
 
-.. command:: swig_link_libraries
-
-  Link libraries to swig module::
-
-    swig_link_libraries(<name> <item>...)
-
-  This command has same capabilities as :command:`target_link_libraries`
-  command.
-
-  .. note::
-
-    If variable ``UseSWIG_TARGET_NAME_PREFERENCE`` is set to ``STANDARD``, this
-    command is deprecated and :command:`target_link_libraries` command must be
-    used instead.
+Properties on Source Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Source file properties on module files **must** be set before the invocation
 of the ``swig_add_library`` command to specify special behavior of SWIG and
@@ -233,6 +228,9 @@ ensure generated files will receive the required settings.
   other ways to define output file directory applies (see ``OUTFILE_DIR``
   option of ``swig_add_library()`` command).
 
+Properties on Targets
+^^^^^^^^^^^^^^^^^^^^^
+
 Target library properties can be set to apply same configuration to all SWIG
 input files.
 
@@ -271,6 +269,9 @@ input files.
 
   Add dependencies to all SWIG input files.
 
+Read-only Target Properties
+"""""""""""""""""""""""""""
+
 The following target properties are output properties and can be used to get
 information about support files generated by ``SWIG`` interface compilation.
 
@@ -303,6 +304,9 @@ information about support files generated by ``SWIG`` interface compilation.
     When source property ``OUTPUT_DIR`` is defined, multiple directories can be
     specified as part of ``SWIG_SUPPORT_FILES_DIRECTORY``.
 
+CMake Variables
+^^^^^^^^^^^^^^^
+
 Some variables can be set to customize the behavior of ``swig_add_library``
 as well as ``SWIG``:
 
@@ -361,6 +365,34 @@ as well as ``SWIG``:
   .. versionadded:: 3.22
     Added the support of :ref:`Visual Studio Generators`.
 
+Deprecated Commands
+^^^^^^^^^^^^^^^^^^^
+
+.. command:: swig_link_libraries
+
+  .. deprecated:: 3.13
+    Use :command:`target_link_libraries` with the standard target name,
+    or with ``${SWIG_MODULE_<name>_REAL_NAME}`` for legacy target naming.
+
+  Link libraries to swig module::
+
+    swig_link_libraries(<name> <item>...)
+
+  This command has same capabilities as :command:`target_link_libraries`
+  command.
+
+  .. note::
+    When policy :policy:`CMP0078` is set to ``NEW``,
+    :command:`swig_add_library` creates a standard target with the
+    specified ``<name>`` and :command:`target_link_libraries` must be used
+    instead of this command.
+
+    With the legacy behavior (when :policy:`CMP0078` is set to ``OLD`` and
+    the ``UseSWIG_TARGET_NAME_PREFERENCE`` variable is set to ``"LEGACY"``,
+    or in CMake versions prior to 3.12), it is preferable to use
+    ``target_link_libraries(${SWIG_MODULE_<name>_REAL_NAME} ...)``
+    instead of this command.
+
 #]=======================================================================]
 
 cmake_policy(PUSH)