DATAMONGO-1552 - Polishing.

Updated doc, removed whitespaces, minor method wording changes.

Original Pull Request: #426

Author: christophstrobl

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/Aggregation.java

@@ -424,6 +424,7 @@ public static OutOperation out(String outCollectionName) {
 	 *
 	 * @param groupByField must not be {@literal null} or empty.
 	 * @return
+	 * @since 1.10
 	 */
 	public static BucketOperation bucket(String groupByField) {
 		return new BucketOperation(field(groupByField));
@@ -434,6 +435,7 @@ public static BucketOperation bucket(String groupByField) {
 	 *
 	 * @param groupByExpression must not be {@literal null}.
 	 * @return
+	 * @since 1.10
 	 */
 	public static BucketOperation bucket(AggregationExpression groupByExpression) {
 		return new BucketOperation(groupByExpression);
@@ -445,6 +447,7 @@ public static BucketOperation bucket(AggregationExpression groupByExpression) {
 	 * @param groupByField must not be {@literal null} or empty.
 	 * @param buckets number of buckets, must be a positive integer.
 	 * @return
+	 * @since 1.10
 	 */
 	public static BucketAutoOperation bucketAuto(String groupByField, int buckets) {
 		return new BucketAutoOperation(field(groupByField), buckets);
@@ -456,6 +459,7 @@ public static BucketAutoOperation bucketAuto(String groupByField, int buckets) {
 	 * @param groupByExpression must not be {@literal null}.
 	 * @param buckets number of buckets, must be a positive integer.
 	 * @return
+	 * @since 1.10
 	 */
 	public static BucketAutoOperation bucketAuto(AggregationExpression groupByExpression, int buckets) {
 		return new BucketAutoOperation(groupByExpression, buckets);
@@ -465,6 +469,7 @@ public static BucketAutoOperation bucketAuto(AggregationExpression groupByExpres
 	 * Creates a new {@link FacetOperation}.
 	 *
 	 * @return
+	 * @since 1.10
 	 */
 	public static FacetOperation facet() {
 		return FacetOperation.EMPTY;
@@ -475,6 +480,7 @@ public static FacetOperation facet() {
 	 *
 	 * @param aggregationOperations the sub-pipeline, must not be {@literal null}.
 	 * @return
+	 * @since 1.10
 	 */
 	public static FacetOperationBuilder facet(AggregationOperation... aggregationOperations) {
 		return facet().and(aggregationOperations);

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/AggregationOperationRenderer.java

@@ -28,7 +28,7 @@
 
 /**
  * Rendering support for {@link AggregationOperation} into a {@link List} of {@link com.mongodb.DBObject}.
- * 
+ *
  * @author Mark Paluch
  * @author Christoph Strobl
  * @since 1.10
@@ -40,7 +40,7 @@ class AggregationOperationRenderer {
 	/**
 	 * Render a {@link List} of {@link AggregationOperation} given {@link AggregationOperationContext} into their
 	 * {@link DBObject} representation.
-	 * 
+	 *
 	 * @param operations must not be {@literal null}.
 	 * @param context must not be {@literal null}.
 	 * @return the {@link List} of {@link DBObject}.

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/BucketAutoOperation.java

@@ -23,18 +23,18 @@
 import com.mongodb.DBObject;
 
 /**
- * Encapsulates the aggregation framework {@code $bucketAuto}-operation.
- * <p>
+ * Encapsulates the aggregation framework {@code $bucketAuto}-operation. <br />
  * Bucket stage is typically used with {@link Aggregation} and {@code $facet}. Categorizes incoming documents into a
  * specific number of groups, called buckets, based on a specified expression. Bucket boundaries are automatically
- * determined in an attempt to evenly distribute the documents into the specified number of buckets.
- * <p>
- * We recommend to use the static factory method {@link Aggregation#bucketAuto(String, int)} instead of creating instances of
- * this class directly.
+ * determined in an attempt to evenly distribute the documents into the specified number of buckets. <br />
+ * We recommend to use the static factory method {@link Aggregation#bucketAuto(String, int)} instead of creating
+ * instances of this class directly.
  *
- * @see http://docs.mongodb.org/manual/reference/aggregation/bucketAuto/
+ * @see <a href=
+ *      "http://docs.mongodb.org/manual/reference/aggregation/bucketAuto/">http://docs.mongodb.org/manual/reference/aggregation/bucketAuto/</a>
  * @see BucketOperationSupport
  * @author Mark Paluch
+ * @author Christoph Strobl
  * @since 1.10
  */
 public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperation, BucketAutoOperationOutputBuilder>
@@ -100,13 +100,12 @@ public DBObject toDBObject(AggregationOperationContext context) {
 		DBObject options = new BasicDBObject();
 
 		options.put("buckets", buckets);
+		options.putAll(super.toDBObject(context));
 
 		if (granularity != null) {
 			options.put("granularity", granularity);
 		}
 
-		options.putAll(super.toDBObject(context));
-
 		return new BasicDBObject("$bucketAuto", options);
 	}
 
@@ -123,8 +122,10 @@ public BucketAutoOperation withBuckets(int buckets) {
 	}
 
 	/**
-	 * Configures {@literal granularity} that specifies the preferred number series to use to ensure that the calculated
-	 * boundary edges end on preferred round numbers or their powers of 10 and return a new {@link BucketAutoOperation}.
+	 * Configures {@link Granularity granularity} that specifies the preferred number series to use to ensure that the
+	 * calculated boundary edges end on preferred round numbers or their powers of 10 and return a new
+	 * {@link BucketAutoOperation}. <br />
+	 * Use either predefined {@link Granularities} or provide a own one.
 	 *
 	 * @param granularity must not be {@literal null}.
 	 * @return
@@ -133,7 +134,7 @@ public BucketAutoOperation withGranularity(Granularity granularity) {
 
 		Assert.notNull(granularity, "Granularity must not be null!");
 
-		return new BucketAutoOperation(this, buckets, granularity.toMongoGranularity());
+		return new BucketAutoOperation(this, buckets, granularity.getMongoRepresentation());
 	}
 
 	/* (non-Javadoc)
@@ -196,7 +197,7 @@ protected BucketAutoOperationOutputBuilder apply(OperationOutput operationOutput
 	/**
 	 * {@link ExpressionBucketOperationBuilderSupport} implementation for {@link BucketAutoOperation} using SpEL
 	 * expression based {@link Output}.
-	 * 
+	 *
 	 * @author Mark Paluch
 	 */
 	public static class ExpressionBucketAutoOperationBuilder
@@ -227,19 +228,20 @@ protected BucketAutoOperationOutputBuilder apply(OperationOutput operationOutput
 	/**
 	 * @author Mark Paluch
 	 */
-	public static interface Granularity {
+	public interface Granularity {
 
 		/**
-		 * @return a String that represents a MongoDB granularity to be used with {@link BucketAutoOperation}.
+		 * @return a String that represents a MongoDB granularity to be used with {@link BucketAutoOperation}. Never
+		 *         {@literal null}.
 		 */
-		String toMongoGranularity();
+		String getMongoRepresentation();
 	}
 
 	/**
 	 * Supported MongoDB granularities.
 	 *
-	 * @see https://en.wikipedia.org/wiki/Preferred_number
-	 * @see https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/#granularity
+	 * @see <a
+	 *      href="https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/#granularity>https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/#granularity</a>
 	 * @author Mark Paluch
 	 */
 	public enum Granularities implements Granularity {
@@ -252,7 +254,7 @@ public enum Granularities implements Granularity {
 
 		POWERSOF2;
 
-		final String granularity;
+		private final String granularity;
 
 		Granularities() {
 			this.granularity = name();
@@ -266,7 +268,7 @@ public enum Granularities implements Granularity {
 		 * @see org.springframework.data.mongodb.core.aggregation.GranularitytoMongoGranularity()
 		 */
 		@Override
-		public String toMongoGranularity() {
+		public String getMongoRepresentation() {
 			return granularity;
 		}
 	}

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/BucketOperation.java

@@ -27,15 +27,15 @@
 import com.mongodb.DBObject;
 
 /**
- * Encapsulates the aggregation framework {@code $bucket}-operation.
- * <p>
+ * Encapsulates the aggregation framework {@code $bucket}-operation. <br />
+ *
  * Bucket stage is typically used with {@link Aggregation} and {@code $facet}. Categorizes incoming documents into
- * groups, called buckets, based on a specified expression and bucket boundaries.
- * <p>
+ * groups, called buckets, based on a specified expression and bucket boundaries. <br />
+ *
  * We recommend to use the static factory method {@link Aggregation#bucket(String)} instead of creating instances of
  * this class directly.
  *
- * @see http://docs.mongodb.org/manual/reference/aggregation/bucket/
+ * @see <a href="http://docs.mongodb.org/manual/reference/aggregation/bucket/">http://docs.mongodb.org/manual/reference/aggregation/bucket/</a>
  * @see BucketOperationSupport
  * @author Mark Paluch
  * @since 1.10
@@ -109,7 +109,7 @@ public DBObject toDBObject(AggregationOperationContext context) {
 
 	/**
 	 * Configures a default bucket {@literal literal} and return a new {@link BucketOperation}.
-	 * 
+	 *
 	 * @param literal must not be {@literal null}.
 	 * @return
 	 */
@@ -122,13 +122,14 @@ public BucketOperation withDefaultBucket(Object literal) {
 	/**
 	 * Configures {@literal boundaries} and return a new {@link BucketOperation}. Existing {@literal boundaries} are
 	 * preserved and the new {@literal boundaries} are appended.
-	 * 
+	 *
 	 * @param boundaries must not be {@literal null}.
 	 * @return
 	 */
 	public BucketOperation withBoundaries(Object... boundaries) {
 
 		Assert.notNull(boundaries, "Boundaries must not be null!");
+		Assert.noNullElements(boundaries, "Boundaries must not contain null values!");
 
 		List<Object> newBoundaries = new ArrayList<Object>(this.boundaries.size() + boundaries.length);
 		newBoundaries.addAll(this.boundaries);
@@ -197,7 +198,7 @@ protected BucketOperationOutputBuilder apply(OperationOutput operationOutput) {
 	/**
 	 * {@link ExpressionBucketOperationBuilderSupport} implementation for {@link BucketOperation} using SpEL expression
 	 * based {@link Output}.
-	 * 
+	 *
 	 * @author Mark Paluch
 	 */
 	public static class ExpressionBucketOperationBuilder