From e8b127deef8f4de51052f864f5490f839e8c9af5 Mon Sep 17 00:00:00 2001
From: Renaud Pawlak <renaud.pawlak@gmail.com>
Date: Mon, 10 Jul 2017 16:11:42 +0200
Subject: [PATCH] API + javadoc

---
 .../es5/src/main/java/def/js/Function.java    |  5 ++++-
 .../main/java/def/js/FunctionalObject.java    | 19 +++++++++++++++++++
 .../es5/src/main/java/jsweet/lang/Erased.java |  5 -----
 .../src/main/java/jsweet/lang/Replace.java    |  3 +--
 .../es6/src/main/java/def/js/Function.java    |  5 ++++-
 .../main/java/def/js/FunctionalObject.java    | 19 +++++++++++++++++++
 .../es6/src/main/java/jsweet/lang/Erased.java |  5 -----
 .../src/main/java/jsweet/lang/Replace.java    |  3 +--
 8 files changed, 48 insertions(+), 16 deletions(-)
 create mode 100644 core-lib/es5/src/main/java/def/js/FunctionalObject.java
 create mode 100644 core-lib/es6/src/main/java/def/js/FunctionalObject.java

diff --git a/core-lib/es5/src/main/java/def/js/Function.java b/core-lib/es5/src/main/java/def/js/Function.java
index b7d776d7..44225629 100644
--- a/core-lib/es5/src/main/java/def/js/Function.java
+++ b/core-lib/es5/src/main/java/def/js/Function.java
@@ -2,7 +2,7 @@ package def.js;
 /**
   * Creates a new function.
   */
-public class Function extends def.js.Object {
+public class Function extends def.js.Object implements FunctionalObject {
     /**
       * Calls the function, substituting the specified object for the this value of the function, and the specified array for the arguments of the function.
       * @param thisArg The object to be used as the this object.
@@ -40,5 +40,8 @@ public class Function extends def.js.Object {
     native public java.lang.Object apply(java.lang.Object thisArg);
     native public java.lang.Object caller(java.lang.Object... args);
     protected Function(){}
+    
+    @Override
+    native public <R> R $apply(Object... arguments);
 }
 
diff --git a/core-lib/es5/src/main/java/def/js/FunctionalObject.java b/core-lib/es5/src/main/java/def/js/FunctionalObject.java
new file mode 100644
index 00000000..ad5b4f58
--- /dev/null
+++ b/core-lib/es5/src/main/java/def/js/FunctionalObject.java
@@ -0,0 +1,19 @@
+package def.js;
+
+/**
+ * This interface defines the <code>$apply</code> signature that allows invoking
+ * an object.
+ * 
+ * <p>
+ * The code <code>o.$apply(args)</code> is transpiled to <code>o(args)</code>.
+ * Implementing this interface is not mandatory to create a functional object.
+ * Just defining the <code>$apply</code> function is enough. It is however
+ * recommended to implement this interface for readbility sake.
+ * 
+ * @author Renaud Pawlak
+ */
+public interface FunctionalObject {
+
+    <R> R $apply(Object... arguments);
+
+}
diff --git a/core-lib/es5/src/main/java/jsweet/lang/Erased.java b/core-lib/es5/src/main/java/jsweet/lang/Erased.java
index b25f632f..38c5e922 100644
--- a/core-lib/es5/src/main/java/jsweet/lang/Erased.java
+++ b/core-lib/es5/src/main/java/jsweet/lang/Erased.java
@@ -26,11 +26,6 @@ import java.lang.annotation.Target;
  * This annotation type is used on elements that should be erased at generation
  * time (casts and constructor invocations are removed).
  * 
- * <p>
- * This is mainly used for Java type disambiguation when the API defines two
- * methods that have the same erasure. Most programmers will not have to use it
- * directly.
- * 
  * @author Renaud Pawlak
  */
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/core-lib/es5/src/main/java/jsweet/lang/Replace.java b/core-lib/es5/src/main/java/jsweet/lang/Replace.java
index 194b7746..cd4e4a96 100644
--- a/core-lib/es5/src/main/java/jsweet/lang/Replace.java
+++ b/core-lib/es5/src/main/java/jsweet/lang/Replace.java
@@ -32,8 +32,7 @@ import java.lang.annotation.Target;
  * 
  * <p>
  * The replacing code can contain variables substituted using a mustache-like
- * convention ({{variableName}}). Note that no space is allowed between the
- * variable name and the mustaches. Here is the list of supported variables:
+ * convention ({{variableName}}). Here is the list of supported variables:
  * 
  * <ul>
  * <li>{{className}}: the current class.</li>
diff --git a/core-lib/es6/src/main/java/def/js/Function.java b/core-lib/es6/src/main/java/def/js/Function.java
index 627d6f12..daa12c0f 100644
--- a/core-lib/es6/src/main/java/def/js/Function.java
+++ b/core-lib/es6/src/main/java/def/js/Function.java
@@ -2,7 +2,7 @@ package def.js;
 /**
   * Creates a new function.
   */
-public class Function extends def.js.Object {
+public class Function extends def.js.Object implements FunctionalObject {
     /**
       * Calls the function, substituting the specified object for the this value of the function, and the specified array for the arguments of the function.
       * @param thisArg The object to be used as the this object.
@@ -49,5 +49,8 @@ public class Function extends def.js.Object {
     native public java.lang.Object apply(java.lang.Object thisArg);
     native public java.lang.Object caller(java.lang.Object... args);
     protected Function(){}
+    
+    @Override
+    native public <R> R $apply(Object... arguments);
 }
 
diff --git a/core-lib/es6/src/main/java/def/js/FunctionalObject.java b/core-lib/es6/src/main/java/def/js/FunctionalObject.java
new file mode 100644
index 00000000..ad5b4f58
--- /dev/null
+++ b/core-lib/es6/src/main/java/def/js/FunctionalObject.java
@@ -0,0 +1,19 @@
+package def.js;
+
+/**
+ * This interface defines the <code>$apply</code> signature that allows invoking
+ * an object.
+ * 
+ * <p>
+ * The code <code>o.$apply(args)</code> is transpiled to <code>o(args)</code>.
+ * Implementing this interface is not mandatory to create a functional object.
+ * Just defining the <code>$apply</code> function is enough. It is however
+ * recommended to implement this interface for readbility sake.
+ * 
+ * @author Renaud Pawlak
+ */
+public interface FunctionalObject {
+
+    <R> R $apply(Object... arguments);
+
+}
diff --git a/core-lib/es6/src/main/java/jsweet/lang/Erased.java b/core-lib/es6/src/main/java/jsweet/lang/Erased.java
index de2bc888..b78f9cd7 100644
--- a/core-lib/es6/src/main/java/jsweet/lang/Erased.java
+++ b/core-lib/es6/src/main/java/jsweet/lang/Erased.java
@@ -26,11 +26,6 @@ import java.lang.annotation.Target;
  * This annotation type is used on elements that should be erased at generation
  * time (casts and constructor invocations are removed).
  * 
- * <p>
- * This is mainly used for Java type disambiguation when the API defines two
- * methods that have the same erasure. Most programmers will not have to use it
- * directly.
- * 
  * @author Renaud Pawlak
  */
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/core-lib/es6/src/main/java/jsweet/lang/Replace.java b/core-lib/es6/src/main/java/jsweet/lang/Replace.java
index 655614b3..abc8db14 100644
--- a/core-lib/es6/src/main/java/jsweet/lang/Replace.java
+++ b/core-lib/es6/src/main/java/jsweet/lang/Replace.java
@@ -32,8 +32,7 @@ import java.lang.annotation.Target;
  * 
  * <p>
  * The replacing code can contain variables substituted using a mustache-like
- * convention ({{variableName}}). Note that no space is allowed between the
- * variable name and the mustaches. Here is the list of supported variables:
+ * convention ({{variableName}}). Here is the list of supported variables:
  * 
  * <ul>
  * <li>{{className}}: the current class.</li>