clock clarification for LWWRegister, #18434

* it's safe to use from Cluster Singleton

akka-distributed-data/src/main/scala/akka/cluster/ddata/LWWMap.scala

@@ -31,6 +31,13 @@ object LWWMap {
  * use a timestamp value based on something else, for example an increasing version number
  * from a database record that is used for optimistic concurrency control.
  *
+ * The `defaultClock` is using max value of `System.currentTimeMillis()` and `currentTimestamp + 1`.
+ * This means that the timestamp is increased for changes on the same node that occurs within
+ * the same millisecond. It also means that it is safe to use the `LWWMap` without
+ * synchronized clocks when there is only one active writer, e.g. a Cluster Singleton. Such a
+ * single writer should then first read current value with `ReadMajority` (or more) before
+ * changing and writing the value with `WriteMajority` (or more).
+ *
  * For first-write-wins semantics you can use the [[LWWRegister#reverseClock]] instead of the
  * [[LWWRegister#defaultClock]]
  *

akka-distributed-data/src/main/scala/akka/cluster/ddata/LWWRegister.scala

@@ -85,6 +85,13 @@ object LWWRegister {
  * use a timestamp value based on something else, for example an increasing version number
  * from a database record that is used for optimistic concurrency control.
  *
+ * The `defaultClock` is using max value of `System.currentTimeMillis()` and `currentTimestamp + 1`.
+ * This means that the timestamp is increased for changes on the same node that occurs within
+ * the same millisecond. It also means that it is safe to use the `LWWRegister` without
+ * synchronized clocks when there is only one active writer, e.g. a Cluster Singleton. Such a
+ * single writer should then first read current value with `ReadMajority` (or more) before
+ * changing and writing the value with `WriteMajority` (or more).
+ *
  * For first-write-wins semantics you can use the [[LWWRegister#reverseClock]] instead of the
  * [[LWWRegister#defaultClock]]
  *