From af610e41e622cc9c0addbe59ee4f8cca94a49913 Mon Sep 17 00:00:00 2001
From: Aditya <aditya@mapr.com>
Date: Tue, 28 Mar 2017 17:10:06 -0700
Subject: [PATCH] Fixed miscellaneous documentation issues.

---
 core/src/main/java/org/ojai/store/Query.java | 88 +++++++++++++-------
 readme.md                                    |  4 +-
 2 files changed, 58 insertions(+), 34 deletions(-)

diff --git a/core/src/main/java/org/ojai/store/Query.java b/core/src/main/java/org/ojai/store/Query.java
index cd726b2..df39c60 100644
--- a/core/src/main/java/org/ojai/store/Query.java
+++ b/core/src/main/java/org/ojai/store/Query.java
@@ -26,9 +26,12 @@
 public interface Query {
 
   /**
-   * <p>Set a named query option. A query option can be used to provide hints to query execution engine.
-   * However, under stable conditions, a query option can not alter the result of the query</p>
-   * <p>Refer to OJAI Driver's documentation for the list of supported options.</p>
+   * Set a named query option. A query option can be used to provide hints to query execution engine.
+   * However, under stable conditions, a query option can not alter the result of the query.
+   * <p/>
+   * Refer to OJAI Driver's documentation for the list of supported options.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query setOption(String optionName, Object value) throws IllegalArgumentException;
 
@@ -40,103 +43,124 @@ public interface Query {
   public Object getOption(String optionName);
 
   /**
-   * <p>Set multiple query options.
-   * If not specified, the entire Document will be returned.</p>
+   * Set multiple query options for this Query.
    *
-   * Multiple invocation will append new fields to the list.
+   * @return {@code this} for chained invocation.
    */
   public Query setOptions(Document options) throws IllegalArgumentException;
 
   /**
-   * <p>Add the list of field paths to the list of projected fields.
-   * If not specified, the entire Document will be returned.</p>
-   *
+   * Add the list of field paths to the list of projected fields.
+   * If not specified, the entire Document will be returned.
+   * <p/>
    * Multiple invocation will append new fields to the list.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query select(String... fieldPaths) throws IllegalArgumentException;
 
   /**
-   * <p>Add the list of field paths to the list of projected fields.
-   * If not specified, the entire Document will be returned.</p>
-   *
+   * Add the list of field paths to the list of projected fields.
+   * If not specified, the entire Document will be returned.
+   * <p/>
    * Multiple invocation will append new fields to the list.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query select(FieldPath... fieldPaths) throws IllegalArgumentException;
 
   /**
-   * <p>Sets the filtering condition for the query.</p>
-   *
+   * Sets the filtering condition for the query.
+   * <p/>
    * Multiple invocation will 'AND' the individual conditions.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query where(String conditionJson) throws OjaiException, IllegalArgumentException;
 
   /**
-   * <p>Sets the filtering condition for the query.</p>
-   *
+   * Sets the filtering condition for the query.
+   * <p/>
    * Multiple invocation will 'AND' the individual conditions.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query where(QueryCondition condition) throws OjaiException, IllegalArgumentException;
 
   /**
-   * <p>Sets the sort ordering of the returned Documents to the ascending order of specified field paths.</p>
-   *
+   * Sets the sort ordering of the returned Documents to the ascending order of specified field paths.
+   * <p/>
    * Multiple invocation will append the field to the sort list.
    *
    * @throws IllegalArgumentException if the same field is specified more than once.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query orderBy(String... fieldPaths) throws IllegalArgumentException;
 
   /**
-   * <p>Sets the sort ordering of the returned Documents to the ascending order of specified field paths.</p>
-   *
+   * Sets the sort ordering of the returned Documents to the ascending order of specified field paths.
+   * <p/>
    * Multiple invocation will append the field to the sort list.
    *
    * @throws IllegalArgumentException if the same field is specified more than once.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query orderBy(FieldPath... fieldPaths) throws IllegalArgumentException;
 
   /**
-   * <p>Sets the sort ordering of the returned Documents to the specified field and order.</p>
-   *
+   * Sets the sort ordering of the returned Documents to the specified field and order.
+   * <p/>
    * Multiple invocation will append the field to the sort list.
    *
    * @throws IllegalArgumentException if the same field is specified more than once.
    * @throws IllegalArgumentException if the supplied field path can not be parsed or
    *         order is neither "ASC" or "DESC", ignoring case.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query orderBy(String field, String order) throws IllegalArgumentException;
 
   /**
-   * <p>Sets the sort ordering of the returned Documents to the specified field and order.</p>
-   *
+   * Sets the sort ordering of the returned Documents to the specified field and order.
+   * <p/>
    * Multiple invocation will append the field to the sort list.
    *
    * @throws IllegalArgumentException if the same field is specified more than once.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query orderBy(String field, SortOrder order) throws IllegalArgumentException;
 
   /**
-   * <p>Sets the sort ordering of the returned Documents to the specified field and order.</p>
-   *
+   * Sets the sort ordering of the returned Documents to the specified field and order.
+   * <p/>
    * Multiple invocation will append the field to the sort list.
    *
    * @throws IllegalArgumentException if the same field is specified more than once.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query orderBy(FieldPath field, SortOrder order) throws IllegalArgumentException;
 
   /**
-   * <p>{@code Zero} (0) based index which specifies number of Documents to skip before
-   * returning any result. Negative values are not permitted.</p>
-   *
+   * {@code Zero} (0) based index which specifies number of Documents to skip before
+   * returning any result. Negative values are not permitted.
+   * <p/>
    * Multiple invocation will overwrite the previous value.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query offset(long offset) throws IllegalArgumentException;
 
   /**
-   * <p>Restricts the maximum number of documents returned from this query
-   * to the specified value. Negative values are not permitted.</p>
-   *
+   * Restricts the maximum number of documents returned from this query
+   * to the specified value. Negative values are not permitted.
+   * <p/>
    * Multiple invocation will overwrite the previous value.
+   *
+   * @return {@code this} for chained invocation.
    */
   public Query limit(long limit) throws IllegalArgumentException;
 
diff --git a/readme.md b/readme.md
index 10cbf1f..954d4ce 100644
--- a/readme.md
+++ b/readme.md
@@ -2,7 +2,7 @@
 
 OJAI is a general-purpose JSON access layer that sits on databases, file systems, and message streams which enables access to structured, semi-structured and unstructured data using a common API.
 
-##Documents
+## Documents
 
 The OJAI API specification is centered around documents that follow a JSON-like data model. Documents can describe entities such as products, people, and places, much more easily and in greater detail than can tables in relational databases. The greater flexibility and richness are due to the lack of schemas in documents, the ability to nest data within other data, the ability to create arrays, and in general the ability to range from simple to very complex data within a single document.
 
@@ -33,7 +33,7 @@ The structure of each document, called the document's schema, is easy to change.
 
 For more about documents, see [Documents](https://github.com/ojai/ojai/wiki/1.-Documents) in the OJAI wiki.
 
-##Interfaces for Working with Documents
+## Interfaces for Working with Documents
 The OJAI specification provides two types of APIs for creating, reading, and updating documents within the context of a client application: Document Object Model (DOM)-based APIs and event-driven APIs. 
 
 ### Document Object Model-based APIs