From 2892ec850f2ba8bc4603e1691c3fefb1ab1c136f Mon Sep 17 00:00:00 2001
From: Arnout Engelen <arnouten@bzzt.net>
Date: Mon, 1 May 2017 17:38:50 +0200
Subject: [PATCH] Document which function types we prefer (#22819)

---
 akka-actor/src/main/java/akka/japi/pf/FI.java     | 15 ++++++++++++++-
 akka-actor/src/main/scala/akka/japi/JavaAPI.scala | 12 ++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/akka-actor/src/main/java/akka/japi/pf/FI.java b/akka-actor/src/main/java/akka/japi/pf/FI.java
index 842290d379..c3aa09e708 100644
--- a/akka-actor/src/main/java/akka/japi/pf/FI.java
+++ b/akka-actor/src/main/java/akka/japi/pf/FI.java
@@ -5,9 +5,10 @@
 package akka.japi.pf;
 
 /**
- * Class that encapsulates all the Functional Interfaces
+ * Class that encapsulates Functional Interfaces
  * used for creating partial functions.
  *
+ * These classes are kept for compatibility, but for future API's please prefer the ones in {@link akka.japi.function}.
  */
 public final class FI {
   private FI() {
@@ -16,6 +17,8 @@ public final class FI {
   /**
    * Functional interface for an application.
    *
+   * This class is kept for compatibility, but for future API's please prefer {@link akka.japi.function.Function}.
+   *
    * @param <I> the input type, that this Apply will be applied to
    * @param <R> the return type, that the results of the application will have
    */
@@ -32,6 +35,8 @@ public final class FI {
   /**
    * Functional interface for an application.
    *
+   * This class is kept for compatibility, but for future API's please prefer {@link akka.japi.function.Function2}.
+   *
    * @param <I1> the first input type, that this Apply will be applied to
    * @param <I2> the second input type, that this Apply will be applied to
    * @param <R> the return type, that the results of the application will have
@@ -50,6 +55,8 @@ public final class FI {
   /**
    * Functional interface for a predicate.
    *
+   * This class is kept for compatibility, but for future API's please prefer {@link akka.japi.function.Predicate}.
+   *
    * @param <T> the type that the predicate will operate on.
    */
   public static interface TypedPredicate<T> {
@@ -82,6 +89,8 @@ public final class FI {
   /**
    * Functional interface for an application.
    *
+   * This class is kept for compatibility, but for future API's please prefer {@link akka.japi.function.Procedure}.
+   *
    * @param <I> the input type, that this Apply will be applied to
    */
   public static interface UnitApply<I> {
@@ -149,6 +158,8 @@ public final class FI {
 
   /**
    * Functional interface for an application.
+   *
+   * This class is kept for compatibility, but for future API's please prefer {@link akka.japi.function.Effect}.
    */
   public static interface UnitApplyVoid {
     /**
@@ -159,6 +170,8 @@ public final class FI {
 
   /**
    * Package scoped functional interface for a predicate. Used internally to match against arbitrary types.
+   *
+   * This class is kept for compatibility, but for future API's please prefer {@link akka.japi.function.Predicate}.
    */
   static interface Predicate {
     /**
diff --git a/akka-actor/src/main/scala/akka/japi/JavaAPI.scala b/akka-actor/src/main/scala/akka/japi/JavaAPI.scala
index 6b050f8072..6d3a36fcac 100644
--- a/akka-actor/src/main/scala/akka/japi/JavaAPI.scala
+++ b/akka-actor/src/main/scala/akka/japi/JavaAPI.scala
@@ -16,6 +16,8 @@ import scala.util.control.NoStackTrace
 
 /**
  * A Function interface. Used to create first-class-functions is Java.
+ *
+ * This class is kept for compatibility, but for future API's please prefer [[akka.japi.function.Function]].
  */
 trait Function[T, R] {
   @throws(classOf[Exception])
@@ -24,6 +26,8 @@ trait Function[T, R] {
 
 /**
  * A Function interface. Used to create 2-arg first-class-functions is Java.
+ *
+ * This class is kept for compatibility, but for future API's please prefer [[akka.japi.function.Function2]].
  */
 trait Function2[T1, T2, R] {
   @throws(classOf[Exception])
@@ -32,6 +36,8 @@ trait Function2[T1, T2, R] {
 
 /**
  * A Procedure is like a Function, but it doesn't produce a return value.
+ *
+ * This class is kept for compatibility, but for future API's please prefer [[akka.japi.function.Procedure]].
  */
 trait Procedure[T] {
   @throws(classOf[Exception])
@@ -40,6 +46,8 @@ trait Procedure[T] {
 
 /**
  * An executable piece of code that takes no parameters and doesn't return any value.
+ *
+ * This class is kept for compatibility, but for future API's please prefer [[akka.japi.function.Effect]].
  */
 trait Effect {
   @throws(classOf[Exception])
@@ -48,6 +56,8 @@ trait Effect {
 
 /**
  * Java API: Defines a criteria and determines whether the parameter meets this criteria.
+ *
+ * This class is kept for compatibility, but for future API's please prefer [[akka.japi.function.Predicate]].
  */
 trait Predicate[T] {
   def test(param: T): Boolean
@@ -69,6 +79,8 @@ object Pair {
 
 /**
  * A constructor/factory, takes no parameters but creates a new value of type T every call.
+ *
+ * This class is kept for compatibility, but for future API's please prefer [[akka.japi.function.Creator]].
  */
 @SerialVersionUID(1L)
 trait Creator[T] extends Serializable {