doc: Clarify warning in cleanup tool (#543)

core/src/main/scala/akka/persistence/r2dbc/cleanup/javadsl/EventSourcedCleanup.scala

@@ -17,11 +17,13 @@ import akka.annotation.ApiMayChange
 import akka.persistence.r2dbc.cleanup.scaladsl
 
 /**
- * Java API: Tool for deleting all events and/or snapshots for a given list of `persistenceIds` without using persistent
- * actors. It's important that the actors with corresponding `persistenceId` are not running at the same time as using
- * the tool.
+ * Java API: Tool for deleting events and/or snapshots for a given list of `persistenceIds` without using persistent
+ * actors.
  *
- * WARNING: deleting events is generally discouraged in event sourced systems.
+ * When running an operation with `EventSourcedCleanup` that deletes all events for a persistence id, the actor with
+ * that persistence id must not be running! If the actor is restarted it would in that case be recovered to the wrong
+ * state since the stored events have been deleted. Delete events before snapshot can still be used while the actor is
+ * running.
  *
  * If `resetSequenceNumber` is `true` then the creating entity with the same `persistenceId` will start from 0.
  * Otherwise it will continue from the latest highest used sequence number.

core/src/main/scala/akka/persistence/r2dbc/cleanup/scaladsl/EventSourcedCleanup.scala

@@ -24,9 +24,13 @@ import akka.persistence.r2dbc.R2dbcSettings
 import akka.persistence.r2dbc.internal.R2dbcExecutorProvider
 
 /**
- * Scala API: Tool for deleting all events and/or snapshots for a given list of `persistenceIds` without using
- * persistent actors. It's important that the actors with corresponding `persistenceId` are not running at the same time
- * as using the tool.
+ * Scala API: Tool for deleting events and/or snapshots for a given list of `persistenceIds` without using persistent
+ * actors.
+ *
+ * When running an operation with `EventSourcedCleanup` that deletes all events for a persistence id, the actor with
+ * that persistence id must not be running! If the actor is restarted it would in that case be recovered to the wrong
+ * state since the stored events have been deleted. Delete events before snapshot can still be used while the actor is
+ * running.
  *
  * If `resetSequenceNumber` is `true` then the creating entity with the same `persistenceId` will start from 0.
  * Otherwise it will continue from the latest highest used sequence number.

docs/src/main/paradox/cleanup.md

@@ -2,15 +2,9 @@
 
 ## Event Sourced cleanup tool
 
-@@@ warning
-
-When running any operation with `EventSourcedCleanup` for a persistence id, the actor with that persistence id must
-not be running!
-
-@@@
-
 If possible, it is best to keep all events in an event sourced system. That way new @extref:[Akka Projection R2DBC](akka-projection:r2dbc.html)
-can be re-built.
+can be re-built. A @ref[Projection can also start or continue from a snapshot](./query.md#eventsbyslicesstartingfromsnapshots),
+and then events can be deleted before the snapshot. 
 
 In some cases keeping all events is not possible or must be removed for regulatory reasons, such as compliance with
 GDPR. `EventSourcedBehavior`s can automatically snapshot state and delete events as described in the
@@ -32,6 +26,15 @@ not emit further events after that and typically stop itself if it receives more
 * Delete events before snapshot for one or many persistence ids
 * Delete events before a timestamp
 
+@@@ warning
+
+When running an operation with `EventSourcedCleanup` that deletes all events for a persistence id,
+the actor with that persistence id must not be running! If the actor is restarted it would in that
+case be recovered to the wrong state since the stored events have been deleted. Delete events before
+snapshot can still be used while the actor is running.
+
+@@@
+
 The cleanup tool can be combined with the @ref[query plugin](./query.md) which has a query to get all persistence ids.
 
 Java
@@ -42,15 +45,16 @@ Scala
 
 ## Durable State cleanup tool
 
+@apidoc[DurableStateCleanup] operations include:
+
+* Delete state for one or many persistence ids
+
 @@@ warning
 
 When running any operation with `DurableStateCleanup` for a persistence id, the actor with that persistence id must
-not be running!
+not be running! If the actor is restarted it would in that case be recovered to the wrong state since the stored state
+hase been deleted.
 
 @@@
 
-@apidoc[DurableStateCleanup] operations include:
-
-* Delete state for one or many persistence ids
-
 The cleanup tool can be combined with the @ref[query plugin](./query.md) which has a query to get all persistence ids.