Misc changes as suggested in the PR review

akka-docs/src/main/paradox/persistence-query-durable-state.md

@@ -35,6 +35,8 @@ durable state is stored in a database and fetched as an asynchronous stream to t
 durable state, provided by the `DurableStateStoreQuery` interface, is used to implement tag based searches in 
 Akka Projections. 
 
+At present the query is based on _tags_. So if you have not tagged your objects, this query cannot be used.
+
 The example below shows how to get the  `DurableStateStoreQuery` from the `DurableStateStoreRegistry` extension.
 
 Scala

akka-docs/src/main/paradox/typed/persistence-durable-state.md

@@ -22,6 +22,12 @@ To use Akka Persistence, add the module to your project:
 
 You also have to select durable state store plugin, see @ref:[Persistence Plugins](../persistence-plugins.md).
 
+@@@ note
+
+The APIs in the Durable State module are _experimental_ and subject to change based on feedbacks from the 
+users and the community.
+
+@@@ 
 
 @@project-info{ projectId="akka-persistence-typed" }
 
@@ -38,7 +44,9 @@ The current state is always stored in the database. Since only the latest state
 Akka Persistence also supports @ref:[Event Sourcing](persistence.md) based implementation, where only the _events_ that are persisted by the actor are stored, but not the actual state of the actor. By storing all events, using this model, 
 a stateful actor can be recovered by replaying the stored events to the actor, which allows it to rebuild its state.
 
-The database specific implementations can be added to existing Akka Persistence plugin implementations, starting with the JDBC plugin. The plugin would serialize the state and store as a blob with the persistenceId as the primary key. 
+The database specific implementations can be added to existing Akka Persistence plugin implementations, starting with the JDBC plugin. The plugin would serialize the state and store as a blob with the persistenceId as the primary key. Since each entity
+lives on one node, consistency is guaranteed and reads can be served directly from memory. For details on how this guarantee
+is ensured, have a look at the @ref:[Cluster Sharding and DurableStateBehavior](#cluster-sharding-and-durablestatebehavior) section below.
 
 ## Example and core API
 

akka-persistence-query/src/main/scala/akka/persistence/query/javadsl/DurableStateStoreQuery.scala

@@ -30,7 +30,7 @@ trait DurableStateStoreQuery[A] extends DurableStateStore[A] {
    * This will return changes that occurred up to when the `Source` returned by this call is materialized. Changes to
    * objects made since materialization are not guaranteed to be included in the results.
    *
-   * @param tag The type of entity to get changes for.
+   * @param tag The tag to get changes for.
    * @param offset The offset to get changes since. Must either be [[akka.persistence.query.NoOffset]] to get
    *               changes since the beginning of time, or an offset that has been previously returned by this query.
    *               Any other offsets are invalid.
@@ -39,7 +39,7 @@ trait DurableStateStoreQuery[A] extends DurableStateStore[A] {
   def currentChanges(tag: String, offset: Offset): Source[DurableStateChange[A], NotUsed]
 
   /**
-   * Get a source of the most recent changes made to objects of the given entity type since the passed in offset.
+   * Get a source of the most recent changes made to objects of the given tag since the passed in offset.
    *
    * The returned source will never terminate, it effectively watches for changes to the objects and emits changes as
    * they happen.
@@ -49,7 +49,7 @@ trait DurableStateStoreQuery[A] extends DurableStateStore[A] {
    * in quick succession are likely to be skipped, with only the last update resulting in a change event from this
    * source.
    *
-   * @param tag The type of entity to get changes for.
+   * @param tag The tag to get changes for.
    * @param offset The offset to get changes since. Must either be [[akka.persistence.query.NoOffset]] to get
    *               changes since the beginning of time, or an offset that has been previously returned by this query.
    *               Any other offsets are invalid.

akka-persistence-query/src/main/scala/akka/persistence/query/scaladsl/DurableStateStoreQuery.scala

@@ -30,7 +30,7 @@ trait DurableStateStoreQuery[A] extends DurableStateStore[A] {
    * This will return changes that occurred up to when the `Source` returned by this call is materialized. Changes to
    * objects made since materialization are not guaranteed to be included in the results.
    *
-   * @param tag The type of entity to get changes for.
+   * @param tag The tag to get changes for.
    * @param offset The offset to get changes since. Must either be [[akka.persistence.query.NoOffset]] to get
    *               changes since the beginning of time, or an offset that has been previously returned by this query.
    *               Any other offsets are invalid.
@@ -49,7 +49,7 @@ trait DurableStateStoreQuery[A] extends DurableStateStore[A] {
    * in quick succession are likely to be skipped, with only the last update resulting in a change event from this
    * source.
    *
-   * @param tag The type of entity to get changes for.
+   * @param tag The tag to get changes for.
    * @param offset The offset to get changes since. Must either be [[akka.persistence.query.NoOffset]] to get
    *               changes since the beginning of time, or an offset that has been previously returned by this query.
    *               Any other offsets are invalid.

akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/DurableStatePersistentBehaviorCompileOnly.scala

@@ -127,7 +127,6 @@ object DurableStatePersistentBehaviorCompileOnly {
         emptyState = State(0),
         commandHandler = (state, cmd) => throw new NotImplementedError("TODO: process the command & return an Effect"))
         .withTag("tag1")
-        .withTag("tag2")
     //#tagging
   }
 

akka-persistence/src/main/scala/akka/persistence/state/javadsl/DurableStateStore.scala

@@ -13,7 +13,7 @@ import akka.annotation.ApiMayChange
 import akka.persistence.state.scaladsl.{ GetObjectResult => SGetObjectResult }
 
 /**
- * API for reading durable state objects.
+ * API for reading durable state objects with payload `A`.
  *
  * For Scala API see [[akka.persistence.state.scaladsl.DurableStateStore]].
  *

akka-persistence/src/main/scala/akka/persistence/state/scaladsl/DurableStateStore.scala

@@ -11,7 +11,7 @@ import akka.annotation.ApiMayChange
 import akka.persistence.state.javadsl.{ GetObjectResult => JGetObjectResult }
 
 /**
- * API for reading durable state objects.
+ * API for reading durable state objects with payload `A`.
  *
  * For Java API see [[akka.persistence.state.javadsl.DurableStateStore]].
  *