docs: enhance keyvalue template

Signed-off-by: Otavio Santana <otaviopolianasantana@gmail.com>

jnosql-mapping/jnosql-mapping-key-value/src/main/java/org/eclipse/jnosql/mapping/keyvalue/KeyValueTemplate.java

@@ -18,55 +18,55 @@
  * </p>
  *
  * <p>
- * This interface provides some methods that accepts queries in a text format to retrieve from the database but,
- * <b>the query syntax belongs to each provider, thus, it is not Jakarta's NoSQL scope to define it.
- * Accordingly, it might vary from implementation and NoSQL provider.</b>
+ * This interface provides some methods that accept queries in a text format to retrieve data from the database, but
+ * <b>the query syntax belongs to each provider, thus, it is not within Jakarta NoSQL's scope to define it.
+ * Accordingly, it might vary between implementations and NoSQL providers.</b>
  * </p>
  */
 public interface KeyValueTemplate extends Template {
     /**
-     * Saves the entity
+     * Saves an entity.
      *
      * @param entity the entity to be inserted
      * @param <T>    the entity type
-     * @return the entity
-     * @throws NullPointerException when entity is null
+     * @return the saved entity
+     * @throws NullPointerException when the entity is null
      */
     <T> T put(T entity);
 
     /**
-     * Saves the entity with time to live
+     * Saves an entity with a specified time to live (TTL).
      *
      * @param entity the entity to be inserted
-     * @param ttl    the defined time to live
+     * @param ttl    the time to live
      * @param <T>    the entity type
-     * @return the entity
-     * @throws NullPointerException          when entity is null
+     * @return the saved entity
+     * @throws NullPointerException          when the entity is null
      * @throws UnsupportedOperationException when expired time is not supported
      */
     <T> T put(T entity, Duration ttl);
 
     /**
-     * Saves the {@link Iterable} of entities
+     * Saves an {@link Iterable} of entities.
      *
-     * @param entities keys to be inserted
+     * @param entities the entities to be inserted
      * @param <T>      the entity type
-     * @return the entities
+     * @return the saved entities
      * @throws NullPointerException when the iterable is null
      */
     default <T> Iterable<T> put(Iterable<T> entities) {
         Objects.requireNonNull(entities, "entities is required");
-        return StreamSupport.stream(entities.spliterator(), false).map(this::put).toList();
+        return StreamSupport.stream(entities.spliterator(), false).map(this::put).collect(Collectors.toList());
     }
 
     /**
-     * Saves the {@link Iterable} of entities with a defined time to live
+     * Saves an {@link Iterable} of entities with a specified time to live (TTL).
      *
-     * @param entities entities to be insert
-     * @param ttl      the time to entity expire
+     * @param entities the entities to be inserted
+     * @param ttl      the time to live
      * @param <T>      the entity type
-     * @return the entities
-     * @throws NullPointerException          when the iterable is null
+     * @return the saved entities
+     * @throws NullPointerException          when the iterable or ttl is null
      * @throws UnsupportedOperationException when expired time is not supported
      */
     default <T> Iterable<T> put(Iterable<T> entities, Duration ttl) {
@@ -76,98 +76,100 @@ default <T> Iterable<T> put(Iterable<T> entities, Duration ttl) {
     }
 
     /**
-     * Finds the Value from a key
+     * Finds the value associated with a key.
      *
      * @param key  the key
      * @param <K>  the key type
      * @param <T>  the entity type
      * @param type the entity class to convert the result
-     * @return the {@link Optional} when is not found will return a {@link Optional#empty()}
+     * @return an {@link Optional} containing the value, or {@link Optional#empty()} if not found
      * @throws NullPointerException when the key is null
      */
     <K, T> Optional<T> get(K key, Class<T> type);
 
     /**
-     * Executes a query database.
+     * Executes a database query.
      *
      * <p>
-     * <b>The query syntax belongs to each provider, thus, it is not Jakarta's NoSQL scope to define it. Accordingly, it might vary from implementation and NoSQL provider.</b>
+     * <b>The query syntax belongs to each provider, thus, it is not within Jakarta NoSQL's scope to define it.
+     * Accordingly, it might vary between implementations and NoSQL providers.</b>
      * </p>
      *
      * @param query the query
      * @param type  the entity class
      * @param <T>   the entity type
-     * @return the result list, if either <b>put</b> or <b>remove</b> it will return empty
-     * @throws NullPointerException          when query is null, if the query is <b>get</b> the entity class is required
+     * @return a stream of query results; an empty stream if no results are found
+     * @throws NullPointerException          when the query is null, or when the query is 'get' and the entity class is not provided
      * @throws UnsupportedOperationException when the provider does not support query by text
      */
     <T> Stream<T> query(String query, Class<T> type);
 
     /**
-     * Executes a query database then returns as single result
+     * Executes a database query and returns a single result.
      *
      * <p>
-     * <b>The query syntax belongs to each provider, thus, it is not Jakarta's NoSQL scope to define it. Accordingly, it might vary from implementation and NoSQL provider.</b>
+     * <b>The query syntax belongs to each provider, thus, it is not within Jakarta NoSQL's scope to define it.
+     * Accordingly, it might vary between implementations and NoSQL providers.</b>
      * </p>
      *
      * @param query the query
      * @param type  the entity class
      * @param <T>   the entity type
-     * @return the result {@link Optional}, if either <b>put</b> or <b>remove</b> it will return {@link Optional#empty()}
-     * @throws NullPointerException          when query is null, if the query is <b>get</b> the entity class is required
+     * @return an {@link Optional} containing the single result, or {@link Optional#empty()} if no result is found
+     * @throws NullPointerException          when the query is null, or when the query is 'get' and the entity class is not provided
      * @throws UnsupportedOperationException when the provider does not support query by text
      */
     <T> Optional<T> getSingleResult(String query, Class<T> type);
 
     /**
-     * Executes a query database and don't return result, e.g.: when the query is either <b>remove</b> or
-     * <b>put</b>
+     * Executes a database query without returning a result, e.g., for 'put' or 'remove' operations.
      *
      * @param query the query
-     * @throws NullPointerException          when query is null
+     * @throws NullPointerException          when the query is null
      * @throws UnsupportedOperationException when the provider does not support query by text
      */
     void query(String query);
 
     /**
-     * Executes a query database with {@link PreparedStatement}
+     * Executes a database query with a {@link PreparedStatement}.
      *
      * <p>
-     * <b>The query syntax belongs to each provider, thus, it is not Jakarta's NoSQL scope to define it. Accordingly, it might vary from implementation and NoSQL provider.</b>
+     * <b>The query syntax belongs to each provider, thus, it is not within Jakarta NoSQL's scope to define it.
+     * Accordingly, it might vary between implementations and NoSQL providers.</b>
      * </p>
      *
      * @param query the query
      * @param type  the entity class
      * @param <T>   the entity type
      * @return a {@link PreparedStatement} instance
-     * @throws NullPointerException          when query is null, if the query is <b>get</b> the entity class is required
+     * @throws NullPointerException          when the query is null, or when the query is 'get' and the entity class is not provided
      * @throws UnsupportedOperationException when the provider does not support query by text
      */
     <T> PreparedStatement prepare(String query, Class<T> type);
 
     /**
-     * Finds a list of values from keys
+     * Finds a list of values associated with the specified keys.
      *
      * @param type the entity class
      * @param keys the keys to be used in this query
      * @param <K>  the key type
      * @param <T>  the entity type
-     * @return the list of result
-     * @throws NullPointerException when either the keys or the entities values are null
+     * @return a list of results
+     * @throws NullPointerException when either the keys or the entity values are null
      */
     <K, T> Iterable<T> get(Iterable<K> keys, Class<T> type);
 
     /**
-     * Removes an entity from key
+     * Removes an entity associated with the specified key.
      *
-     * @param key the key bo be used
+     * @param key the key to be used
      * @param <K> the key type
      * @throws NullPointerException when the key is null
      */
     <K> void delete(K key);
 
     /**
-     * Removes entities from keys
+     * Removes entities associated with the specified keys.
      *
      * @param keys the keys to be used
      * @param <K>  the key type