diff --git a/cmake/git.cmake b/cmake/git.cmake
index a9b1a2812a3..9f823252d5c 100644
--- a/cmake/git.cmake
+++ b/cmake/git.cmake
@@ -1,6 +1,15 @@
 # SPDX-License-Identifier: Apache-2.0
 
-# Use git if it is installed, to set BUILD_VERSION
+#.rst:
+# git.cmake
+# ---------
+# If the user didn't already define BUILD_VERSION then try to initialize
+# it with the output of "git describe". Warn but don't error if
+# everything fails and leave BUILD_VERSION undefined.
+#
+# See also: independent and more static ``KERNEL_VERSION_*`` in
+# ``version.cmake`` and ``kernel_version.h``
+
 
 # https://cmake.org/cmake/help/latest/module/FindGit.html
 find_package(Git QUIET)
@@ -15,7 +24,8 @@ if(NOT BUILD_VERSION AND GIT_FOUND)
     RESULT_VARIABLE                  return_code
   )
   if(return_code)
-    message(STATUS "git describe failed: ${stderr}; ${KERNEL_VERSION_STRING} will be used instead")
+    message(STATUS "git describe failed: ${stderr};
+   BUILD_VERSION is left undefined")
   elseif(CMAKE_VERBOSE_MAKEFILE)
     message(STATUS "git describe stderr: ${stderr}")
   endif()
diff --git a/cmake/version.cmake b/cmake/version.cmake
index a6ad7723773..e04247e69b7 100644
--- a/cmake/version.cmake
+++ b/cmake/version.cmake
@@ -1,5 +1,32 @@
 # SPDX-License-Identifier: Apache-2.0
 
+#.rst:
+# version.cmake
+# -------------
+#
+# Inputs:
+#
+#   ``*VERSION*`` and other constants set by
+#   maintainers in ``${ZEPHYR_BASE}/VERSION``
+#
+# Outputs with examples::
+#
+#   PROJECT_VERSION           1.14.99.07
+#   KERNEL_VERSION_STRING    "1.14.99-extraver"
+#
+#   KERNEL_VERSION_MAJOR       1
+#   KERNEL_VERSION_MINOR        14
+#   KERNEL_PATCHLEVEL             99
+#   KERNELVERSION            0x10E6307
+#   KERNEL_VERSION_NUMBER    0x10E63
+#   ZEPHYR_VERSION_CODE        69219
+#
+# Most outputs are converted to C macros, see ``version.h.in``
+#
+# See also: independent and more dynamic ``BUILD_VERSION`` in
+# ``git.cmake``.
+
+
 include(${ZEPHYR_BASE}/cmake/hex.cmake)
 file(READ ${ZEPHYR_BASE}/VERSION ver)
 
diff --git a/version.h.in b/version.h.in
index ff2b3d3e3a4..4cb43adcb44 100644
--- a/version.h.in
+++ b/version.h.in
@@ -1,6 +1,8 @@
 #ifndef _KERNEL_VERSION_H_
 #define _KERNEL_VERSION_H_
 
+/* @templates@ values come from cmake/version.cmake */
+
 #cmakedefine ZEPHYR_VERSION_CODE @ZEPHYR_VERSION_CODE@
 #define ZEPHYR_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))