2 files changed, 11 insertions, 8 deletions
diff --git a/src/main/java/com/amazon/carbonado/Query.java b/src/main/java/com/amazon/carbonado/Query.java
index 6073a84..e27e484 100644
--- a/src/main/java/com/amazon/carbonado/Query.java
+++ b/src/main/java/com/amazon/carbonado/Query.java
@@ -24,15 +24,16 @@ import com.amazon.carbonado.filter.Filter;
 import com.amazon.carbonado.filter.FilterValues;
 
 /**
- * Supports complex retrieval and deletion of {@link Storable} objects. A Query
- * is defined by {@link Storage#query}, and it merely represents an action. It
- * does not contain any data, and it is immutable. Query objects are usually
- * compiled and cached, and the same instance can be re-used for future
- * queries.
+ * Supports complex retrieval and deletion of {@link Storable} objects.
+ * Queries are immutable representations of an action \u2013 they do not
+ * contain any Storable instances. The apparent mutators (with, et al) do not
+ * actually modify the Query. Instead, they return another Query instance which
+ * has the requested modification. To obtain an initial Query instance, call
+ * one of the {@link Storage} query methods.
  *
- * <p>Query instances are thread-safe and immutable. All of the apparent
- * mutators (with, et al) do not modify the Query, but instead return a new
- * Query with the requested modification.
+ * <p>Query objects are usually compiled and cached, and the same instance can
+ * be re-used for future queries. This is possible because queries are
+ * immutable and naturally thread-safe.
  *
  * @author Brian S O'Neill
  */
diff --git a/src/main/java/com/amazon/carbonado/qe/IndexedQueryExecutor.java b/src/main/java/com/amazon/carbonado/qe/IndexedQueryExecutor.java
index d306e25..25423ee 100644
--- a/src/main/java/com/amazon/carbonado/qe/IndexedQueryExecutor.java
+++ b/src/main/java/com/amazon/carbonado/qe/IndexedQueryExecutor.java
@@ -395,6 +395,7 @@ public class IndexedQueryExecutor<S extends Storable> extends AbstractQueryExecu
          * never called by IndexedQueryExecutor.
          *
          * @return index entry query or null if not supported
+         * @since 1.2
          */
         Query<?> indexEntryQuery(StorableIndex<S> index) throws FetchException;
 
@@ -405,6 +406,7 @@ public class IndexedQueryExecutor<S extends Storable> extends AbstractQueryExecu
          * @param index index to open
          * @param indexEntryQuery query with no blank parameters, derived from
          * the query returned by indexEntryQuery
+         * @since 1.2
          */
         Cursor<S> fetchFromIndexEntryQuery(StorableIndex<S> index, Query<?> indexEntryQuery)
             throws FetchException;