add javadoc to nonintermediate classes

7 files changed, 608 insertions, 6 deletions

diff --git a/client/src/main/java/ai/vespa/client/dsl/A.java b/client/src/main/java/ai/vespa/client/dsl/A.java
index b0b801c6015..a691d1288e8 100644
--- a/client/src/main/java/ai/vespa/client/dsl/A.java
+++ b/client/src/main/java/ai/vespa/client/dsl/A.java
@@ -6,28 +6,61 @@ import java.util.Map;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
+/**
+ * Helper class for generating Annotation
+ * https://docs.vespa.ai/documentation/reference/query-language-reference.html#annotations
+ */
 public final class A {
 
     private final static Annotation EMPTY = new Annotation();
 
+    /**
+     * Empty annotation.
+     *
+     * @return the annotation
+     */
     static public Annotation empty() {
         return EMPTY;
     }
 
+    /**
+     * Filter annotation.
+     *
+     * @return the annotation
+     */
     static public Annotation filter() {
         return a("filter", true);
     }
 
+    /**
+     * Default index annotation.
+     *
+     * @param index the search index
+     * @return the annotation
+     */
     static public Annotation defaultIndex(String index) {
         return a("defaultIndex", index);
     }
 
+    /**
+     * Arbitrary key-value pair annotation.
+     *
+     * @param name  the name
+     * @param value the value
+     * @return the annotation
+     */
     public static Annotation a(String name, Object value) {
         Map<String, Object> map = new HashMap<>();
         map.put(name, value);
         return new Annotation(map);
     }
 
+    /**
+     * Arbitrary annotation given by the map.
+     *
+     * @param annotation the annotation
+     * @return the annotation
+     */
     public static Annotation a(Map<String, Object> annotation) {
         if (annotation.isEmpty()) {
             return empty();
diff --git a/client/src/main/java/ai/vespa/client/dsl/EndQuery.java b/client/src/main/java/ai/vespa/client/dsl/EndQuery.java
index 112335e7c32..4facf6ce0fb 100644
--- a/client/src/main/java/ai/vespa/client/dsl/EndQuery.java
+++ b/client/src/main/java/ai/vespa/client/dsl/EndQuery.java
@@ -7,6 +7,10 @@ import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
+/**
+ * EndQuery contains a 'Query'
+ * This object holds timeout, offset, limit, group and orderBy information before the semicolon
+ */
 public class EndQuery {
 
     QueryChain queryChain;
@@ -38,47 +42,118 @@ public class EndQuery {
         return this;
     }
 
+    /**
+     * Offset.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#limit-offset
+     *
+     * @param offset the offset
+     * @return the end query
+     */
     public EndQuery offset(int offset) {
         return this.setOffset(offset);
     }
 
+    /**
+     * Timeout.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#timeout
+     *
+     * @param timeout the timeout
+     * @return the end query
+     */
     public EndQuery timeout(int timeout) {
         return this.setTimeout(timeout);
     }
 
+    /**
+     * Limit.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#limit-offset
+     *
+     * @param limit the limit
+     * @return the end query
+     */
     public EndQuery limit(int limit) {
         return this.setLimit(limit);
     }
 
+    /**
+     * Semicolon.
+     * turn a query into fixed query.
+     *
+     * @return the fixed query
+     */
     public FixedQuery semicolon() {
         return new FixedQuery(this);
     }
 
+    /**
+     * Group.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#grouping
+     *
+     * @param group the group
+     * @return the end query
+     */
     public EndQuery group(Group group) {
         this.groupQueryStr = group.toString();
         return this;
     }
 
+    /**
+     * Group.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#grouping
+     *
+     * @param groupQueryStr the group str
+     * @return the end query
+     */
     public EndQuery group(String groupQueryStr) {
         this.groupQueryStr = groupQueryStr;
         return this;
     }
 
+    /**
+     * Order by asc.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#order-by
+     *
+     * @param annotation the annotation
+     * @param fieldName the field name
+     * @return the end query
+     */
     public EndQuery orderByAsc(Annotation annotation, String fieldName) {
         order.add(new Object[]{annotation, fieldName, "asc"});
         return this;
     }
 
+    /**
+     * Order by asc.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#order-by
+     *
+     * @param fieldName the field name
+     * @return the end query
+     */
     public EndQuery orderByAsc(String fieldName) {
         order.add(new Object[]{A.empty(), fieldName, "asc"});
         return this;
     }
 
+    /**
+     * Order by desc.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#order-by
+     *
+     * @param annotation the annotation
+     * @param fieldName the field name
+     * @return the end query
+     */
     public EndQuery orderByDesc(Annotation annotation, String fieldName) {
         order.add(new Object[]{annotation, fieldName, "desc"});
         return this;
     }
 
+    /**
+     * Order by desc.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#order-by
+     *
+     * @param fieldName the field name
+     * @return the end query
+     */
     public EndQuery orderByDesc(String fieldName) {
         order.add(new Object[]{A.empty(), fieldName, "desc"});
         return this;
diff --git a/client/src/main/java/ai/vespa/client/dsl/Field.java b/client/src/main/java/ai/vespa/client/dsl/Field.java
index 1a82430deb7..0cbe03a8fb9 100644
--- a/client/src/main/java/ai/vespa/client/dsl/Field.java
+++ b/client/src/main/java/ai/vespa/client/dsl/Field.java
@@ -25,18 +25,48 @@ public class Field extends QueryChain {
         this.fieldName = fieldName;
     }
 
+    /**
+     * Contains query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param value the value
+     * @return the query
+     */
     public Query contains(String value) {
         return contains(A.empty(), value);
     }
 
+    /**
+     * Contains query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param annotation the annotation
+     * @param value      the value
+     * @return the query
+     */
     public Query contains(Annotation annotation, String value) {
         return common("contains", annotation, value);
     }
 
+    /**
+     * Contains phrase query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param value  the value
+     * @param others the others
+     * @return the query
+     */
     public Query containsPhrase(String value, String... others) {
         return common("phrase", annotation, value, others);
     }
 
+    /**
+     * Contains phrase query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param values the values
+     * @return the query
+     */
     public Query containsPhrase(List<String> values) {
         if (values.isEmpty()) {
             throw new IllegalArgumentException("value of \"contains phrase\" should not be empty");
@@ -45,10 +75,25 @@ public class Field extends QueryChain {
         return common("phrase", annotation, values);
     }
 
+    /**
+     * Contains near query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param value  the value
+     * @param others the others
+     * @return the query
+     */
     public Query containsNear(String value, String... others) {
         return common("near", annotation, value, others);
     }
 
+    /**
+     * Contains near query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param values the values
+     * @return the query
+     */
     public Query containsNear(List<String> values) {
         if (values.isEmpty()) {
             throw new IllegalArgumentException("value of \"contains near\" should not be empty");
@@ -57,10 +102,27 @@ public class Field extends QueryChain {
         return common("near", annotation, values);
     }
 
+    /**
+     * Contains near query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param annotation the annotation
+     * @param value      the value
+     * @param others     the others
+     * @return the query
+     */
     public Query containsNear(Annotation annotation, String value, String... others) {
         return common("near", annotation, value, others);
     }
 
+    /**
+     * Contains near query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param annotation the annotation
+     * @param values     the values
+     * @return the query
+     */
     public Query containsNear(Annotation annotation, List<String> values) {
         if (values.isEmpty()) {
             throw new IllegalArgumentException("value of \"contains near\" should not be empty");
@@ -69,10 +131,25 @@ public class Field extends QueryChain {
         return common("near", annotation, values);
     }
 
+    /**
+     * Contains onear query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param value  the value
+     * @param others the others
+     * @return the query
+     */
     public Query containsOnear(String value, String... others) {
         return common("onear", annotation, value, others);
     }
 
+    /**
+     * Contains onear query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param values the values
+     * @return the query
+     */
     public Query containsOnear(List<String> values) {
         if (values.isEmpty()) {
             throw new IllegalArgumentException("value of \"contains onear\" should not be empty");
@@ -81,10 +158,27 @@ public class Field extends QueryChain {
         return common("onear", annotation, values);
     }
 
+    /**
+     * Contains onear query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param annotation the annotation
+     * @param value      the value
+     * @param others     the others
+     * @return the query
+     */
     public Query containsOnear(Annotation annotation, String value, String... others) {
         return common("onear", annotation, value, others);
     }
 
+    /**
+     * Contains onear query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param annotation the annotation
+     * @param values     the values
+     * @return the query
+     */
     public Query containsOnear(Annotation annotation, List<String> values) {
         if (values.isEmpty()) {
             throw new IllegalArgumentException("value of \"contains onear\" should not be empty");
@@ -93,14 +187,36 @@ public class Field extends QueryChain {
         return common("onear", annotation, values);
     }
 
+    /**
+     * Contains same element query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param andQuery the and query
+     * @return the query
+     */
     public Query containsSameElement(Query andQuery) {
         return common("sameElement", annotation, andQuery);
     }
 
+    /**
+     * Contains equiv query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param value  the value
+     * @param others the others
+     * @return the query
+     */
     public Query containsEquiv(String value, String... others) {
         return containsEquiv(Stream.concat(Stream.of(value), Stream.of(others)).collect(Collectors.toList()));
     }
 
+    /**
+     * Contains equiv query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param values the values
+     * @return the query
+     */
     public Query containsEquiv(List<String> values) {
         if (values.isEmpty()) {
             throw new IllegalArgumentException("value of \"contains equiv\" should not be empty");
@@ -112,71 +228,191 @@ public class Field extends QueryChain {
         }
     }
 
+    /**
+     * Contains uri query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param value the value
+     * @return the query
+     */
     public Query containsUri(String value) {
         return common("uri", annotation, value) ;
     }
 
+    /**
+     * Contains uri query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#contains
+     *
+     * @param annotation the annotation
+     * @param value      the value
+     * @return the query
+     */
     public Query containsUri(Annotation annotation, String value) {
         return common("uri", annotation, value) ;
     }
 
+    /**
+     * Matches query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#matches
+     *
+     * @param str the str
+     * @return the query
+     */
     public Query matches(String str) {
         return common("matches", annotation, str);
     }
 
+    /**
+     * Equals query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query eq(int t) {
         return common("=", annotation, t);
     }
 
+    /**
+     * Greater than or equal to query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query ge(int t) {
         return common(">=", annotation, t);
     }
 
+    /**
+     * Greater than query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query gt(int t) {
         return common(">", annotation, t);
     }
 
+    /**
+     * Less than or equal to query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query le(int t) {
         return common("<=", annotation, t);
     }
 
+    /**
+     * Less than query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query lt(int t) {
         return common("<", annotation, t);
     }
 
+    /**
+     * In range query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param l the l
+     * @param m the m
+     * @return the query
+     */
     public Query inRange(int l, int m) {
         return common("range", annotation, l, new Integer[]{m});
     }
 
+    /**
+     * Equal to query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query eq(long t) {
         return common("=", annotation, t);
     }
 
+    /**
+     * Greater than or equal to query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query ge(long t) {
         return common(">=", annotation, t);
     }
 
+    /**
+     * Greater than query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query gt(long t) {
         return common(">", annotation, t);
     }
 
+    /**
+     * Less than or equal to query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query le(long t) {
         return common("<=", annotation, t);
     }
 
+    /**
+     * Less than query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param t the t
+     * @return the query
+     */
     public Query lt(long t) {
         return common("<", annotation, t);
     }
 
+    /**
+     * In range query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#numeric
+     *
+     * @param l the l
+     * @param m the m
+     * @return the query
+     */
     public Query inRange(long l, long m) {
         return common("range", annotation, l, new Long[]{m});
     }
 
 
+    /**
+     * Is true query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#boolean
+     *
+     * @return the query
+     */
     public Query isTrue() {
         return common("=", annotation, true);
     }
 
+    /**
+     * Is false query.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#boolean
+     *
+     * @return the query
+     */
     public Query isFalse() {
         return common("=", annotation, false);
     }
@@ -264,6 +500,12 @@ public class Field extends QueryChain {
         return hasNegativeSearchField(fieldName) && valuesContains(value);
     }
 
+    /**
+     * Values contains boolean.
+     *
+     * @param value the value
+     * @return the boolean
+     */
     boolean valuesContains(Object value) {
         if (value instanceof String) {
             value = "\"" + value + "\"";
diff --git a/client/src/main/java/ai/vespa/client/dsl/FixedQuery.java b/client/src/main/java/ai/vespa/client/dsl/FixedQuery.java
index 7b9872cbe11..02f1f294d14 100644
--- a/client/src/main/java/ai/vespa/client/dsl/FixedQuery.java
+++ b/client/src/main/java/ai/vespa/client/dsl/FixedQuery.java
@@ -9,14 +9,18 @@ import java.util.Map;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.stream.Collectors;
 
+/**
+ * FixedQuery contains a 'Query' which is terminated by a 'semicolon'
+ * This object holds vespa or user defined parameters
+ * https://docs.vespa.ai/documentation/reference/search-api-reference.html
+ */
 public class FixedQuery {
 
     final EndQuery endQuery;
     Map<String, String> others = new HashMap<>();
     Map<String, String> queryMap;
 
-
-    public FixedQuery(EndQuery endQuery) {
+    FixedQuery(EndQuery endQuery) {
         this.endQuery = endQuery;
     }
 
@@ -330,6 +334,12 @@ public class FixedQuery {
         return this;
     }
 
+
+    /**
+     * build the query map from the query
+     *
+     * @return the query map
+     */
     public Map<String, String> buildQueryMap() {
         if (queryMap != null) {
             return queryMap;
@@ -357,7 +367,11 @@ public class FixedQuery {
         return queryMap;
     }
 
-
+    /**
+     * build the vespa query string join by '&'
+     *
+     * @return the query string
+     */
     public String build() {
         return buildQueryMap().entrySet().stream().map(entry -> entry.getKey() + "=" + entry.getValue())
             .collect(Collectors.joining("&"));
diff --git a/client/src/main/java/ai/vespa/client/dsl/G.java b/client/src/main/java/ai/vespa/client/dsl/G.java
index f93cbe249b8..4a82658d3e0 100644
--- a/client/src/main/java/ai/vespa/client/dsl/G.java
+++ b/client/src/main/java/ai/vespa/client/dsl/G.java
@@ -2,6 +2,14 @@
 package ai.vespa.client.dsl;
 
 
+/**
+ * Helper class for generating group syntax
+ * https://docs.vespa.ai/documentation/reference/grouping-syntax.html
+ *
+ * basically the syntax is exactly the same as Vespa group syntax.
+ * The only exception "max" in the Vespa group syntax which represents 'max returned documents',
+ * is replaced by "maxRtn" in the dsl lib.
+ */
 public final class G {
 
     public static Group all(IGroupOperation... ops) {
diff --git a/client/src/main/java/ai/vespa/client/dsl/Q.java b/client/src/main/java/ai/vespa/client/dsl/Q.java
index c6aedeca12e..4048e6b8869 100644
--- a/client/src/main/java/ai/vespa/client/dsl/Q.java
+++ b/client/src/main/java/ai/vespa/client/dsl/Q.java
@@ -6,67 +6,166 @@ import com.google.gson.Gson;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Helper class for generating Vespa search queries
+ * https://docs.vespa.ai/documentation/reference/query-language-reference.html
+ */
 public final class Q {
 
     static Gson gson = new Gson();
     private static Sources SELECT_ALL_FROM_SOURCES_ALL = new Sources(new Select("*"), "*");
 
-    public static Select select(String fieldName) {
-        return new Select(fieldName);
+    public static Select select(String fieldName) { return new Select(fieldName);
     }
 
     public static Select select(String fieldName, String... others) {
         return new Select(fieldName, others);
     }
 
+    /**
+     * P represents "parentheses", used for generated a query in the parentheses.
+     *
+     * @param fieldName the field name
+     * @return the field
+     */
     public static Field p(String fieldName) {
         return SELECT_ALL_FROM_SOURCES_ALL.where(fieldName);
     }
 
+    /**
+     * P represents "parentheses", used for generated a query in the parentheses.
+     *
+     * @param query the query
+     * @return the query
+     */
     public static Query p(QueryChain query) {
         return new Query(SELECT_ALL_FROM_SOURCES_ALL, query);
     }
 
+    /**
+     * P represents "parentheses", used for generated a query in the parentheses.
+     * This method generates an empty query
+     *
+     * @return the empty query
+     */
     public static Query p() {
         return new Query(SELECT_ALL_FROM_SOURCES_ALL);
     }
 
+    /**
+     * Rank rank.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#rank
+     *
+     * @param query the query
+     * @param ranks the ranks
+     * @return the rank query
+     */
     public static Rank rank(Query query, Query... ranks) {
         return new Rank(query, ranks);
     }
 
+    /**
+     * UI represents "userInput".
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#userinput
+     *
+     * @param value the value
+     * @return the user input query
+     */
     public static UserInput ui(String value) {
         return new UserInput(value);
     }
 
+    /**
+     * userInput with an annotation.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#userinput
+     *
+     * @param a     the a
+     * @param value the value
+     * @return the user input query
+     */
     public static UserInput ui(Annotation a, String value) {
         return new UserInput(a, value);
     }
 
+    /**
+     * A convenience method to generate userInput with default index annotation.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#userinput
+     *
+     * @param index the index
+     * @param value the value
+     * @return the user input query
+     */
     public static UserInput ui(String index, String value) {
         return ui(A.defaultIndex(index), value);
     }
 
+    /**
+     * dotPdt represents "dotProduct".
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#dotproduct
+     *
+     * @param field       the field
+     * @param weightedSet the weighted set
+     * @return the dot product query
+     */
     public static DotProduct dotPdt(String field, Map<String, Integer> weightedSet) {
         return new DotProduct(field, weightedSet);
     }
 
+    /**
+     * wtdSet represents "weightedSet".
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#weightedset
+     *
+     * @param field       the field
+     * @param weightedSet the weighted set
+     * @return the weighted set query
+     */
     public static WeightedSet wtdSet(String field, Map<String, Integer> weightedSet) {
         return new WeightedSet(field, weightedSet);
     }
 
+    /**
+     * NonEmpty non empty.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#nonempty
+     *
+     * @param query the query
+     * @return the non empty query
+     */
     public static NonEmpty nonEmpty(Query query) {
         return new NonEmpty(query);
     }
 
+    /**
+     * Wand wand.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#wand
+     *
+     * @param field       the field
+     * @param weightedSet the weighted set
+     * @return the wand query
+     */
     public static Wand wand(String field, Map<String, Integer> weightedSet) {
         return new Wand(field, weightedSet);
     }
 
+    /**
+     * Wand wand.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#wand
+     *
+     * @param field        the field
+     * @param numericRange the numeric range
+     * @return the wand query
+     */
     public static Wand wand(String field, List<List<Integer>> numericRange) {
         return new Wand(field, numericRange);
     }
 
+    /**
+     * Weakand weak and.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#weakand
+     *
+     * @param field the field
+     * @param query the query
+     * @return the weak and query
+     */
     public static WeakAnd weakand(String field, Query query) {
         return new WeakAnd(field, query);
     }
diff --git a/client/src/main/java/ai/vespa/client/dsl/Query.java b/client/src/main/java/ai/vespa/client/dsl/Query.java
index 3d10f5c429f..62f92c51bee 100644
--- a/client/src/main/java/ai/vespa/client/dsl/Query.java
+++ b/client/src/main/java/ai/vespa/client/dsl/Query.java
@@ -6,11 +6,13 @@ import java.util.List;
 import java.util.Objects;
 import java.util.stream.Collectors;
 
+/**
+ * Vespa query object
+ */
 public class Query extends QueryChain {
 
     Annotation annotation;
     Sources sources;
-
     List<QueryChain> queries = new ArrayList<>();
 
     Query(Sources sources, QueryChain queryChain) {
@@ -86,6 +88,13 @@ public class Query extends QueryChain {
         return sb.toString().trim();
     }
 
+    /**
+     * And.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#and
+     *
+     * @param fieldName the field name
+     * @return the field
+     */
     public Field and(String fieldName) {
         Field f = new Field(this, fieldName);
         f.setOp("and");
@@ -94,6 +103,13 @@ public class Query extends QueryChain {
         return f;
     }
 
+    /**
+     * Andnot.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#andnot
+     *
+     * @param fieldName the field name
+     * @return the field
+     */
     public Field andnot(String fieldName) {
         Field f = new Field(this, fieldName);
         f.setOp("andnot");
@@ -102,6 +118,13 @@ public class Query extends QueryChain {
         return f;
     }
 
+    /**
+     * Or.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#or
+     *
+     * @param fieldName the field name
+     * @return the field
+     */
     public Field or(String fieldName) {
         Field f = new Field(this, fieldName);
         f.setOp("or");
@@ -110,6 +133,13 @@ public class Query extends QueryChain {
         return f;
     }
 
+    /**
+     * And.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#and
+     *
+     * @param query the query
+     * @return the query
+     */
     public Query and(QueryChain query) {
         query.setOp("and");
         queries.add(query);
@@ -117,6 +147,13 @@ public class Query extends QueryChain {
         return this;
     }
 
+    /**
+     * Andnot.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#andnot
+     *
+     * @param query the query
+     * @return the query
+     */
     public Query andnot(QueryChain query) {
         query.setOp("andnot");
         queries.add(query);
@@ -124,6 +161,13 @@ public class Query extends QueryChain {
         return this;
     }
 
+    /**
+     * Or.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#or
+     *
+     * @param query the query
+     * @return the query
+     */
     public Query or(QueryChain query) {
         query.setOp("or");
         queries.add(query);
@@ -131,39 +175,126 @@ public class Query extends QueryChain {
         return this;
     }
 
+    /**
+     * Annotate a query (sub-expression).
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#annotations-of-sub-expressions
+     *
+     * @param annotation the annotation
+     * @return the query
+     */
     public Query annotate(Annotation annotation) {
         this.annotation = annotation;
         return this;
     }
 
+    /**
+     * Offset.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#limit-offset
+     *
+     * @param offset the offset
+     * @return the end query
+     */
     public EndQuery offset(int offset) {
         return new EndQuery(this).offset(offset);
     }
 
+    /**
+     * Limit.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#limit-offset
+     *
+     * @param hits the hits
+     * @return the end query
+     */
     public EndQuery limit(int hits) {
         return new EndQuery(this).limit(hits);
     }
 
+    /**
+     * Timeout.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#timeout
+     *
+     * @param timeout the timeout
+     * @return the end query
+     */
     public EndQuery timeout(int timeout) {
         return new EndQuery(this).timeout(timeout);
     }
 
+    /**
+     * Group.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#grouping
+     *
+     * @param group the group
+     * @return the end query
+     */
     public EndQuery group(Group group) {
         return new EndQuery(this).group(group);
     }
 
+    /**
+     * Group.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#grouping
+     *
+     * @param groupStr the group str
+     * @return the end query
+     */
     public EndQuery group(String groupStr) {
         return new EndQuery(this).group(groupStr);
     }
 
+    /**
+     * Order by asc.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#order-by
+     *
+     * @param fieldName the field name
+     * @return the end query
+     */
     public EndQuery orderByAsc(String fieldName) {
         return new EndQuery(this).orderByAsc(fieldName);
     }
 
+    /**
+     * Order by asc.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#order-by
+     *
+     * @param annotation the annotation
+     * @param fieldName the field name
+     * @return the end query
+     */
+    public EndQuery orderByAsc(Annotation annotation, String fieldName) {
+        return new EndQuery(this).orderByAsc(annotation, fieldName);
+    }
+
+    /**
+     * Order by desc.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#order-by
+     *
+     * @param fieldName the field name
+     * @return the end query
+     */
     public EndQuery orderByDesc(String fieldName) {
         return new EndQuery(this).orderByDesc(fieldName);
     }
 
+
+    /**
+     * Order by desc.
+     * https://docs.vespa.ai/documentation/reference/query-language-reference.html#order-by
+     *
+     * @param annotation the annotation
+     * @param fieldName the field name
+     * @return the end query
+     */
+    public EndQuery orderByDesc(Annotation annotation, String fieldName) {
+        return new EndQuery(this).orderByDesc(annotation, fieldName);
+    }
+
+    /**
+     * Semicolon.
+     * turn a query into fixed query.
+     *
+     * @return the fixed query
+     */
     public FixedQuery semicolon() {
         return new FixedQuery(new EndQuery(this));
     }