Polishing.

Add since tags to extension methods and issue references to tests.
Update antora playbook to consider maintenance branches.

Original Pull Request: #4753

spring-data-mongodb/src/main/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensions.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2024 the original author or authors.
+ * Copyright 2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,6 +23,7 @@ import kotlin.reflect.KProperty
  * Static factory method to create an Update using the provided key
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.update
  */
 fun <T> update(key: KProperty<T>, value: T?) =
@@ -32,6 +33,7 @@ fun <T> update(key: KProperty<T>, value: T?) =
  * Update using the {@literal $set} update modifier
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.set
  */
 fun <T> Update.set(key: KProperty<T>, value: T?) =
@@ -41,6 +43,7 @@ fun <T> Update.set(key: KProperty<T>, value: T?) =
  * Update using the {@literal $setOnInsert} update modifier
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.setOnInsert
  */
 fun <T> Update.setOnInsert(key: KProperty<T>, value: T?) =
@@ -50,6 +53,7 @@ fun <T> Update.setOnInsert(key: KProperty<T>, value: T?) =
  * Update using the {@literal $unset} update modifier
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.unset
  */
 fun <T> Update.unset(key: KProperty<T>) =
@@ -59,6 +63,7 @@ fun <T> Update.unset(key: KProperty<T>) =
  * Update using the {@literal $inc} update modifier
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.inc
  */
 fun <T> Update.inc(key: KProperty<T>, inc: Number) =
@@ -71,6 +76,7 @@ fun <T> Update.inc(key: KProperty<T>) =
  * Update using the {@literal $push} update modifier
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.push
  */
 fun <T> Update.push(key: KProperty<Collection<T>>, value: T?) =
@@ -79,9 +85,10 @@ fun <T> Update.push(key: KProperty<Collection<T>>, value: T?) =
 /**
  * Update using {@code $push} modifier. <br/>
  * Allows creation of {@code $push} command for single or multiple (using {@code $each}) values as well as using
- *
  * {@code $position}.
+ *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.push
  */
 fun <T> Update.push(key: KProperty<T>) =
@@ -92,6 +99,7 @@ fun <T> Update.push(key: KProperty<T>) =
  * Allows creation of {@code $push} command for single or multiple (using {@code $each}) values * {@code $position}.
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.addToSet
  */
 fun <T> Update.addToSet(key: KProperty<T>) =
@@ -101,6 +109,7 @@ fun <T> Update.addToSet(key: KProperty<T>) =
  * Update using the {@literal $addToSet} update modifier
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.addToSet
  */
 fun <T> Update.addToSet(key: KProperty<Collection<T>>, value: T?) =
@@ -110,6 +119,7 @@ fun <T> Update.addToSet(key: KProperty<Collection<T>>, value: T?) =
  * Update using the {@literal $pop} update modifier
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.pop
  */
 fun <T> Update.pop(key: KProperty<T>, pos: Position) =
@@ -119,6 +129,7 @@ fun <T> Update.pop(key: KProperty<T>, pos: Position) =
  * Update using the {@literal $pull} update modifier
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.pull
  */
 fun <T> Update.pull(key: KProperty<T>, value: Any) =
@@ -128,6 +139,7 @@ fun <T> Update.pull(key: KProperty<T>, value: Any) =
  * Update using the {@literal $pullAll} update modifier
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.pullAll
  */
 fun <T> Update.pullAll(key: KProperty<Collection<T>>, values: Array<T>) =
@@ -137,6 +149,7 @@ fun <T> Update.pullAll(key: KProperty<Collection<T>>, values: Array<T>) =
  * Update given key to current date using {@literal $currentDate} modifier.
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.currentDate
  */
 fun <T> Update.currentDate(key: KProperty<T>) =
@@ -146,6 +159,7 @@ fun <T> Update.currentDate(key: KProperty<T>) =
  * Update given key to current date using {@literal $currentDate : &#123; $type : "timestamp" &#125;} modifier.
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.currentTimestamp
  */
 fun <T> Update.currentTimestamp(key: KProperty<T>) =
@@ -155,6 +169,7 @@ fun <T> Update.currentTimestamp(key: KProperty<T>) =
  * Multiply the value of given key by the given number.
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.multiply
  */
 fun <T> Update.multiply(key: KProperty<T>, multiplier: Number) =
@@ -164,6 +179,7 @@ fun <T> Update.multiply(key: KProperty<T>, multiplier: Number) =
  * Update given key to the {@code value} if the {@code value} is greater than the current value of the field.
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.max
  */
 fun <T : Any> Update.max(key: KProperty<T>, value: T) =
@@ -173,6 +189,7 @@ fun <T : Any> Update.max(key: KProperty<T>, value: T) =
  * Update given key to the {@code value} if the {@code value} is less than the current value of the field.
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.min
  */
 fun <T : Any> Update.min(key: KProperty<T>, value: T) =
@@ -182,6 +199,7 @@ fun <T : Any> Update.min(key: KProperty<T>, value: T) =
  * The operator supports bitwise {@code and}, bitwise {@code or}, and bitwise {@code xor} operations.
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.bitwise
  */
 fun <T> Update.bitwise(key: KProperty<T>) =
@@ -192,6 +210,7 @@ fun <T> Update.bitwise(key: KProperty<T>) =
  * driver without further type or field mapping.
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.filterArray
  */
 fun <T> Update.filterArray(identifier: KProperty<T>, expression: Any) =
@@ -201,6 +220,7 @@ fun <T> Update.filterArray(identifier: KProperty<T>, expression: Any) =
  * Determine if a given {@code key} will be touched on execution.
  *
  * @author Pawel Matysek
+ * @since 4.4
  * @see Update.modifies
  */
 fun <T> Update.modifies(key: KProperty<T>) =

spring-data-mongodb/src/test/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensionsTests.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2024 the original author or authors.
+ * Copyright 2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,7 +27,7 @@ import java.time.Instant
  */
 class TypedUpdateExtensionsTests {
 
-    @Test
+    @Test // GH-3028
     fun `update() should equal expected Update`() {
 
         val typed = update(Book::title, "Moby-Dick")
@@ -36,7 +36,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `set() should equal expected Update`() {
 
         val typed = Update().set(Book::title, "Moby-Dick")
@@ -45,7 +45,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `setOnInsert() should equal expected Update`() {
 
         val typed = Update().setOnInsert(Book::title, "Moby-Dick")
@@ -54,7 +54,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `unset() should equal expected Update`() {
 
         val typed = Update().unset(Book::title)
@@ -63,7 +63,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `inc(key, inc) should equal expected Update`() {
 
         val typed = Update().inc(Book::price, 5)
@@ -72,7 +72,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `inc(key) should equal expected Update`() {
 
         val typed = Update().inc(Book::price)
@@ -81,7 +81,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `push(key, value) should equal expected Update`() {
 
         val typed = Update().push(Book::categories, "someCategory")
@@ -90,7 +90,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `push(key) should equal expected Update`() {
 
         val typed = Update().push(Book::categories)
@@ -99,7 +99,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `addToSet(key) should equal expected Update`() {
 
         val typed = Update().addToSet(Book::categories).each("category", "category2")
@@ -108,7 +108,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `addToSet(key, value) should equal expected Update`() {
 
         val typed = Update().addToSet(Book::categories, "someCategory")
@@ -117,7 +117,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `pop() should equal expected Update`() {
 
         val typed = Update().pop(Book::categories, Update.Position.FIRST)
@@ -126,7 +126,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `pull() should equal expected Update`() {
 
         val typed = Update().pull(Book::categories, "someCategory")
@@ -135,7 +135,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `pullAll() should equal expected Update`() {
 
         val typed = Update().pullAll(Book::categories, arrayOf("someCategory", "someCategory2"))
@@ -144,7 +144,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `currentDate() should equal expected Update`() {
 
         val typed = Update().currentDate(Book::releaseDate)
@@ -153,7 +153,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `currentTimestamp() should equal expected Update`() {
 
         val typed = Update().currentTimestamp(Book::releaseDate)
@@ -162,7 +162,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `multiply() should equal expected Update`() {
 
         val typed = Update().multiply(Book::price, 2)
@@ -171,7 +171,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `max() should equal expected Update`() {
 
         val typed = Update().max(Book::price, 200)
@@ -180,7 +180,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `min() should equal expected Update`() {
 
         val typed = Update().min(Book::price, 100)
@@ -189,7 +189,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `bitwise() should equal expected Update`() {
 
         val typed = Update().bitwise(Book::price).and(2)
@@ -198,7 +198,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `filterArray() should equal expected Update`() {
 
         val typed = Update().filterArray(Book::categories, "someCategory")
@@ -207,7 +207,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `typed modifies() should equal expected modifies()`() {
 
         val typed = update(Book::title, "Moby-Dick")
@@ -216,7 +216,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed.modifies(Book::price)).isEqualTo(typed.modifies("price"))
     }
 
-    @Test
+    @Test // GH-3028
     fun `One level nested should equal expected Update`() {
 
         val typed = update(Book::author / Author::name, "Herman Melville")
@@ -225,7 +225,7 @@ class TypedUpdateExtensionsTests {
         assertThat(typed).isEqualTo(expected)
     }
 
-    @Test
+    @Test // GH-3028
     fun `Two levels nested should equal expected Update`() {
 
         data class Entity(val book: Book)

src/main/antora/antora-playbook.yml

@@ -17,7 +17,7 @@ content:
     - url: https://github.com/spring-projects/spring-data-commons
       # Refname matching:
       # https://docs.antora.org/antora/latest/playbook/content-refname-matching/
-      branches: [ main, 3.2.x ]
+      branches: [ main, 3.3.x, 3.2.x]
       start_path: src/main/antora
 asciidoc:
   attributes:

src/main/antora/modules/ROOT/pages/kotlin/extensions.adoc

@@ -19,7 +19,7 @@ val characters : Flux<SWCharacter> = template.query().inTable("star-wars").all()
 As in Java, `characters` in Kotlin is strongly typed, but Kotlin's clever type inference allows for shorter syntax.
 
 [[mongo.query.kotlin-support]]
-== Type-safe Queries and Updates for Kotlin
+== Type-safe Queries for Kotlin
 
 Kotlin embraces domain-specific language creation through its language syntax and its extension system.
 Spring Data MongoDB ships with a Kotlin Extension for `Criteria` using https://kotlinlang.org/docs/reference/reflection.html#property-references[Kotlin property references] to build type-safe queries.
@@ -64,7 +64,11 @@ mongoOperations.find<Book>(
 <3> To construct nested properties, use the `/` character (overloaded operator `div`).
 ====
 
-Similar syntax can be used while updating a document:
+[[mongo.update.kotlin-support]]
+== Type-safe Updates for Kotlin
+
+A syntax similar to <<mongo.query.kotlin-support>> can be used to update documents:
+
 ====
 [source,kotlin]
 ----