Merge topic 'doc-pdb-not-for-static-libs'

c0897cf Help: Document PDB behavior w.r.t. static libraries explicitly (#14600)
09c05f3 Help: Format PDB_NAME and PDB_OUTPUT_DIRECTORY documentation
cb7b907 Help: Document CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> variable

5 files changed, 38 insertions, 19 deletions

diff --git a/Help/prop_tgt/PDB_NAME.rst b/Help/prop_tgt/PDB_NAME.rst
index fe059e06fc..e8fc3be522 100644
--- a/Help/prop_tgt/PDB_NAME.rst
+++ b/Help/prop_tgt/PDB_NAME.rst
@@ -1,10 +1,13 @@
 PDB_NAME
 --------
 
-Output name for MS debug symbols .pdb file from linker.
+Output name for the MS debug symbol ``.pdb`` file generated by the
+linker for an executable or shared library target.
 
-Set the base name for debug symbols file created for an executable or
-shared library target.  If not set, the logical target name is used by
-default.
+This property specifies the base name for the debug symbols file.
+If not set, the logical target name is used by default.
 
-This property is not implemented by the Visual Studio 6 generator.
+.. include:: PDB_NOTE.txt
+
+This property is not implemented by the :generator:`Visual Studio 6`
+generator.
diff --git a/Help/prop_tgt/PDB_NAME_CONFIG.rst b/Help/prop_tgt/PDB_NAME_CONFIG.rst
index 50c3aa294b..c846b57d15 100644
--- a/Help/prop_tgt/PDB_NAME_CONFIG.rst
+++ b/Help/prop_tgt/PDB_NAME_CONFIG.rst
@@ -1,8 +1,10 @@
 PDB_NAME_<CONFIG>
 -----------------
 
-Per-configuration name for MS debug symbols .pdb file.
+Per-configuration output name for the MS debug symbol ``.pdb`` file
+generated by the linker for an executable or shared library target.
 
-This is the configuration-specific version of PDB_NAME.
+This is the configuration-specific version of :prop_tgt:`PDB_NAME`.
 
-This property is not implemented by the Visual Studio 6 generator.
+This property is not implemented by the :generator:`Visual Studio 6`
+generator.
diff --git a/Help/prop_tgt/PDB_NOTE.txt b/Help/prop_tgt/PDB_NOTE.txt
new file mode 100644
index 0000000000..e55aba2850
--- /dev/null
+++ b/Help/prop_tgt/PDB_NOTE.txt
@@ -0,0 +1,8 @@
+.. note::
+ This property does not apply to STATIC library targets because no linker
+ is invoked to produce them so they have no linker-generated ``.pdb`` file
+ containing debug symbols.
+
+ The compiler-generated program database files specified by the MSVC
+ ``/Fd`` flag are not the same as linker-generated program database
+ files and so are not influenced by this property.
diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst
index d973e90d96..9a863a1d1c 100644
--- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst
+++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst
@@ -1,11 +1,15 @@
 PDB_OUTPUT_DIRECTORY
 --------------------
 
-Output directory for MS debug symbols .pdb file from linker.
+Output directory for the MS debug symbols ``.pdb`` file
+generated by the linker for an executable or shared library target.
 
 This property specifies the directory into which the MS debug symbols
 will be placed by the linker.  This property is initialized by the
-value of the variable CMAKE_PDB_OUTPUT_DIRECTORY if it is set when a
-target is created.
+value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is
+set when a target is created.
 
-This property is not implemented by the Visual Studio 6 generator.
+.. include:: PDB_NOTE.txt
+
+This property is not implemented by the :generator:`Visual Studio 6`
+generator.
diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst
index 25ab944967..caec2de25a 100644
--- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst
+++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst
@@ -1,13 +1,15 @@
 PDB_OUTPUT_DIRECTORY_<CONFIG>
 -----------------------------
 
-Per-configuration output directory for MS debug symbols .pdb files.
+Per-configuration output directory for the MS debug symbol ``.pdb`` file
+generated by the linker for an executable or shared library target.
 
-This is a per-configuration version of PDB_OUTPUT_DIRECTORY, but
-multi-configuration generators (VS, Xcode) do NOT append a
+This is a per-configuration version of :prop_tgt:`PDB_OUTPUT_DIRECTORY`,
+but multi-configuration generators (VS, Xcode) do NOT append a
 per-configuration subdirectory to the specified directory.  This
-property is initialized by the value of the variable
-CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
-created.
+property is initialized by the value of the
+:variable:`CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable if it is
+set when a target is created.
 
-This property is not implemented by the Visual Studio 6 generator.
+This property is not implemented by the :generator:`Visual Studio 6`
+generator.