project: Add `DESCRIPTION` parameter

It is quite often the project description has used in a real world software.
Examples include:

* part of a help screen of the application
* builtin resources (`*.rc` files, data for "About" dialog of a GUI app, & etc)
* most generators for CPack can use it
* it could be used by documentary software (Doxygen, Sphinx) which is usually
  integrated to CMake based projects via `add_custom_target()`

Now `project()` call learned an optional `DESCRIPTION` parameter with a
short string describing a project. Being specified, it would set the
`PROJECT_DESCRIPTION` variable which could be used in `configure_file()`
or whatever user wants.  Also `PROJECT_DESCRIPTION` is a default value
for `CPACK_PACKAGE_DESCRIPTION_SUMMARY`.

5 files changed, 25 insertions, 0 deletions

diff --git a/Help/command/project.rst b/Help/command/project.rst
index 6c5ace7..139f69c 100644
--- a/Help/command/project.rst
+++ b/Help/command/project.rst
@@ -8,6 +8,7 @@ Set a name, version, and enable languages for the entire project.
  project(<PROJECT-NAME> [LANGUAGES] [<language-name>...])
  project(<PROJECT-NAME>
          [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
+         [DESCRIPTION <project-description-string>]
          [LANGUAGES <language-name>...])
 
 Sets the name of the project and stores the name in the
@@ -40,6 +41,10 @@ in variables
 Variables corresponding to unspecified versions are set to the empty string
 (if policy :policy:`CMP0048` is set to ``NEW``).
 
+If optional ``DESCRIPTION`` is given, then additional :variable:`PROJECT_DESCRIPTION`
+variable will be set to its argument. The argument must be a string with short
+description of the project (only a few words).
+
 Optionally you can specify which languages your project supports.
 Example languages are ``C``, ``CXX`` (i.e.  C++), ``Fortran``, etc.
 By default ``C`` and ``CXX`` are enabled if no language options are
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 9d8d596..038d6e0 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -60,6 +60,7 @@ Variables that Provide Information
    /variable/CMAKE_MINOR_VERSION
    /variable/CMAKE_PARENT_LIST_FILE
    /variable/CMAKE_PATCH_VERSION
+   /variable/CMAKE_PROJECT_DESCRIPTION
    /variable/CMAKE_PROJECT_NAME
    /variable/CMAKE_RANLIB
    /variable/CMAKE_ROOT
@@ -97,6 +98,7 @@ Variables that Provide Information
    /variable/PROJECT-NAME_VERSION_PATCH
    /variable/PROJECT-NAME_VERSION_TWEAK
    /variable/PROJECT_BINARY_DIR
+   /variable/PROJECT_DESCRIPTION
    /variable/PROJECT_NAME
    /variable/PROJECT_SOURCE_DIR
    /variable/PROJECT_VERSION
diff --git a/Help/release/dev/project_description.rst b/Help/release/dev/project_description.rst
new file mode 100644
index 0000000..baf0045
--- /dev/null
+++ b/Help/release/dev/project_description.rst
@@ -0,0 +1,5 @@
+project-description
+-------------------
+
+* The :command:`project` command learned an optional ``DESCRIPTION`` parameter.
+  See :command:`project` command and :variable:`PROJECT_DESCRIPTION` variable.
diff --git a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
new file mode 100644
index 0000000..f1911ec
--- /dev/null
+++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
@@ -0,0 +1,7 @@
+CMAKE_PROJECT_DESCRIPTION
+-------------------------
+
+The description of the current project.
+
+This specifies description of the current project from the closest inherited
+:command:`project` command.
diff --git a/Help/variable/PROJECT_DESCRIPTION.rst b/Help/variable/PROJECT_DESCRIPTION.rst
new file mode 100644
index 0000000..05ede8f
--- /dev/null
+++ b/Help/variable/PROJECT_DESCRIPTION.rst
@@ -0,0 +1,6 @@
+PROJECT_DESCRIPTION
+-------------------
+
+Short project description given to the project command.
+
+This is the description given to the most recent :command:`project` command.