diff --git a/jOOQ/src/main/java/org/jooq/Commit.java b/jOOQ/src/main/java/org/jooq/Commit.java
index be884434c0..2f8d77b0da 100644
--- a/jOOQ/src/main/java/org/jooq/Commit.java
+++ b/jOOQ/src/main/java/org/jooq/Commit.java
@@ -43,7 +43,9 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.ApiStatus.Experimental;
 
 /**
- * A commit in a version control system.
+ * A change set describing the exact migration path between the
+ * {@link #parents()} versions and the {@link #version()} represented by this
+ * change.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/Version.java b/jOOQ/src/main/java/org/jooq/Version.java
index 1c4c6f3cd2..4f0cbda887 100644
--- a/jOOQ/src/main/java/org/jooq/Version.java
+++ b/jOOQ/src/main/java/org/jooq/Version.java
@@ -48,6 +48,14 @@ import org.jetbrains.annotations.ApiStatus.Experimental;
 /**
  * A version ID attached to a {@link Meta} description of a database.
  * <p>
+ * Unlike a {@link Commit}, which describes a <em>change</em> between two
+ * versions of a database, this type just describes the version itself, not how
+ * to get to the version.
+ * <p>
+ * While it is possible to describe a path between versions using a migration
+ * (e.g. composed of {@link Queries}), the versions themselves do not expose
+ * this information.
+ * <p>
  * This is EXPERIMENTAL functionality and subject to change in future jOOQ
  * versions.
  *