Merge pull request #275 from ajkannan/query-javadoc

aozarov · aozarov · commit 99a4091760b6 · 2015-10-20T17:12:46.000-07:00
Add Javadocs for set vs add in StructuredQuery's builder
diff --git a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/StructuredQuery.java b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/StructuredQuery.java
@@ -113,6 +113,9 @@ static Filter fromPb(DatastoreV1.Filter filterPb) {
     }
   }
 
+  /**
+   * A class representing a filter composed of a combination of other filters.
+   */
   public static final class CompositeFilter extends Filter {
 
     private static final long serialVersionUID = 3610352685739360009L;
@@ -194,6 +197,9 @@ protected DatastoreV1.Filter toPb() {
     }
   }
 
+  /**
+   * A class representing a filter based on a single property or ancestor.
+   */
   public static final class PropertyFilter extends Filter {
 
     private static final long serialVersionUID = -4514695915258598597L;
@@ -514,6 +520,9 @@ static OrderBy fromPb(DatastoreV1.PropertyOrder propertyOrderPb) {
     }
   }
 
+  /**
+   * A class representing a projection based on a property.
+   */
   public static final class Projection implements Serializable {
 
     private static final long serialVersionUID = 3083707957256279470L;
@@ -665,12 +674,18 @@ public B clearOrderBy() {
       return self();
     }
 
+    /**
+     * Sets the query's order by clause (clearing any previously specified OrderBy settings).
+     */
     public B orderBy(OrderBy orderBy, OrderBy... others) {
       clearOrderBy();
       addOrderBy(orderBy, others);
       return self();
     }
 
+    /**
+     * Adds settings to the existing order by clause.
+     */
     public B addOrderBy(OrderBy orderBy, OrderBy... others) {
       this.orderBy.add(orderBy);
       Collections.addAll(this.orderBy, others);
@@ -754,6 +769,9 @@ static final class Builder<V> extends BaseBuilder<V, Builder<V>> {
     }
   }
 
+  /**
+   * A StructuredQuery builder for queries that return Entity results.
+   */
   public static final class EntityQueryBuilder extends BaseBuilder<Entity, EntityQueryBuilder> {
 
     EntityQueryBuilder() {
@@ -766,6 +784,9 @@ public StructuredQuery<Entity> build() {
     }
   }
 
+  /**
+   * A StructuredQuery builder for queries that return Key results.
+   */
   public static final class KeyQueryBuilder extends BaseBuilder<Key, KeyQueryBuilder> {
 
     KeyQueryBuilder() {
@@ -787,6 +808,9 @@ public StructuredQuery<Key> build() {
     }
   }
 
+  /**
+   * A StructuredQuery builder for projection queries.
+   */
   public static final class ProjectionEntityQueryBuilder
       extends BaseBuilder<ProjectionEntity, ProjectionEntityQueryBuilder> {
 
@@ -804,11 +828,17 @@ public ProjectionEntityQueryBuilder clearProjection() {
       return super.clearProjection();
     }
 
+    /**
+     * Sets the query's projection clause (clearing any previously specified Projection settings).
+     */
     @Override
     public ProjectionEntityQueryBuilder projection(Projection projection, Projection... others) {
       return super.projection(projection, others);
     }
 
+    /**
+     * Adds one or more projections to the existing projection clause.
+     */
     @Override
     public ProjectionEntityQueryBuilder addProjection(Projection projection, Projection... others) {
       return super.addProjection(projection, others);
@@ -819,11 +849,17 @@ public ProjectionEntityQueryBuilder clearGroupBy() {
       return super.clearGroupBy();
     }
 
+    /**
+     * Sets the query's group by clause (clearing any previously specified GroupBy settings).
+     */
     @Override
     public ProjectionEntityQueryBuilder groupBy(String property, String... others) {
       return super.groupBy(property, others);
     }
 
+    /**
+     * Adds one or more properties to the existing group by clause.
+     */
     @Override
     public ProjectionEntityQueryBuilder addGroupBy(String property, String... others) {
       return super.addGroupBy(property, others);

Original file line number	Diff line number	Diff line change
`@@ -113,6 +113,9 @@ static Filter fromPb(DatastoreV1.Filter filterPb) {`
`113`	`113`	`}`
`114`	`114`	`}`
`115`	`115`
	`116`	`+ /**`
	`117`	`+ * A class representing a filter composed of a combination of other filters.`
	`118`	`+ */`
`116`	`119`	`public static final class CompositeFilter extends Filter {`
`117`	`120`
`118`	`121`	`private static final long serialVersionUID = 3610352685739360009L;`
`@@ -194,6 +197,9 @@ protected DatastoreV1.Filter toPb() {`
`194`	`197`	`}`
`195`	`198`	`}`
`196`	`199`
	`200`	`+ /**`
	`201`	`+ * A class representing a filter based on a single property or ancestor.`
	`202`	`+ */`
`197`	`203`	`public static final class PropertyFilter extends Filter {`
`198`	`204`
`199`	`205`	`private static final long serialVersionUID = -4514695915258598597L;`
`@@ -514,6 +520,9 @@ static OrderBy fromPb(DatastoreV1.PropertyOrder propertyOrderPb) {`
`514`	`520`	`}`
`515`	`521`	`}`
`516`	`522`
	`523`	`+ /**`
	`524`	`+ * A class representing a projection based on a property.`
	`525`	`+ */`
`517`	`526`	`public static final class Projection implements Serializable {`
`518`	`527`
`519`	`528`	`private static final long serialVersionUID = 3083707957256279470L;`
`@@ -665,12 +674,18 @@ public B clearOrderBy() {`
`665`	`674`	`return self();`
`666`	`675`	`}`
`667`	`676`
	`677`	`+ /**`
	`678`	`+ * Sets the query's order by clause (clearing any previously specified OrderBy settings).`
	`679`	`+ */`
`668`	`680`	`public B orderBy(OrderBy orderBy, OrderBy... others) {`
`669`	`681`	`clearOrderBy();`
`670`	`682`	`addOrderBy(orderBy, others);`
`671`	`683`	`return self();`
`672`	`684`	`}`
`673`	`685`
	`686`	`+ /**`
	`687`	`+ * Adds settings to the existing order by clause.`
	`688`	`+ */`
`674`	`689`	`public B addOrderBy(OrderBy orderBy, OrderBy... others) {`
`675`	`690`	`this.orderBy.add(orderBy);`
`676`	`691`	`Collections.addAll(this.orderBy, others);`
`@@ -754,6 +769,9 @@ static final class Builder<V> extends BaseBuilder<V, Builder<V>> {`
`754`	`769`	`}`
`755`	`770`	`}`
`756`	`771`
	`772`	`+ /**`
	`773`	`+ * A StructuredQuery builder for queries that return Entity results.`
	`774`	`+ */`
`757`	`775`	`public static final class EntityQueryBuilder extends BaseBuilder<Entity, EntityQueryBuilder> {`
`758`	`776`
`759`	`777`	`EntityQueryBuilder() {`
`@@ -766,6 +784,9 @@ public StructuredQuery<Entity> build() {`
`766`	`784`	`}`
`767`	`785`	`}`
`768`	`786`
	`787`	`+ /**`
	`788`	`+ * A StructuredQuery builder for queries that return Key results.`
	`789`	`+ */`
`769`	`790`	`public static final class KeyQueryBuilder extends BaseBuilder<Key, KeyQueryBuilder> {`
`770`	`791`
`771`	`792`	`KeyQueryBuilder() {`
`@@ -787,6 +808,9 @@ public StructuredQuery<Key> build() {`
`787`	`808`	`}`
`788`	`809`	`}`
`789`	`810`
	`811`	`+ /**`
	`812`	`+ * A StructuredQuery builder for projection queries.`
	`813`	`+ */`
`790`	`814`	`public static final class ProjectionEntityQueryBuilder`
`791`	`815`	`extends BaseBuilder<ProjectionEntity, ProjectionEntityQueryBuilder> {`
`792`	`816`
`@@ -804,11 +828,17 @@ public ProjectionEntityQueryBuilder clearProjection() {`
`804`	`828`	`return super.clearProjection();`
`805`	`829`	`}`
`806`	`830`
	`831`	`+ /**`
	`832`	`+ * Sets the query's projection clause (clearing any previously specified Projection settings).`
	`833`	`+ */`
`807`	`834`	`@Override`
`808`	`835`	`public ProjectionEntityQueryBuilder projection(Projection projection, Projection... others) {`
`809`	`836`	`return super.projection(projection, others);`
`810`	`837`	`}`
`811`	`838`
	`839`	`+ /**`
	`840`	`+ * Adds one or more projections to the existing projection clause.`
	`841`	`+ */`
`812`	`842`	`@Override`
`813`	`843`	`public ProjectionEntityQueryBuilder addProjection(Projection projection, Projection... others) {`
`814`	`844`	`return super.addProjection(projection, others);`
`@@ -819,11 +849,17 @@ public ProjectionEntityQueryBuilder clearGroupBy() {`
`819`	`849`	`return super.clearGroupBy();`
`820`	`850`	`}`
`821`	`851`
	`852`	`+ /**`
	`853`	`+ * Sets the query's group by clause (clearing any previously specified GroupBy settings).`
	`854`	`+ */`
`822`	`855`	`@Override`
`823`	`856`	`public ProjectionEntityQueryBuilder groupBy(String property, String... others) {`
`824`	`857`	`return super.groupBy(property, others);`
`825`	`858`	`}`
`826`	`859`
	`860`	`+ /**`
	`861`	`+ * Adds one or more properties to the existing group by clause.`
	`862`	`+ */`
`827`	`863`	`@Override`
`828`	`864`	`public ProjectionEntityQueryBuilder addGroupBy(String property, String... others) {`
`829`	`865`	`return super.addGroupBy(property, others);`