#21 [euphoria-core] Javadocs for FlatMap

sdks/java/extensions/euphoria/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/operator/FlatMap.java

@@ -24,7 +24,37 @@
 import java.util.Objects;
 
 /**
- * Flat map operator on dataset.
+ * A transformation of a dataset from one type into another allowing user code
+ * to generate zero, one, or many output elements for a given input element.<p>
+ *
+ * The user supplied map function is supposed to be stateless. It is fed items
+ * from the input in no specified order and the results of the map function are
+ * "flattened" to the output (equally in no specified order.)<p>
+ *
+ * Example:
+ *
+ * <pre>{@code
+ *  Dataset<String> strings = ...;
+ *  Dataset<Integer> ints =
+ *         FlatMap.named("TO-INT")
+ *            .of(strings)
+ *            .using((String s, Context<String> c) -> {
+ *              try {
+ *                int i = Integer.parseInt(s);
+ *                c.collect(i);
+ *              } catch (NumberFormatException e) {
+ *                // ~ ignore the input if we failed to parse it
+ *              }
+ *            })
+ *            .output();
+ * }</pre>
+ *
+ * The above example tries to parse incoming strings as integers, silently
+ * skipping those which cannot be successfully converted. While
+ * {@link cz.seznam.euphoria.core.client.io.Context#collect(Object)} has
+ * been used only once here, a {@link FlatMap} operator is free
+ * to invoke it multiple times or not at all to generate that many elements
+ * to the output dataset.
  */
 @Basic(
     state = StateComplexity.ZERO,
@@ -39,6 +69,16 @@ public static class OfBuilder {
       this.name = name;
     }
 
+    /**
+     * Specifies the input dataset to be transformed.
+     *
+     * @param <IN> the type of elements of the input dataset
+     *
+     * @param input the input dataset
+     *
+     * @return the next builder to complete the setup
+     *          of the {@link FlatMap} operator
+     */
     public <IN> UsingBuilder<IN> of(Dataset<IN> input) {
       return new UsingBuilder<>(name, input);
     }
@@ -53,6 +93,18 @@ public static class UsingBuilder<IN> {
       this.input = Objects.requireNonNull(input);
     }
 
+    /**
+     * Specifies the user defined map function by which to transform
+     * the final operator's input dataset.
+     *
+     * @param <OUT> the type of elements the user defined map function
+     *            will produce to the output dataset
+     *
+     * @param functor the user defined map function
+     *
+     * @return the next builder to complete the setup
+     *          of the {@link FlatMap} operator
+     */
     public <OUT> OutputBuilder<IN, OUT> using(UnaryFunctor<IN, OUT> functor) {
       return new OutputBuilder<>(name, input, functor);
     }
@@ -71,20 +123,45 @@ public static class OutputBuilder<IN, OUT>
       this.functor = functor;
     }
 
+    /**
+     * Finalizes the setup of the {@link FlatMap} operator and retrieves the
+     * transformed dataset.
+     *
+     * @return the dataset representing the operator's transformed input
+     */
     @Override
     public Dataset<OUT> output() {
       Flow flow = input.getFlow();
       FlatMap<IN, OUT> map = new FlatMap<>(name, flow, input, functor);
       flow.add(map);
-
       return map.output();
     }
   }
 
+  /**
+   * Starts building a nameless {@link FlatMap} operator to transform the given
+   * input dataset.
+   *
+   * @param <IN> the type of elements of the input dataset
+   *
+   * @param input the input data set to be transformed
+   *
+   * @return a builder to complete the setup of the new {@link FlatMap} operator
+   *
+   * @see #named(String)
+   * @see OfBuilder#of(Dataset)
+   */
   public static <IN> UsingBuilder<IN> of(Dataset<IN> input) {
     return new UsingBuilder<>("FlatMap", input);
   }
 
+  /**
+   * Starts building a named {@link FlatMap} operator.
+   *
+   * @param name a user provided name of the new operator to build
+   *
+   * @return a builder to complete the setup of the new {@link FlatMap} operator
+   */
   public static OfBuilder named(String name) {
     return new OfBuilder(name);
   }
@@ -96,9 +173,13 @@ public static OfBuilder named(String name) {
     this.functor = functor;
   }
 
+  /**
+   * Retrieves the user defined map function to be applied to this operator's
+   * input elements.
+   *
+   * @return the user defined map function; never {@code null}
+   */
   public UnaryFunctor<IN, OUT> getFunctor() {
     return functor;
   }
-
-
-}
+}