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

1 files changed, 31 insertions, 3 deletions

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.