add javadocs for set vs add in structured query builder

Ajay Kannan · Ajay Kannan · commit 5f01eb90a4ea · 2015-10-20T15:08:27.000-07:00
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();
     }
 
+    /*
+     * Clears all previously-specified OrderBy objects and orders by the given input instead.
+     */
     public B orderBy(OrderBy orderBy, OrderBy... others) {
       clearOrderBy();
       addOrderBy(orderBy, others);
       return self();
     }
 
+    /*
+     * Adds one or more OrderBy objects to the existing list of OrderBy objects.
+     */
     public B addOrderBy(OrderBy orderBy, OrderBy... others) {
       this.orderBy.add(orderBy);
       Collections.addAll(this.orderBy, others);
@@ -682,12 +697,19 @@ B clearProjection() {
       return self();
     }
 
+    /*
+     * Clears all previously-specified Projections and sets the list of Projections to the given
+     * input instead.
+     */
     B projection(Projection projection, Projection... others) {
       clearProjection();
       addProjection(projection, others);
       return self();
     }
 
+    /*
+     * Adds one or more Projections to the existing list of Projections.
+     */
     B addProjection(Projection projection, Projection... others) {
       this.projection.add(projection);
       Collections.addAll(this.projection, others);
@@ -699,12 +721,19 @@ B clearGroupBy() {
       return self();
     }
 
+    /*
+     * Clears all existing properties to group by and instead groups by the given the list of
+     * properties.
+     */
     B groupBy(String property, String... others) {
       clearGroupBy();
       addGroupBy(property, others);
       return self();
     }
 
+    /*
+     * Adds one or more properties to the existing list of "group by" properties.
+     */
     B addGroupBy(String property, String... others) {
       this.groupBy.add(property);
       Collections.addAll(this.groupBy, others);
@@ -754,6 +783,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 +798,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 +822,9 @@ public StructuredQuery<Key> build() {
     }
   }
 
+  /*
+   * A StructuredQuery builder for projection queries.
+   */
   public static final class ProjectionEntityQueryBuilder
       extends BaseBuilder<ProjectionEntity, ProjectionEntityQueryBuilder> {
 

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`	`+ * Clears all previously-specified OrderBy objects and orders by the given input instead.`
	`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 one or more OrderBy objects to the existing list of OrderBy objects.`
	`688`	`+ */`
`674`	`689`	`public B addOrderBy(OrderBy orderBy, OrderBy... others) {`
`675`	`690`	`this.orderBy.add(orderBy);`
`676`	`691`	`Collections.addAll(this.orderBy, others);`
`@@ -682,12 +697,19 @@ B clearProjection() {`
`682`	`697`	`return self();`
`683`	`698`	`}`
`684`	`699`
	`700`	`+ /*`
	`701`	`+ * Clears all previously-specified Projections and sets the list of Projections to the given`
	`702`	`+ * input instead.`
	`703`	`+ */`
`685`	`704`	`B projection(Projection projection, Projection... others) {`
`686`	`705`	`clearProjection();`
`687`	`706`	`addProjection(projection, others);`
`688`	`707`	`return self();`
`689`	`708`	`}`
`690`	`709`
	`710`	`+ /*`
	`711`	`+ * Adds one or more Projections to the existing list of Projections.`
	`712`	`+ */`
`691`	`713`	`B addProjection(Projection projection, Projection... others) {`
`692`	`714`	`this.projection.add(projection);`
`693`	`715`	`Collections.addAll(this.projection, others);`
`@@ -699,12 +721,19 @@ B clearGroupBy() {`
`699`	`721`	`return self();`
`700`	`722`	`}`
`701`	`723`
	`724`	`+ /*`
	`725`	`+ * Clears all existing properties to group by and instead groups by the given the list of`
	`726`	`+ * properties.`
	`727`	`+ */`
`702`	`728`	`B groupBy(String property, String... others) {`
`703`	`729`	`clearGroupBy();`
`704`	`730`	`addGroupBy(property, others);`
`705`	`731`	`return self();`
`706`	`732`	`}`
`707`	`733`
	`734`	`+ /*`
	`735`	`+ * Adds one or more properties to the existing list of "group by" properties.`
	`736`	`+ */`
`708`	`737`	`B addGroupBy(String property, String... others) {`
`709`	`738`	`this.groupBy.add(property);`
`710`	`739`	`Collections.addAll(this.groupBy, others);`
`@@ -754,6 +783,9 @@ static final class Builder<V> extends BaseBuilder<V, Builder<V>> {`
`754`	`783`	`}`
`755`	`784`	`}`
`756`	`785`
	`786`	`+ /*`
	`787`	`+ * A StructuredQuery builder for queries that return Entity results.`
	`788`	`+ */`
`757`	`789`	`public static final class EntityQueryBuilder extends BaseBuilder<Entity, EntityQueryBuilder> {`
`758`	`790`
`759`	`791`	`EntityQueryBuilder() {`
`@@ -766,6 +798,9 @@ public StructuredQuery<Entity> build() {`
`766`	`798`	`}`
`767`	`799`	`}`
`768`	`800`
	`801`	`+ /*`
	`802`	`+ * A StructuredQuery builder for queries that return Key results.`
	`803`	`+ */`
`769`	`804`	`public static final class KeyQueryBuilder extends BaseBuilder<Key, KeyQueryBuilder> {`
`770`	`805`
`771`	`806`	`KeyQueryBuilder() {`
`@@ -787,6 +822,9 @@ public StructuredQuery<Key> build() {`
`787`	`822`	`}`
`788`	`823`	`}`
`789`	`824`
	`825`	`+ /*`
	`826`	`+ * A StructuredQuery builder for projection queries.`
	`827`	`+ */`
`790`	`828`	`public static final class ProjectionEntityQueryBuilder`
`791`	`829`	`extends BaseBuilder<ProjectionEntity, ProjectionEntityQueryBuilder> {`
`792`	`830`