file(MAKE_DIRECTORY): Add optional RESULT keyword to capture failure.

Fixes: #26041

Help/command/file.rst

@@ -398,10 +398,19 @@ Filesystem
   ============== ======================================================
 
 .. signature::
-  file(MAKE_DIRECTORY <directories>...)
+  file(MAKE_DIRECTORY <directories>... [RESULT <result>])
 
   Create the given directories and their parents as needed.
 
+  The options are:
+
+    ``RESULT <result>``
+      .. versionadded:: 3.31
+
+      Set ``<result>`` variable to ``0`` on success or an error message
+      otherwise. If ``RESULT`` is not specified and the operation fails,
+      an error is emitted.
+
   .. versionchanged:: 3.30
     ``<directories>`` can be an empty list. CMake 3.29 and earlier required
     at least one directory to be given.

Help/dev/make_directory-optional-result.rst

@@ -0,0 +1,5 @@
+make_directory-optional-result
+------------------------------
+
+* The :command:`file(MAKE_DIRECTORY)` learned to
+optionally capture failure in a result variable.