fix javadoc durable state deleteobject (#2972)

* fix: clarify deleteObject revision must be expected next revision (current + 1) in docs

Agent-Logs-Url: https://github.com/pjfanning/incubator-pekko/sessions/e855d7d3-4827-4438-9c9d-8f288f2f0c4d

Co-authored-by: pjfanning <11783444+pjfanning@users.noreply.github.com>

* further changes

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pjfanning <11783444+pjfanning@users.noreply.github.com>

Author: pjfanning

persistence/src/main/scala/org/apache/pekko/persistence/state/javadsl/DurableStateUpdateStore.scala

@@ -50,14 +50,15 @@ trait DurableStateUpdateStore[A] extends DurableStateStore[A] {
    * Delete the object with the given `persistenceId` and `revision`.
    *
    * <p>
-   * Since Pekko v1.1, if the revision does not match the current revision
+   * If the revision does not match the expected revision
    * of the object, the delete operation will fail. The returned CompletionStage
    * will complete with a failed result wrapping the exception.
    * </p>
    *
    * @param persistenceId the persistenceId of the object to delete
-   * @param revision the revision of the object to delete
-   * @return a CompletionStage that completes when the object has been deleted
+   * @param revision the expected next revision for the `persistenceId` — this must be one more than
+   *                 the current (existing) revision of the object
+   * @return a CompletionStage that completes when the object has been deleted or fails if the revision does not match the expected revision of the object
    */
   def deleteObject(persistenceId: String, revision: Long): CompletionStage[Done]
 }

persistence/src/main/scala/org/apache/pekko/persistence/state/scaladsl/DurableStateUpdateStore.scala

@@ -50,14 +50,15 @@ trait DurableStateUpdateStore[A] extends DurableStateStore[A] {
    * Delete the object with the given `persistenceId` and `revision`.
    *
    * <p>
-   * Since Pekko v1.1, if the revision does not match the current revision
+   * If the revision does not match the expected revision
    * of the object, the delete operation will fail. The returned Future
    * will complete with a failed result wrapping the exception.
    * </p>
    *
    * @param persistenceId the persistenceId of the object to delete
-   * @param revision the revision of the object to delete
-   * @return a Future that completes when the object has been deleted
+   * @param revision the expected next revision for the `persistenceId` — this must be one more than
+   *                 the current (existing) revision of the object
+   * @return a Future that completes when the object has been deleted or fails if the revision does not match the expected revision of the object
    */
   def deleteObject(persistenceId: String, revision: Long): Future[Done]
 }