Merge topic 'preset-comments'

7d2cc6ece6 presets: Allow comments in presets files

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

Help/manual/cmake-presets.7.rst

@@ -39,6 +39,9 @@ The files are a JSON document with an object as the root:
 .. literalinclude:: presets/example.json
   :language: json
 
+Preset files specifying version ``10`` or above may include comments using the
+key ``$comment`` at any level within the JSON object to provide documentation.
+
 The root object recognizes the following fields:
 
 ``$schema``
@@ -81,6 +84,9 @@ The root object recognizes the following fields:
   ``9``
     .. versionadded:: 3.30
 
+  ``10``
+    .. versionadded:: 3.31
+
 ``cmakeMinimumRequired``
   An optional object representing the minimum version of CMake needed to
   build this project. This object consists of the following fields:

Help/manual/presets/example.json

@@ -1,16 +1,22 @@
 {
-  "version": 6,
+  "version": 10,
   "cmakeMinimumRequired": {
     "major": 3,
     "minor": 23,
     "patch": 0
   },
+  "$comment": "An example CMakePresets.json file",
   "include": [
     "otherThings.json",
     "moreThings.json"
   ],
   "configurePresets": [
     {
+      "$comment": [
+        "This is a comment row.",
+        "This is another comment,",
+        "just because we can do it"
+      ],
       "name": "default",
       "displayName": "Default Config",
       "description": "Default build using Ninja generator",

Help/release/dev/preset-comments.rst

@@ -0,0 +1,5 @@
+preset-comments
+---------------
+
+* Preset files may now include comments using the key ``$comment``
+  at any level within the JSON object to provide documentation.