Merge topic 'doc-LINK_WHAT_YOU_USE'

e4cd54dab2 Help: Clarify intended purpose of LINK_WHAT_YOU_USE

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

Help/prop_tgt/LINK_WHAT_YOU_USE.rst

@@ -3,14 +3,15 @@ LINK_WHAT_YOU_USE
 
 .. versionadded:: 3.7
 
-This is a boolean option that, when set to ``TRUE``, will automatically run
-contents of variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` on the target
-after it is linked. In addition, the linker flag specified by variable
-:variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG`  will be passed to the target
-with the link command so that all libraries specified on the command line will
-be linked into the target. This will result in the link producing a list of
-libraries that provide no symbols used by this target but are being linked to
-it.
+This is a boolean option that, when set to ``TRUE``, adds a link-time check
+to print a list of shared libraries that are being linked but provide no symbols
+used by the target.  This is intended as a lint.
+
+The flag specified by :variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` will
+be passed to the linker so that all libraries specified on the command line
+will be linked into the target.  Then the command specified by
+:variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` will run after the target is linked
+to check the binary for unnecessarily-linked shared libraries.
 
 .. note::
 

Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst

@@ -3,7 +3,13 @@ CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG
 
 .. versionadded:: 3.22
 
-Linker flag to be used to configure linker so that all specified libraries on
-the command line will be linked into the target.
+Linker flag used by :prop_tgt:`LINK_WHAT_YOU_USE` to tell the linker to
+link all shared libraries specified on the command line even if none
+of their symbols is needed.  This is an implementation detail used so
+that the command in :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` can check
+the binary for unnecessarily-linked shared libraries.
 
-See also variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK`.
+.. note::
+
+  Do not rely on this abstraction to intentionally link to
+  shared libraries whose symbols are not needed.

Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst

@@ -3,7 +3,8 @@ CMAKE_LINK_WHAT_YOU_USE_CHECK
 
 .. versionadded:: 3.22
 
-Defines the command executed after the link step to check libraries usage.
+Command executed by :prop_tgt:`LINK_WHAT_YOU_USE` after the linker to
+check for unnecessarily-linked shared libraries.
 This check is currently only defined on ``ELF`` platforms with value
 ``ldd -u -r``.