Merge topic 'string-json-doc-update' into release-3.19

49fce3373b Help: Clarify string(JSON) error handling

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

1 files changed, 13 insertions, 10 deletions

diff --git a/Help/command/string.rst b/Help/command/string.rst
index 0c2f57e68b..51f8d821ab 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -491,6 +491,16 @@ JSON
 
 Functionality for querying a JSON string.
 
+.. note::
+  In each of the following JSON-related subcommands, if the optional
+  ``ERROR_VARIABLE`` argument is given, errors will be reported in
+  ``<error-variable>`` and the ``<out-var>`` will be set to
+  ``<member|index>-[<member|index>...]-NOTFOUND`` with the path elements
+  up to the point where the error occurred, or just ``NOTFOUND`` if there
+  is no relevant path.  If an error occurs but the ``ERROR_VARIABLE``
+  option is not present, a fatal error message is generated.  If no error
+  occurs, the ``<error-variable>`` will be set to ``NOTFOUND``.
+
 .. _GET:
 .. code-block:: cmake
 
@@ -563,13 +573,6 @@ The contents of ``<value>`` should be valid JSON.
          EQUAL <json-string1> <json-string2>)
 
 Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>``
-for equality
-
-
-If the optional ``ERROR_VARIABLE`` argument is given, errors will be
-reported in ``<error-variable>``. If no error occurs, the ``<error-variable>``
-will be set to ``NOTFOUND``. If ``ERROR_VARIABLE`` is not set a CMake error
-will be issued.
-When an error occurs the ``<out-var>`` will be set to
-``<member|index>-[<member|index>...]-NOTFOUND`` with the path elements up to
-the point where the error occurred.
+for equality.  The contents of ``<json-string1>`` and ``<json-string2>``
+should be valid JSON.  The ``<out-var>`` will be set to a true value if the
+JSON objects are considered equal, or a false value otherwise.