From cb8414a355ff3989b36deffbd5aa92c4ed1cbb48 Mon Sep 17 00:00:00 2001
From: "Novotnik, Petr" <petr.novotnik@firma.seznam.cz>
Date: Tue, 25 Apr 2017 12:20:58 +0200
Subject: [PATCH] #21 [euphoria-core] Javadocs for Repartition

---
 .../core/client/operator/Repartition.java     | 73 ++++++++++++++++++-
 1 file changed, 69 insertions(+), 4 deletions(-)

diff --git a/sdks/java/extensions/euphoria/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/operator/Repartition.java b/sdks/java/extensions/euphoria/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/operator/Repartition.java
index 69dbb1bfb4b4..98189cead5f2 100644
--- a/sdks/java/extensions/euphoria/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/operator/Repartition.java
+++ b/sdks/java/extensions/euphoria/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/operator/Repartition.java
@@ -24,7 +24,33 @@
 import java.util.Objects;
 
 /**
- * Repartition input to some other number of partitions.
+ * Repartition the input dataset. Repartioning allows 1) to redistribute
+ * a dataset's elements across their partitions and/or 2) to define the
+ * number of partitions of a dataset.
+ *
+ * Example:
+ *
+ * <pre>{@code
+ *   Dataset<String> strings = ...;
+ *   strings = Repartition
+ *      .of(strings)
+ *      .setNumPartitions(10)
+ *      .setPartitioner(new HashPartitioner<>())
+ *      .output();
+ * }</pre>
+ *
+ * Here, the input dataset is repartitioned into 10 partitions, distributing
+ * the elements based on their hash code as computed by `String#hashCode`.<p>
+ *
+ * {@code #setNumPartitions} is optional and will default to the number of
+ * partitions of the input dataset. Effectively merely redistributing the
+ * dataset elements according to the specified partitioner.<p>
+ *
+ * Also {@code #setPartitioner} is optional, defaulting to
+ * {@link cz.seznam.euphoria.core.client.dataset.partitioning.HashPartitioner}.
+ *
+ * Note: as with all Euphoria operators, you must continue to use the
+ * repartition operator's output dataset to make the operation effective.
  */
 @Basic(
     state = StateComplexity.ZERO,
@@ -42,6 +68,15 @@ public static class OfBuilder {
       this.name = name;
     }
 
+    /**
+     * Specifies the input dataset to be repartitioned.
+     *
+     * @param <IN> the type of elements in the input dataset
+     *
+     * @param input the input dataset to process
+     *
+     * @return the next builder to complete the setup of the repartition operator
+     */
     public <IN> OutputBuilder<IN> of(Dataset<IN> input) {
       return new OutputBuilder<>(name, input);
     }
@@ -61,6 +96,12 @@ public static class OutputBuilder<IN>
       this.input = Objects.requireNonNull(input);
     }
 
+    /**
+     * Finalizes the setup of the {@link Repartition} operator and retrieves
+     * the dataset representing the repartitioned input dataset.
+     *
+     * @return the dataset represeting the repartitioned input
+     */
     @Override
     public Dataset<IN> output() {
       Flow flow = input.getFlow();
@@ -71,10 +112,30 @@ public Dataset<IN> output() {
     }
   }
 
+  /**
+   * Starts building a nameless {@link Repartition} operator over the given
+   * input dataset.
+   *
+   * @param <IN> the type of elements in the input dataset
+   *
+   * @param input the input dataset to process
+   *
+   * @return a builder to complete the setup of the {@link Repartition} operator
+   *
+   * @see #named(String)
+   * @see OfBuilder#of(Dataset)
+   */
   public static <IN> OutputBuilder<IN> of(Dataset<IN> input) {
     return new OutputBuilder<>("Repartition", input);
   }
 
+  /**
+   * Starts building a named {@link Repartition} operator.
+   *
+   * @param name a user provided name of the new operator to build
+   *
+   * @return a builder to complete the setup of the new {@link Repartition} operator
+   */
   public static OfBuilder named(String name) {
     return new OfBuilder(name);
   }
@@ -87,10 +148,14 @@ public static OfBuilder named(String name) {
     this.partitioning = partitioning;
   }
 
+  /**
+   * Retrieves the partitioning information according which this operators
+   * input dataset is to be redistributed.
+   *
+   * @return the partitioning schema of this {@link Repartition} operator
+   */
   @Override
   public Partitioning<IN> getPartitioning() {
     return partitioning;
   }
-
-
-}
+}
\ No newline at end of file