diff --git a/src/driver/database-connection.ts b/src/driver/database-connection.ts
index 1259a77c2..cca2b4647 100644
--- a/src/driver/database-connection.ts
+++ b/src/driver/database-connection.ts
@@ -29,7 +29,9 @@ export interface QueryResult<O> {
   /**
    * This is defined for update queries and contains the number of rows
    * the query changed.
-   * This is optional and only provided by some drivers like node-mysql2.
+   *
+   * This is **optional** and only provided in dialects such as MySQL.
+   * You would probably use {@link numAffectedRows} in most cases.
    */
   readonly numChangedRows?: bigint
 
diff --git a/src/query-builder/update-result.ts b/src/query-builder/update-result.ts
index 4a35637f3..bd89b2071 100644
--- a/src/query-builder/update-result.ts
+++ b/src/query-builder/update-result.ts
@@ -1,5 +1,15 @@
 export class UpdateResult {
+  /**
+   * The number of rows the update query updated (even if not changed).
+  */
   readonly numUpdatedRows: bigint
+
+  /**
+   * The number of rows the update query changed.
+   *
+   * This is **optional** and only supported in dialects such as MySQL.
+   * You would probably use {@link numUpdatedRows} in most cases.
+  */
   readonly numChangedRows?: bigint
 
   constructor(numUpdatedRows: bigint, numChangedRows: bigint | undefined) {