diff --git a/meson.build b/meson.build
index 074e80ff13..c8f6482e4a 100644
--- a/meson.build
+++ b/meson.build
@@ -21,11 +21,13 @@ libudev_version = '1.6.17'
 # names, sometimes. Not all variables are included in every
 # set. Ugh, ugh, ugh!
 conf = configuration_data()
-conf.set('PROJECT_VERSION',        meson.project_version())
+conf.set('PROJECT_VERSION',        meson.project_version(),
+         description : 'Numerical project version (used where a simple number is expected)')
 
 substs = configuration_data()
 substs.set('PROJECT_URL',          'https://www.freedesktop.org/wiki/Software/systemd')
-substs.set('PROJECT_VERSION',      meson.project_version())
+substs.set('PROJECT_VERSION',      meson.project_version(),
+           description : 'Numerical project version (used where a simple number is expected)')
 
 # This is to be used instead of meson.source_root(), as the latter will return
 # the wrong result when systemd is being built as a meson subproject
diff --git a/src/version/version.h.in b/src/version/version.h.in
index 9f82d905a7..4219dce83a 100644
--- a/src/version/version.h.in
+++ b/src/version/version.h.in
@@ -1 +1,8 @@
+/* Detailed project version that includes git commit when not built from a release.
+ * Use this in preference to PROJECT_VERSION, with the following exceptions:
+ * - where a simplified form is expected for compatiblity, for example
+ *   'udevadm version',
+ * - where a simplified machine-parsable form is more useful, for example
+ *   pkgconfig files and version information written to binary files.
+ */
 #define GIT_VERSION "@VCS_TAG@"