Merge topic 'doc-dev-source-code'

caabb6e1 Help/dev: Adopt C++ subset rules in coding guide
0fd255ad Help/dev: Adopt clang-format instructions in coding guide
540b4cdc Help/dev: Add a CMake Source Code Guide placeholder

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !724

4 files changed, 53 insertions, 36 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 434f0f4..e219763 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -25,6 +25,7 @@ To contribute patches:
 
 #. Fork the upstream `CMake Repository`_ into a personal account.
 #. Run `Utilities/SetupForDevelopment.sh`_ for local configuration.
+#. See the `CMake Source Code Guide`_ for coding guidelines.
 #. Base all new work on the upstream ``master`` branch.
 #. Create commits making incremental, distinct, logically complete changes.
 #. Push a topic branch to a personal repository fork on GitLab.
@@ -35,20 +36,9 @@ The merge request will enter the `CMake Review Process`_ for consideration.
 .. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
 .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
 .. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh
+.. _`CMake Source Code Guide`: Help/dev/source.rst
 .. _`CMake Review Process`: Help/dev/review.rst
 
-Code Style
-==========
-
-We use `clang-format`_ to define our style for C++ code in the CMake source
-tree.  See the `.clang-format`_ configuration file for our style settings.
-Use ``clang-format`` version 3.8 or higher to format source files.
-See also the `Utilities/Scripts/clang-format.bash`_ script.
-
-.. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html
-.. _`.clang-format`: .clang-format
-.. _`Utilities/Scripts/clang-format.bash`: Utilities/Scripts/clang-format.bash
-
 License
 =======
 
diff --git a/Help/dev/README.rst b/Help/dev/README.rst
index 0dc512a..163be97 100644
--- a/Help/dev/README.rst
+++ b/Help/dev/README.rst
@@ -29,3 +29,12 @@ following documents:
 .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
 .. _`CMake Review Process`: review.rst
 .. _`CMake Testing Process`: testing.rst
+
+Developer Documentation
+=======================
+
+CMake developer documentation is provided by the following documents:
+
+* The `CMake Source Code Guide`_.
+
+.. _`CMake Source Code Guide`: source.rst
diff --git a/Help/dev/source.rst b/Help/dev/source.rst
new file mode 100644
index 0000000..3ac9aca
--- /dev/null
+++ b/Help/dev/source.rst
@@ -0,0 +1,42 @@
+CMake Source Code Guide
+***********************
+
+The following is a guide to the CMake source code for developers.
+See documentation on `CMake Development`_ for more information.
+
+.. _`CMake Development`: README.rst
+
+C++ Code Style
+==============
+
+We use `clang-format`_ version **3.8** to define our style for C++ code in
+the CMake source tree.  See the `.clang-format`_ configuration file for our
+style settings.  Use the `Utilities/Scripts/clang-format.bash`_ script to
+format source code.  It automatically runs ``clang-format`` on the set of
+source files for which we enforce style.  The script also has options to
+format only a subset of files, such as those that are locally modified.
+
+.. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html
+.. _`.clang-format`: ../../.clang-format
+.. _`Utilities/Scripts/clang-format.bash`: ../../Utilities/Scripts/clang-format.bash
+
+C++ Subset Permitted
+====================
+
+CMake supports compiling as C++98 in addition to C++11 and C++14.
+In order to support building on older toolchains some constructs
+need to be handled with care:
+
+* Use ``CM_AUTO_PTR`` instead of ``std::auto_ptr``.
+
+  The ``std::auto_ptr`` template is deprecated in C++11.  We want to use it
+  so we can build on C++98 compilers but we do not want to turn off compiler
+  warnings about deprecated interfaces in general.  Use the ``CM_AUTO_PTR``
+  macro instead.
+
+* Use ``size_t`` instead of ``std::size_t``.
+
+  Various implementations have differing implementation of ``size_t``.
+  When assigning the result of ``.size()`` on a container for example,
+  the result should be assigned to ``size_t`` not to ``std::size_t``,
+  ``unsigned int`` or similar types.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index f77d8c0..cd509ac 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -13,30 +13,6 @@ Introduction
 This manual is intended for reference by developers modifying the CMake
 source tree itself, and by those authoring externally-maintained modules.
 
-
-Permitted C++ Subset
-====================
-
-CMake is required to build with ancient C++ compilers and standard library
-implementations.  Some common C++ constructs may not be used in CMake in order
-to build with such toolchains.
-
-std::auto_ptr
--------------
-
-The ``std::auto_ptr`` template is deprecated in C++11.  We want to use it
-so we can build on C++98 compilers but we do not want to turn off compiler
-warnings about deprecated interfaces in general.  Use the ``CM_AUTO_PTR``
-macro instead.
-
-size_t
-------
-
-Various implementations have differing implementation of ``size_t``.  When
-assigning the result of ``.size()`` on a container for example, the result
-should be assigned to ``size_t`` not to ``std::size_t``, ``unsigned int`` or
-similar types.
-
 Adding Compile Features
 =======================