string(JSON .. EQUAL) documentation is unclear regarding errors
The current documentation for the new string(JSON ... EQUAL ...)
subcommand added in CMake 3.19 by !5159 (merged) is a bit confusing with regard to the handling of errors. The following points should be addressed before the final 3.19 release:
- If one of the two JSON strings provided for comparison is not valid JSON, the command always fails and ignores any
ERROR_VARIABLE
option. The docs could be interpreted to capture such errors in the nominated error variable instead. - What does "If
ERROR_VARIABLE
is not set a CMake error will be issued" mean? - If the two JSON strings provided are unequal, is that considered an error? That doesn't seem like an error in the usual sense, just one of two possible outcomes assuming valid JSON strings are provided. But it seems like issuing an error on mismatch might be how the command is meant to operate. This should be clarified and perhaps reworded in the docs.