ISPN-15060 docs review

commons/all/src/main/java/org/infinispan/commons/api/query/HitCount.java

@@ -3,7 +3,7 @@
 public interface HitCount {
 
    /**
-    * This returned value could be exact or a lower-bound of the exact value.
+    * This returned value could be either exact or a lower-bound of the exact value.
     * <p>
     * When the query is non-indexed, for performance reasons,
     * the hit count is not calculated and will return -1.
@@ -14,9 +14,9 @@ public interface HitCount {
    int value();
 
    /**
-    * For efficiency reasons the computation of the hit count could be limited to some upper bound.
+    * For efficiency reasons, the computation of the hit count could be limited to some upper bound.
     * If the hit account accuracy is limited, the {@link #value()} here could be a lower-bound of the exact value,
-    * and in this case this method will return {@code false}.
+    * and in this case, this method will return {@code false}.
     *
     * @return whether the {@link #value()} is exact
     */

commons/all/src/main/java/org/infinispan/commons/api/query/Query.java

@@ -19,32 +19,32 @@ public interface Query<T> extends Iterable<T> {
    /**
     * Returns the results of a search as a list.
     *
-    * @return list of objects that were found from the search.
+    * @return a list of objects that were found in the search.
     */
    List<T> list();
 
    /**
     *  Executes the query (a SELECT statement). Subsequent invocations cause the query to be re-executed.
     *  <p>
-    *  Executing a DELETE is also allowed. No results will be returned in this case but the number of affected entries
+    *  Executing a DELETE is also allowed. In this case, no results will be returned, but the number of affected entries
     *  will be returned as the hit count in the {@link QueryResult}.
     *
     * @return {@link QueryResult} with the results.
     */
    QueryResult<T> execute();
 
    /**
-    * Executes a data modifying statement (typically a DELETE) that does not return results; instead it returns an
-    * affected entries count. This method cannot be used to execute a SELECT.
+    * Executes a data modifying statement (typically a DELETE) that does not return results; instead it returns the
+    * count of affected entries. This method cannot be used to execute a SELECT.
     * <p>
-    * <b>NOTE:</b> Paging params (firstResult/maxResults) are NOT allowed.
+    * <b>NOTE:</b> Paging parameters (firstResult/maxResults) are NOT allowed.
     *
     * @return the number of affected (deleted) entries
     */
    int executeStatement();
 
    /**
-    * Indicates if the parsed query has projections (a SELECT clause) and consequently the returned results will
+    * Indicates if the parsed query has projections (a SELECT clause) and consequently, the returned results will
     * actually be {@code Object[]} containing the projected values rather than the target entity.
     *
     * @return {@code true} if it has projections, {@code false} otherwise.
@@ -60,13 +60,13 @@ public interface Query<T> extends Iterable<T> {
    Query<T> maxResults(int maxResults);
 
    /**
-    * @return current hitCountAccuracy if present
+    * @return the current hitCountAccuracy if present
     * @see #hitCountAccuracy(int)
     */
    Integer hitCountAccuracy();
 
    /**
-    * Limit the required accuracy of the hit count for the indexed queries to an upper-bound.
+    * Limits the required accuracy of the hit count for the indexed queries to an upper-bound.
     * Setting the hit-count-accuracy could improve the performance of queries targeting large data sets.
     *
     * @param hitCountAccuracy The value to apply
@@ -91,7 +91,7 @@ public interface Query<T> extends Iterable<T> {
    Query<T> setParameter(String paramName, Object paramValue);
 
    /**
-    * Sets multiple named parameters at once. Parameters names cannot be empty or {@code null}. Parameter values must
+    * Sets multiple named parameters at once. Parameter names cannot be empty or {@code null}. Parameter values must
     * not be {@code null}.
     *
     * @param paramValues a Map of parameters
@@ -100,7 +100,7 @@ public interface Query<T> extends Iterable<T> {
    Query<T> setParameters(Map<String, Object> paramValues);
 
    /**
-    * Returns a {@link CloseableIterator} over the results. Please close the iterator when you are done with processing
+    * Returns a {@link CloseableIterator} over the results. Close the iterator when you are done with processing
     * the results.
     *
     * @return the results of the query as an iterator.
@@ -109,7 +109,7 @@ public interface Query<T> extends Iterable<T> {
    CloseableIterator<T> iterator();
 
    /**
-    * Returns a {@link CloseableIterator} over the results, including both key and value. Please close the iterator when
+    * Returns a {@link CloseableIterator} over the results, including both key and value. Close the iterator when
     * you are done with processing the results. The query cannot use projections.
     *
     * @return the results of the query as an iterator.

core/src/main/java/org/infinispan/util/logging/Log.java

@@ -2372,7 +2372,7 @@ CacheConfigurationException storeConfiguredHasBothReadAndWriteOnly(String storeC
    @Message(value = "Query module not found. Add infinispan-query or infinispan-query-core to the classpath.", id = 695)
    CacheException queryNotSupported();
 
-   @Message(value = "Simple caches do not support queries. If you need queries, you should use standard caches.", id = 969)
+   @Message(value = "Simple caches do not support queries. Use standard caches for querying.", id = 969)
    CacheException querySimpleCacheNotSupported();
 
 }

documentation/src/main/asciidoc/topics/ref_query_ickle.adoc

@@ -1,13 +1,13 @@
 [id='ickle-queries_{context}']
 = Ickle queries
 
-To use the API, call the cache `.query()` method, passing in the string to use in the query.
+To use the API, call the cache `.query()` method and provide the query string.
 
 For instance:
 
 [source,java,tile="Using Ickle"]
 ----
-// Remote Query, using protobuf
+// Remote Query using protobuf
 Query<Transaction> q = remoteCache.create("from sample_bank_account.Transaction where amount > 20");
 
 // Embedded Query using Java Objects