Help: Fix incorrect CMAKE_PROJECT_xxx docs

The docs for CMAKE_PROJECT_NAME and CMAKE_PROJECT_DESCRIPTION
were erroneously documenting the behavior of PROJECT_NAME and
PROJECT_DESCRIPTION respectively. Fix these and update the
project() docs to also mention CMAKE_PROJECT_NAME and
CMAKE_PROJECT_DESCRIPTION.

Fixes: #17815

5 files changed, 74 insertions, 10 deletions

diff --git a/Help/command/project.rst b/Help/command/project.rst
index eb185e4046..ac71d7a86b 100644
--- a/Help/command/project.rst
+++ b/Help/command/project.rst
@@ -1,7 +1,7 @@
 project
 -------
 
-Set a name, version, and enable languages for the entire project.
+Sets project details such as name, version, etc. and enables languages.
 
 .. code-block:: cmake
 
@@ -63,7 +63,10 @@ The top-level ``CMakeLists.txt`` file for a project must contain a
 literal, direct call to the :command:`project` command; loading one
 through the :command:`include` command is not sufficient.  If no such
 call exists CMake will implicitly add one to the top that enables the
-default languages (``C`` and ``CXX``).
+default languages (``C`` and ``CXX``).  The name of the project set in
+the top level CMakeLists.txt file is available from the
+:variable:`CMAKE_PROJECT_NAME` variable and its description from
+:variable:`CMAKE_PROJECT_DESCRIPTION`.
 
 .. note::
   Call the :command:`cmake_minimum_required` command at the beginning
diff --git a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
index f1911eced4..6db5b9e8ae 100644
--- a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
+++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
@@ -1,7 +1,35 @@
 CMAKE_PROJECT_DESCRIPTION
 -------------------------
 
-The description of the current project.
+The description of the top level project.
 
-This specifies description of the current project from the closest inherited
-:command:`project` command.
+This variable holds the description of the project as specified in the top
+level CMakeLists.txt file by a :command:`project` command.  In the event that
+the top level CMakeLists.txt contains multiple :command:`project` calls,
+the most recently called one from that top level CMakeLists.txt will determine
+the name that ``CMAKE_PROJECT_DESCRIPTION`` contains.  For example, consider
+the following top level CMakeLists.txt:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.0)
+  project(First DESCRIPTION "I am First")
+  project(Second DESCRIPTION "I am Second")
+  add_subdirectory(sub)
+  project(Third DESCRIPTION "I am Third")
+
+And ``sub/CMakeLists.txt`` with the following contents:
+
+.. code-block:: cmake
+
+  project(SubProj DESCRIPTION "I am SubProj")
+  message("CMAKE_PROJECT_DESCRIPTION = ${CMAKE_PROJECT_DESCRIPTION}")
+
+The most recently seen :command:`project` command from the top level
+CMakeLists.txt would be ``project(Second ...)``, so this will print::
+
+  CMAKE_PROJECT_DESCRIPTION = I am Second
+
+To obtain the description from the most recent call to :command:`project` in
+the current directory scope or above, see the :variable:`PROJECT_DESCRIPTION`
+variable.
diff --git a/Help/variable/CMAKE_PROJECT_NAME.rst b/Help/variable/CMAKE_PROJECT_NAME.rst
index 431e9f3025..94b8dbab82 100644
--- a/Help/variable/CMAKE_PROJECT_NAME.rst
+++ b/Help/variable/CMAKE_PROJECT_NAME.rst
@@ -1,7 +1,35 @@
 CMAKE_PROJECT_NAME
 ------------------
 
-The name of the current project.
+The name of the top level project.
 
-This specifies name of the current project from the closest inherited
-:command:`project` command.
+This variable holds the name of the project as specified in the top
+level CMakeLists.txt file by a :command:`project` command.  In the event that
+the top level CMakeLists.txt contains multiple :command:`project` calls,
+the most recently called one from that top level CMakeLists.txt will determine
+the name that ``CMAKE_PROJECT_NAME`` contains.  For example, consider
+the following top level CMakeLists.txt:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.0)
+  project(First)
+  project(Second)
+  add_subdirectory(sub)
+  project(Third)
+
+And ``sub/CMakeLists.txt`` with the following contents:
+
+.. code-block:: cmake
+
+  project(SubProj)
+  message("CMAKE_PROJECT_NAME = ${CMAKE_PROJECT_NAME}")
+
+The most recently seen :command:`project` command from the top level
+CMakeLists.txt would be ``project(Second)``, so this will print::
+
+  CMAKE_PROJECT_NAME = Second
+
+To obtain the name from the most recent call to :command:`project` in
+the current directory scope or above, see the :variable:`PROJECT_NAME`
+variable.
diff --git a/Help/variable/PROJECT_DESCRIPTION.rst b/Help/variable/PROJECT_DESCRIPTION.rst
index 05ede8fccd..2833e1101f 100644
--- a/Help/variable/PROJECT_DESCRIPTION.rst
+++ b/Help/variable/PROJECT_DESCRIPTION.rst
@@ -3,4 +3,7 @@ PROJECT_DESCRIPTION
 
 Short project description given to the project command.
 
-This is the description given to the most recent :command:`project` command.
+This is the description given to the most recently called :command:`project`
+command in the current directory scope or above.  To obtain the description
+of the top level project, see the :variable:`CMAKE_PROJECT_DESCRIPTION`
+variable.
diff --git a/Help/variable/PROJECT_NAME.rst b/Help/variable/PROJECT_NAME.rst
index 61aa8bc003..672680a717 100644
--- a/Help/variable/PROJECT_NAME.rst
+++ b/Help/variable/PROJECT_NAME.rst
@@ -3,4 +3,6 @@ PROJECT_NAME
 
 Name of the project given to the project command.
 
-This is the name given to the most recent :command:`project` command.
+This is the name given to the most recently called :command:`project`
+command in the current directory scope or above.  To obtain the name of
+the top level project, see the :variable:`CMAKE_PROJECT_NAME` variable.