Repository: spineeventengine/core-java
Issue: The `targetVersion` of `CommandFactory.create(Message, int)` is not documented properly

Currently it is documented as follows.

```java
 @param targetVersion the ID of the entity for applying commands if {@code null}
                      the commands can be applied to any entity
```

When clearly it isn't what we say about it.

Also, for some reason, we check this `int`-typed parameter for not being `null`.

In scope of this issue we need to fix the documentation and address the nullability check.

Changed files:
client/src/main/java/io/spine/client/QueryFactory.java, client/src/main/java/io/spine/client/ActorRequestFactory.java, client/src/main/java/io/spine/client/TopicFactory.java, client/src/main/java/io/spine/client/CommandFactory.java, client/src/main/java/io/spine/client/QueryBuilder.java

diff --git a/client/src/main/java/io/spine/client/ActorRequestFactory.java b/client/src/main/java/io/spine/client/ActorRequestFactory.java
index 932c696a7e..ab2d1821b7 100644
--- a/client/src/main/java/io/spine/client/ActorRequestFactory.java
+++ b/client/src/main/java/io/spine/client/ActorRequestFactory.java
@@ -93,14 +93,32 @@ public class ActorRequestFactory {
         return result;
     }
 
+    /**
+     * Creates an instance of {@link QueryFactory} based on configuration of this
+     * {@code ActorRequestFactory} instance.
+     *
+     * @return an instance of {@link QueryFactory}
+     */
     public QueryFactory query() {
         return new QueryFactory(this);
     }
 
+    /**
+     * Creates an instance of {@link TopicFactory} based on configuration of this
+     * {@code ActorRequestFactory} instance.
+     *
+     * @return an instance of {@link TopicFactory}
+     */
     public TopicFactory topic() {
         return new TopicFactory(this);
     }
 
+    /**
+     * Creates an instance of {@link CommandFactory} based on configuration of this
+     * {@code ActorRequestFactory} instance.
+     *
+     * @return an instance of {@link CommandFactory}
+     */
     public CommandFactory command() {
         return new CommandFactory(this);
     }
diff --git a/client/src/main/java/io/spine/client/CommandFactory.java b/client/src/main/java/io/spine/client/CommandFactory.java
index 2fb8b02ded..0c8330611f 100644
--- a/client/src/main/java/io/spine/client/CommandFactory.java
+++ b/client/src/main/java/io/spine/client/CommandFactory.java
@@ -41,17 +41,14 @@ import static io.spine.time.Time.getCurrentTime;
 import static io.spine.validate.Validate.checkValid;
 
 /**
- * Public API for creating {@link Command} instances, using the {@code ActorRequestFactory}
- * configuration.
+ * A factory of {@link Command} instances.
  *
- * <p>During the creation of {@code Command} instances the source {@code Message} instances, passed
- * into creation methods, are validated. The validation is performed according to the constraints
- * set in Protobuf definition of each {@code Message}. In case the message isn't valid,
- * an {@linkplain ValidationException exception} is thrown.
+ * <p>Uses the given {@link ActorRequestFactory} as the source of the command meta information,
+ * such as the actor, the tenant, etc.
  *
- * <p>Therefore it is recommended to use a corresponding
- * {@linkplain io.spine.validate.ValidatingBuilder ValidatingBuilder} implementation to create
- * a command message.
+ * <p>The command messages passed to the factory are
+ * {@linkplain io.spine.validate.Validate#checkValid(Message) validated} according to their
+ * Proto definitions. If a given message is invalid, a {@link ValidationException} is thrown.
  *
  * @see ActorRequestFactory#command()
  */
@@ -64,14 +61,12 @@ public final class CommandFactory {
     }
 
     /**
-     * Creates new {@code Command} with the passed message.
-     *
-     * <p>The command contains a {@code CommandContext} instance with the current time.
+     * Creates a new {@link Command} with the given message.
      *
      * @param message the command message
      * @return new command instance
      * @throws ValidationException if the passed message does not satisfy the constraints
-     *                                      set for it in its Protobuf definition
+     *                             set for it in its Protobuf definition
      */
     public Command create(Message message) throws ValidationException {
         checkNotNull(message);
@@ -83,24 +78,20 @@ public final class CommandFactory {
     }
 
     /**
-     * Creates new {@code Command} with the passed message and target entity version.
-     *
-     * <p>The command contains a {@code CommandContext} instance with the current time.
+     * Creates a new {@code Command} with the passed message and target entity version.
      *
-     * <p>The message passed is validated according to the constraints set in its Protobuf
-     * definition. In case the message isn't valid, an {@linkplain ValidationException
-     * exception} is thrown.
+     * <p>The {@code targetVersion} parameter defines the version of the entity which handles
+     * the resulting command. Note that the framework performs no validation of the target version
+     * before a command is handled. The validation may be performed by the user themselves instead.
      *
      * @param message       the command message
-     * @param targetVersion the ID of the entity for applying commands if {@code null}
-     *                      the commands can be applied to any entity
+     * @param targetVersion the version of the entity for which this command is intended
      * @return new command instance
      * @throws ValidationException if the passed message does not satisfy the constraints
      *                             set for it in its Protobuf definition
      */
     public Command create(Message message, int targetVersion) throws ValidationException {
         checkNotNull(message);
-        checkNotNull(targetVersion);
         checkValid(message);
 
         final CommandContext context = createContext(targetVersion);
@@ -109,10 +100,7 @@ public final class CommandFactory {
     }
 
     /**
-     * Creates new {@code Command} with the passed {@code message} and {@code context}.
-     *
-     * <p>The timestamp of the resulting command is the <i>same</i> as in
-     * the passed {@code CommandContext}.
+     * Creates a new {@code Command} with the passed {@code message} and {@code context}.
      *
      * @param message the command message
      * @param context the command context
@@ -157,10 +145,10 @@ public final class CommandFactory {
     }
 
     /**
-     * Creates a command instance with the given {@code message} and the {@code context}.
+     * Creates a command instance with the given {@code message} and {@code context}.
      *
-     * <p>If {@code Any} instance is passed as the first parameter it will be used as is.
-     * Otherwise, the command message will be packed into {@code Any}.
+     * <p>If an instance of {@link Any} is passed as the {@code message} parameter, the packed
+     * message is used for the command construction.
      *
      * <p>The ID of the new command instance is automatically generated.
      *
@@ -169,9 +157,6 @@ public final class CommandFactory {
      * @return a new command
      */
     private static Command createCommand(Message message, CommandContext context) {
-        checkNotNull(message);
-        checkNotNull(context);
-
         final Any packed = AnyPacker.pack(message);
         final Command.Builder result = Command.newBuilder()
                                               .setId(Commands.generateId())
@@ -211,20 +196,18 @@ public final class CommandFactory {
     private static CommandContext createContext(@Nullable TenantId tenantId,
                                                 UserId userId,
                                                 ZoneOffset zoneOffset) {
-        checkNotNull(userId);
-        checkNotNull(zoneOffset);
-
         final CommandContext.Builder result = newContextBuilder(tenantId, userId, zoneOffset);
         return result.build();
     }
 
     /**
-     * Creates a new command context with the current time.
+     * Creates a new command context with the given parameters and
+     * {@link io.spine.time.Time#getCurrentTime() current time} as the {@code timestamp}.
      *
      * @param tenantId      the ID of the tenant or {@code null} for single-tenant applications
      * @param userId        the actor id
      * @param zoneOffset    the offset of the timezone in which the user works
-     * @param targetVersion the the ID of the entity for applying commands
+     * @param targetVersion the version of the entity for which this command is intended
      * @return new {@code CommandContext}
      * @see CommandFactory#create(Message)
      */
@@ -233,10 +216,6 @@ public final class CommandFactory {
                                         UserId userId,
                                         ZoneOffset zoneOffset,
                                         int targetVersion) {
-        checkNotNull(userId);
-        checkNotNull(zoneOffset);
-        checkNotNull(targetVersion);
-
         final CommandContext.Builder builder = newContextBuilder(tenantId, userId, zoneOffset);
         final CommandContext result = builder.setTargetVersion(targetVersion)
                                              .build();
@@ -262,13 +241,13 @@ public final class CommandFactory {
     /**
      * Creates a new instance of {@code CommandContext} based on the passed one.
      *
-     * <p>The returned instance gets new {@code timestamp} set to the time of the call.
+     * <p>The returned instance gets new {@code timestamp} set to
+     * the {@link io.spine.time.Time#getCurrentTime() current time}.
      *
      * @param value the instance from which to copy values
      * @return new {@code CommandContext}
      */
     private static CommandContext contextBasedOn(CommandContext value) {
-        checkNotNull(value);
         final ActorContext.Builder withCurrentTime = value.getActorContext()
                                                           .toBuilder()
                                                           .setTimestamp(getCurrentTime());
diff --git a/client/src/main/java/io/spine/client/QueryBuilder.java b/client/src/main/java/io/spine/client/QueryBuilder.java
index 7a6045969d..b61df55f4e 100644
--- a/client/src/main/java/io/spine/client/QueryBuilder.java
+++ b/client/src/main/java/io/spine/client/QueryBuilder.java
@@ -43,10 +43,10 @@ import static java.util.Collections.singleton;
  *
  * <p>The API of this class is inspired by the SQL syntax.
  *
- * <p>Calling any of the methods is optional. Call {@link #build() build()} to retrieve
- * the instance of {@link Query}.
+ * <p>Calling any of the methods is optional. Call {@link #build()} to retrieve the resulting
+ * instance of {@link Query}.
  *
- * <p>Calling any of the builder methods overrides the previous call of the given method of
+ * <p>Calling any of the builder methods overrides the previous call of the given method or
  * any of its overloads. For example, calling sequentially
  * <pre>
  *     {@code
@@ -70,9 +70,9 @@ import static java.util.Collections.singleton;
  *     {@code
  *     final Query query = factory().query()
  *                                  .select(Customer.class)
- *                                  .byId(getWestCostCustomersIds())
+ *                                  .byId(getWestCostCustomerIds())
  *                                  .withMask("name", "address", "email")
- *                                  .where({@link ColumnFilters#eq eq}("type", "permanent"),
+ *                                  .where(eq("type", "permanent"),
  *                                         eq("discountPercent", 10),
  *                                         eq("companySize", Company.Size.SMALL))
  *                                  .build();
@@ -87,9 +87,10 @@ public final class QueryBuilder {
     private final QueryFactory queryFactory;
     private final Class<? extends Message> targetType;
 
-    /* All the optional fields are initialized only when and if set
-       The empty collections make effectively no influence, but null values allow us to create
-       the query `Target` more efficiently.
+    /*
+        All the optional fields are initialized only when and if set.
+        The empty collections make effectively no influence, but null values allow us to create
+        the query `Target` more efficiently.
      */
 
     @Nullable
@@ -107,13 +108,13 @@ public final class QueryBuilder {
     }
 
     /**
-     * Sets the ID predicate to the {@linkplain Query}.
+     * Sets the ID predicate to the {@link Query}.
      *
      * <p>Though it's not prohibited at compile-time, please make sure to pass instances of the
      * same type to the argument of this method. Moreover, the instances must be of the type of
      * the query target type identifier.
      *
-     * <p>This method or any of its overload do not check these
+     * <p>This method or any of its overloads do not check these
      * constrains an assume they are followed by the caller.
      *
      * <p>If there are no IDs (i.e. and empty {@link Iterable} is passed), the query retrieves all
@@ -129,7 +130,7 @@ public final class QueryBuilder {
     }
 
     /**
-     * Sets the ID predicate to the {@linkplain Query}.
+     * Sets the ID predicate to the {@link Query}.
      *
      * @param ids the values of the IDs to look up
      * @return self for method chaining
@@ -141,7 +142,7 @@ public final class QueryBuilder {
     }
 
     /**
-     * Sets the ID predicate to the {@linkplain Query}.
+     * Sets the ID predicate to the {@link Query}.
      *
      * @param ids the values of the IDs to look up
      * @return self for method chaining
@@ -153,7 +154,7 @@ public final class QueryBuilder {
     }
 
     /**
-     * Sets the ID predicate to the {@linkplain Query}.
+     * Sets the ID predicate to the {@link Query}.
      *
      * @param ids the values of the IDs to look up
      * @return self for method chaining
@@ -165,7 +166,7 @@ public final class QueryBuilder {
     }
 
     /**
-     * Sets the ID predicate to the {@linkplain Query}.
+     * Sets the ID predicate to the {@link Query}.
      *
      * @param ids the values of the IDs to look up
      * @return self for method chaining
@@ -177,7 +178,7 @@ public final class QueryBuilder {
     }
 
     /**
-     * Sets the Entity Column predicate to the {@linkplain Query}.
+     * Sets the Entity Column predicate to the {@link Query}.
      *
      * <p>If there are no {@link ColumnFilter}s (i.e. the passed array is empty), all
      * the records will be retrieved regardless the Entity Columns values.
@@ -198,7 +199,7 @@ public final class QueryBuilder {
     }
 
     /**
-     * Sets the Entity Column predicate to the {@linkplain Query}.
+     * Sets the Entity Column predicate to the {@link Query}.
      *
      * <p>If there are no {@link ColumnFilter}s (i.e. the passed array is empty), all
      * the records will be retrieved regardless the Entity Columns values.
@@ -251,8 +252,7 @@ public final class QueryBuilder {
      *
      * <p>The {@code Option 1} is recommended in this case, since the filters are grouped logically,
      * though both builders produce effectively the same {@link Query} instances. Note, that
-     * those instances may not be equal in terms of {@link Object#equals(Object) Object.equals}
-     * method.
+     * those instances may not be equal in terms of {@link Object#equals(Object)} method.
      *
      * @param predicate a number of {@link CompositeColumnFilter} instances forming the query
      *                  predicate
@@ -308,7 +308,6 @@ public final class QueryBuilder {
      */
     public Query build() {
         final FieldMask mask = composeMask();
-        // Implying AnyPacker.pack to be idempotent
         final Set<Any> entityIds = composeIdPredicate();
 
         final Query result = queryFactory.composeQuery(targetType, entityIds, columns, mask);
diff --git a/client/src/main/java/io/spine/client/QueryFactory.java b/client/src/main/java/io/spine/client/QueryFactory.java
index e9937410ef..de84e7766f 100644
--- a/client/src/main/java/io/spine/client/QueryFactory.java
+++ b/client/src/main/java/io/spine/client/QueryFactory.java
@@ -31,12 +31,15 @@ import java.util.Set;
 
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
+import static io.spine.Identifier.newUuid;
 import static io.spine.client.Queries.queryBuilderFor;
 import static java.lang.String.format;
 
 /**
- * Public API for creating {@link Query} instances, using the {@code ActorRequestFactory}
- * configuration.
+ * A factory of {@link Query} instances.
+ *
+ * <p>Uses the given {@link ActorRequestFactory} as the source of the query meta information,
+ * such as the actor.
  *
  * @see ActorRequestFactory#query()
  */
@@ -57,14 +60,14 @@ public final class QueryFactory {
     }
 
     private static QueryId newQueryId() {
-        final String formattedId = format(QUERY_ID_FORMAT, Identifier.newUuid());
+        final String formattedId = format(QUERY_ID_FORMAT, newUuid());
         return QueryId.newBuilder()
                       .setValue(formattedId)
                       .build();
     }
 
     /**
-     * Creates a new instance of {@link QueryBuilder} for the further {@linkplain Query}
+     * Creates a new instance of {@link QueryBuilder} for the further {@link Query}
      * construction.
      *
      * @param targetType the {@linkplain Query query} target type
diff --git a/client/src/main/java/io/spine/client/TopicFactory.java b/client/src/main/java/io/spine/client/TopicFactory.java
index 661e4b2fb9..2f82425fa9 100644
--- a/client/src/main/java/io/spine/client/TopicFactory.java
+++ b/client/src/main/java/io/spine/client/TopicFactory.java
@@ -30,8 +30,10 @@ import static com.google.common.base.Preconditions.checkNotNull;
 import static io.spine.client.Targets.composeTarget;
 
 /**
- * Public API for creating {@link Topic} instances, using the {@code ActorRequestFactory}
- * configuration.
+ * A factory of {@link Topic} instances.
+ *
+ * <p>Uses the given {@link ActorRequestFactory} as the source of the topic meta information,
+ * such as the actor.
  *
  * @see ActorRequestFactory#topic()
  */
@@ -45,11 +47,11 @@ public final class TopicFactory {
     }
 
     /**
-     * Creates a {@link Topic} for a subset of the entity states by specifying their IDs.
+     * Creates a {@link Topic} for the entity states with the given IDs.
      *
      * @param entityClass the class of a target entity
      * @param ids         the IDs of interest
-     * @return the instance of {@code Topic} assembled according to the parameters.
+     * @return the instance of {@code Topic} assembled according to the parameters
      */
     public Topic someOf(Class<? extends Message> entityClass, Set<? extends Message> ids) {
         checkNotNull(entityClass);
@@ -64,7 +66,7 @@ public final class TopicFactory {
      * Creates a {@link Topic} for all of the specified entity states.
      *
      * @param entityClass the class of a target entity
-     * @return the instance of {@code Topic} assembled according to the parameters.
+     * @return the instance of {@code Topic} assembled according to the parameters
      */
     public Topic allOf(Class<? extends Message> entityClass) {
         checkNotNull(entityClass);
@@ -75,14 +77,13 @@ public final class TopicFactory {
     }
 
     /**
-     * Creates a {@link Topic} for the specified {@linkplain Target}.
+     * Creates a {@link Topic} for the specified {@link Target}.
      *
-     * <p>This method is intended for internal use only. To achieve the similar result,
-     * {@linkplain #allOf(Class) allOf()} and {@linkplain #someOf(Class, Set) someOf()} methods
-     * should be used.
+     * <p>This method is intended for internal use only. To achieve the similar result use
+     * {@linkplain #allOf(Class)} and {@linkplain #someOf(Class, Set)}.
      *
-     * @param target the {@code} Target to create a topic for.
-     * @return the instance of {@code Topic}.
+     * @param target the {@code Target} to create a topic for
+     * @return the instance of {@code Topic}
      */
     @Internal
     public Topic forTarget(Target target) {