presets: Allow comments in presets files

Co-authored-by: Kanaiym <abdigak@clarkson.edu>
Fixes: #22791

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.

Source/cmCMakePresetsGraphReadJSON.cxx

@@ -40,7 +40,7 @@ using cmCMakePresetsGraphInternal::BaseMacroExpander;
 using cmCMakePresetsGraphInternal::ExpandMacros;
 
 constexpr int MIN_VERSION = 1;
-constexpr int MAX_VERSION = 9;
+constexpr int MAX_VERSION = 10;
 
 struct CMakeVersion
 {
@@ -528,6 +528,9 @@ bool cmCMakePresetsGraph::ReadJSONFile(const std::string& filename,
     return false;
   }
 
+  // Support for $comment added in version 10.
+  this->parseState.allowComments = (v >= 10);
+
   RootPresets presets;
   if ((result = RootPresetsHelper(presets, &root, &parseState)) != true) {
     return result;

Source/cmJSONHelpers.h

@@ -119,6 +119,12 @@ struct cmJSONHelperBuilder
         extraFields = value->getMemberNames();
       }
 
+      if (state->allowComments) {
+        extraFields.erase(
+          std::remove(extraFields.begin(), extraFields.end(), "$comment"),
+          extraFields.end());
+      }
+
       for (auto const& m : this->Members) {
         std::string name(m.Name.data(), m.Name.size());
         state->push_stack(name, value);

Source/cmJSONState.h

@@ -65,6 +65,7 @@ public:
   std::vector<JsonPair> parseStack;
   std::vector<Error> errors;
   std::string doc;
+  bool allowComments;
 
 private:
   std::string GetJsonContext(Location loc);

Tests/RunCMake/CMakePresets/CommentValid-result.txt

@@ -0,0 +1 @@
+0

Tests/RunCMake/CMakePresets/CommentValid.json.in

@@ -0,0 +1,14 @@
+{
+  "$comment": [
+    "example comment",
+    "with an array of strings"
+  ],
+  "version": 10,
+  "configurePresets": [
+    {
+      "name": "CommentValid",
+      "generator": "@RunCMake_GENERATOR@",
+      "binaryDir": "${sourceDir}/build"
+    }
+  ]
+}

Tests/RunCMake/CMakePresets/CommentValidFull-result.txt

@@ -0,0 +1 @@
+0

Tests/RunCMake/CMakePresets/CommentValidFull.json.in

@@ -0,0 +1,179 @@
+{
+  "$comment": [
+    "example comment",
+    "with an array of strings"
+  ],
+  "version": 10,
+  "cmakeMinimumRequired": {
+    "$comment": "We can add comments in version"
+  },
+  "configurePresets": [
+    {
+      "name": "CommentValidFull",
+      "$comment": "example comment",
+      "generator": "@RunCMake_GENERATOR@",
+      "binaryDir": "${sourceDir}/build",
+      "architecture": {
+        "$comment": "We can add comments in architecture",
+        "value": "v143",
+        "strategy": "external"
+      },
+      "toolset": {
+        "$comment": "We can add comments in toolset",
+        "value": "x64",
+        "strategy": "external"
+      },
+      "cacheVariables": {
+        "SOME_VARIABLE": {
+          "$comment": "We can add comments in every cacheVariable, that we created",
+          "value": "SOME_VALUE"
+        }
+      },
+      "warnings": {
+        "$comment": "We can add comments in warnings",
+        "dev": false
+      },
+      "errors": {
+        "$comment": "We can add comments in errors",
+        "dev": false
+      },
+      "debug": {
+        "$comment": "We can add comments in debug",
+        "find": false
+      },
+      "trace": {
+        "$comment": "We can add comments in trace",
+        "mode": "off"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "$comment": "example comment",
+      "name": "default",
+      "condition": {
+        "$comment": "We can add comments in condition",
+        "type": "const",
+        "value": false
+      },
+      "configurePreset": "CommentValidFull"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "default",
+      "configurePreset": "CommentValidFull",
+      "filter": {
+        "$comment": "We can add comments in filter",
+        "include": {
+          "$comment": ["example comment", "with an array of strings", "inside include"],
+          "index": {
+            "$comment": ["example comment", "with an array of strings"],
+            "start": 0
+          }
+        },
+        "exclude": {
+          "$comment": ["example comment", "with an array of strings", "inside exclude"],
+          "fixtures": {
+            "$comment": ["example comment", "with an array of strings"],
+            "any": ".*full.*"
+          }
+        }
+      },
+      "execution": {
+        "$comment": ["example comment", "with an array of strings"],
+        "repeat": {
+          "$comment": "Some comments here",
+          "mode": "until-fail",
+          "count": 1
+        }
+      },
+      "condition": {
+        "$comment": "We can add comments in equal & non-equal conditions",
+        "type": "equals",
+        "lhs": "test1",
+        "rhs": "test2"
+      },
+      "$comment": ["example comment", "with an array of strings"]
+    }
+  ],
+  "packagePresets": [
+    {
+      "name": "CommentValidFull",
+      "$comment": ["example comment", "with an array of strings"],
+      "configurePreset": "CommentValidFull",
+      "condition": {
+        "$comment": "We can add comments in list check conditions",
+        "type": "notInList",
+        "list": [
+          "test1",
+          "test2"
+        ],
+        "string": "test1"
+      },
+      "output": {
+        "$comment": "Hello, World!",
+        "debug": false
+      }
+    },
+    {
+      "name": "CommentValidFull1",
+      "configurePreset": "CommentValidFull",
+      "condition": {
+        "$comment": "We can add comments in aggregation conditions",
+        "type": "allOf",
+        "conditions": [
+          {
+            "$comment": "We can add comments in regex match conditions",
+            "type": "matches",
+            "regex": ".*tests.*",
+            "string": "test1"
+          },
+          {
+            "type": "matches",
+            "regex": ".*tests.*",
+            "string": "test2"
+          },
+          {
+            "type": "not",
+            "$comment": "We can add comments in not conditions",
+            "condition": {
+              "type": "matches",
+              "regex": ".*tests.*",
+              "string": "test3"
+            }
+          }
+        ]
+      },
+      "output": {
+        "$comment": "Hello, World 123!",
+        "verbose": false
+      }
+    }
+  ],
+  "workflowPresets": [
+    {
+      "name": "CommentValidFull",
+      "$comment": ["example comment", "with an array of strings"],
+      "steps": [
+        {
+          "type": "configure",
+          "name": "CommentValidFull"
+        },
+        {
+          "type": "build",
+          "name": "default"
+        },
+        {
+          "$comment": "We must test it before we can package it",
+          "type": "test",
+          "name": "default"
+        },
+        {
+          "type": "package",
+          "name": "CommentValidFull"
+        }
+      ]
+    }
+  ]
+}

Tests/RunCMake/CMakePresets/CommentValidOldSchema-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CMakePresets/CommentValidOldSchema-stderr.txt

@@ -0,0 +1,2 @@
+^CMake Error: Could not read presets from .*
+Error: @2,15: Invalid extra field \"\$comment\" in root object

Tests/RunCMake/CMakePresets/CommentValidOldSchema.json.in

@@ -0,0 +1,14 @@
+{
+  "$comment": [
+    "invalid comment",
+    "version less than 10"
+  ],
+  "version": 9,
+  "configurePresets": [
+    {
+      "name": "CommentValidOldSchema",
+      "generator": "@RunCMake_GENERATOR@",
+      "binaryDir": "${sourceDir}/build"
+    }
+  ]
+}

Tests/RunCMake/CMakePresets/NoCommentValid-result.txt

@@ -0,0 +1 @@
+0

Tests/RunCMake/CMakePresets/NoCommentValid.json.in

@@ -0,0 +1,10 @@
+{
+  "version": 10,
+  "configurePresets": [
+    {
+      "name": "NoCommentValid",
+      "generator": "@RunCMake_GENERATOR@",
+      "binaryDir": "${sourceDir}/build"
+    }
+  ]
+}

Tests/RunCMake/CMakePresets/RunCMakeTest.cmake

@@ -92,6 +92,12 @@ endfunction()
 set(CMakePresets_SCHEMA_EXPECTED_RESULT 1)
 run_cmake_presets(NoCMakePresets)
 run_cmake_presets(Comment)
+set(CMakePresets_SCHEMA_EXPECTED_RESULT 0)
+run_cmake_presets(NoCommentValid)
+run_cmake_presets(CommentValid)
+run_cmake_presets(CommentValidFull)
+set(CMakePresets_SCHEMA_EXPECTED_RESULT 1)
+run_cmake_presets(CommentValidOldSchema)
 run_cmake_presets(JSONParseError)
 run_cmake_presets(InvalidRoot)
 run_cmake_presets(NoVersion)