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

4 files changed, 69 insertions, 8 deletions

diff --git a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
index f1911ec..6db5b9e 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 431e9f3..94b8dba 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 05ede8f..2833e11 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 61aa8bc..672680a 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.