From ea0c9927e655168dd8636933bec7b5dd7720253f Mon Sep 17 00:00:00 2001
From: Julien Dramaix <dramaix@google.com>
Date: Tue, 30 Apr 2019 10:35:48 -0700
Subject: [PATCH] Add support for @this annotation in the JsInterop-generator
 and clean up elemental2 diff that were removing @this annotation.

We differentiate two cases:
- @this {THIS} @template THIS: this is used in closure type system to reflect the class used when a method is called. This pattern is used for allowing subclasses methods chaining.
When this pattern is used, we will just use the enclosing type of the
method as return type. This is the current behavior we have with the diff solution.
A better solution would be to override the method by specializing the return type on each known subclasses.

- Generic methods: Generic methods use @this for redefining the minimum contract that has to be satisfied by the instance the method is called on. For that purpose, they also redefine the template types at method level. For the java conversion purpose, we ignore the @this annotation and we don't redefine the template type (used in @this annotation) at the method level. I've also created https://github.com/google/elemental2/issues/107 that propose a possible improvement for generic methods

PiperOrigin-RevId: 245975596
---
 java/elemental2/core/BUILD                   | 15 +--
 java/elemental2/core/es3.js.diff             | 96 +-------------------
 java/elemental2/core/es6.js.diff             | 47 ----------
 java/elemental2/core/es6_collections.js.diff | 40 --------
 4 files changed, 2 insertions(+), 196 deletions(-)
 delete mode 100644 java/elemental2/core/es6_collections.js.diff

diff --git a/java/elemental2/core/BUILD b/java/elemental2/core/BUILD
index b7ea233..ea655a4 100644
--- a/java/elemental2/core/BUILD
+++ b/java/elemental2/core/BUILD
@@ -13,9 +13,6 @@ load(
 )
 load("@com_google_jsinterop_generator//:jsinterop_generator.bzl", "jsinterop_generator")
 
-# Removes @this annotations from some Arrays methods. This annotation confuses the generator
-# because it redefine the type parameter defined at type level.
-# TODO(b/36088887): Handle correctly @this annotation
 # Removes non-existing static methods defined in Array type.
 # TODO(b/36088884): clean-up the extern file directly
 # Make RegExp API stricter.
@@ -28,7 +25,6 @@ patch_extern_file(
 
 # Removes @this annotations from some Arrays methods. This annotation confuses the generator
 # because it redefine the type parameter defined at type level.
-# TODO(b/36088887): Handle correctly @this annotation
 # TODO(b/36252263): Extract Promise API in its own extern file instead
 patch_extern_file(
     name = "es6_patched",
@@ -36,15 +32,6 @@ patch_extern_file(
     patch_file = "es6.js.diff",
 )
 
-# Removes @this annotations from some Set, Map, WeakSet, WeakMap methods. This annotation
-# confuses the generator because it redefine the type parameter defined at type level.
-# TODO(b/36088887): Handle correctly @this annotation
-patch_extern_file(
-    name = "es6_collections_patched",
-    src = "//third_party:es6_collections.js",
-    patch_file = "es6_collections.js.diff",
-)
-
 filegroup(
     name = "externs",
     srcs = [
@@ -52,7 +39,7 @@ filegroup(
         ":es3_patched",
         "//third_party:es5.js",
         ":es6_patched",
-        ":es6_collections_patched",
+        "//third_party:es6_collections.js",
     ],
 )
 
diff --git a/java/elemental2/core/es3.js.diff b/java/elemental2/core/es3.js.diff
index 530ecf1..8bddd65 100644
--- a/java/elemental2/core/es3.js.diff
+++ b/java/elemental2/core/es3.js.diff
@@ -6,10 +6,9 @@
 < function Array(var_args) {}
 ---
 > function Array(items) {}
-567,569c557,558
+567,568c557,558
 <  * @param {...*} var_args
 <  * @return {!Array<?>}
-<  * @this {*}
 ---
 >  * @param {...T} items
 >  * @return {!Array<T>}
@@ -17,24 +16,6 @@
 < Array.prototype.concat = function(var_args) {};
 ---
 > Array.prototype.concat = function(items) {};
-592,594d580
-<  * @this {IArrayLike<T>}
-<  * @modifies {this}
-<  * @template T
-606,608d591
-<  * @this {IArrayLike<T>}
-<  * @template T
-<  * @modifies {this}
-617,620c600
-<  * @return {THIS} A reference to the original modified array.
-<  * @this {THIS}
-<  * @template THIS
-<  * @modifies {this}
----
->  * @return {Array<T>} A reference to the original modified array.
-629,630d608
-<  * @this {IArrayLike<T>}
-<  * @modifies {this}
 632d609
 <  * @template T
 640c617
@@ -45,13 +26,6 @@
 <  * @param {*=} opt_end Zero-based index at which to end extraction.  slice
 ---
 >  * @param {number=} opt_end Zero-based index at which to end extraction.  slice
-645,646d621
-<  * @this {IArrayLike<T>|string}
-<  * @template T
-657,659d631
-<  * @this {IArrayLike<T>}
-<  * @template T
-<  * @modifies {this}
 669c641
 <  * @param {*=} opt_index Index at which to start changing the array. If negative,
 ---
@@ -60,78 +34,10 @@
 <  * @param {*=} opt_howMany An integer indicating the number of old array elements
 ---
 >  * @param {number=} opt_howMany An integer indicating the number of old array elements
-676,678d647
-<  * @this {IArrayLike<T>}
-<  * @modifies {this}
-<  * @template T
 703c672
 <  * @param {...*} var_args
 ---
 >  * @param {...T} var_args
-718,719c687
-<  * @this {IArrayLike<T>|string}
-<  * @template T,R
----
->  * @template R
-731,732c699
-<  * @this {IArrayLike<T>|string}
-<  * @template T,R
----
->  * @template R
-739,740c706,707
-<  * @param {?function(this:S, T, number, !Array<T>): ?} callback
-<  * @param {S=} opt_thisobj
----
->  * @param {?function(T, number, !Array<T>): ?} callback
->  * @param {*=} opt_thisobj
-742,743d708
-<  * @this {IArrayLike<T>|string}
-<  * @template T,S
-750,751c715,716
-<  * @param {?function(this:S, T, number, !Array<T>): ?} callback
-<  * @param {S=} opt_thisobj
----
->  * @param {?function(T, number, !Array<T>): ?} callback
->  * @param {*=} opt_thisobj
-753,754d717
-<  * @this {IArrayLike<T>|string}
-<  * @template T,S
-761,764c724,725
-<  * @param {?function(this:S, T, number, !Array<T>): ?} callback
-<  * @param {S=} opt_thisobj
-<  * @this {IArrayLike<T>|string}
-<  * @template T,S
----
->  * @param {?function(T, number, !Array<T>): ?} callback
->  * @param {*=} opt_thisobj
-775d735
-<  * @this {IArrayLike<T>|string}
-777d736
-<  * @template T
-787d745
-<  * @this {IArrayLike<T>|string}
-789d746
-<  * @template T
-796,797c753,754
-<  * @param {?function(this:S, T, number, !Array<T>): R} callback
-<  * @param {S=} opt_thisobj
----
->  * @param {?function(T, number, !Array<T>): R} callback
->  * @param {*=} opt_thisobj
-799,800c756
-<  * @this {IArrayLike<T>|string}
-<  * @template T,S,R
----
->  * @template R
-807,808c763,764
-<  * @param {?function(this:S, T, number, !Array<T>): ?} callback
-<  * @param {S=} opt_thisobj
----
->  * @param {?function( T, number, !Array<T>): ?} callback
->  * @param {*=} opt_thisobj
-810,811d765
-<  * @this {IArrayLike<T>|string}
-<  * @template T,S
 835,903d788
 <  * @param {IArrayLike<T>} arr
 <  * @param {?function(this:S, T, number, ?) : ?} callback
diff --git a/java/elemental2/core/es6.js.diff b/java/elemental2/core/es6.js.diff
index 0a47c6e..bfea6b1 100644
--- a/java/elemental2/core/es6.js.diff
+++ b/java/elemental2/core/es6.js.diff
@@ -157,50 +157,3 @@
 < Promise.prototype.finally = function(callback) {};
 < 
 < 
-1297,1298c1139,1140
-<  * @param {function(this:S, (string|T), number): R=} opt_mapFn
-<  * @param {S=} opt_this
----
->  * @param {function((string|T), number): R=} opt_mapFn
->  * @param {*=} opt_this
-1300c1142
-<  * @template T,S,R
----
->  * @template T,R
-1324,1328c1166,1168
-<  * @param {function(this:S, T, number, !Array<T>): boolean} predicateFn
-<  * @param {S=} opt_this
-<  * @return {T|undefined}
-<  * @this {IArrayLike<T>|string}
-<  * @template T,S
----
->  * @param {function(T, number, !Array<T>): boolean} predicateFn
->  * @param {*=} opt_this
->  * @return {T}
-1335,1336c1175,1176
-<  * @param {function(this:S, T, number, !Array<T>): boolean} predicateFn
-<  * @param {S=} opt_this
----
->  * @param {function(T, number, !Array<T>): boolean} predicateFn
->  * @param {*=} opt_this
-1338,1339d1177
-<  * @this {IArrayLike<T>|string}
-<  * @template T,S
-1350,1351d1187
-<  * @this {!IArrayLike<T>|string}
-<  * @template T
-1363d1198
-<  * @template T
-1374,1375d1208
-<  * @this {!IArrayLike<T>|string}
-<  * @template T
-1550,1551c1383,1384
-<  * @param {function(this: THIS, ...?): RESULT} targetFn
-<  * @param {THIS} thisArg
----
->  * @param {function(...?): RESULT} targetFn
->  * @param {*} thisArg
-1554c1387
-<  * @template THIS, RESULT
----
->  * @template RESULT
diff --git a/java/elemental2/core/es6_collections.js.diff b/java/elemental2/core/es6_collections.js.diff
deleted file mode 100644
index 8dfcb96..0000000
--- a/java/elemental2/core/es6_collections.js.diff
+++ /dev/null
@@ -1,40 +0,0 @@
-51,54c51,52
-<  * @param {function(this:THIS, VALUE, KEY, MAP)} callback
-<  * @param {THIS=} opt_thisArg
-<  * @this {MAP}
-<  * @template MAP,THIS
----
->  * @param {function(VALUE, KEY, Map<KEY, VALUE>)} callback
->  * @param {*=} opt_thisArg
-81,83c79
-<  * @return {THIS}
-<  * @this {THIS}
-<  * @template THIS
----
->  * @return {Map<KEY,VALUE>}
-140,142c136
-<  * @return {THIS}
-<  * @this {THIS}
-<  * @template THIS
----
->  * @return {WeakMap<KEY,VALUE>}
-158,160c152
-<  * @return {THIS}
-<  * @this {THIS}
-<  * @template THIS
----
->  * @return {Set<VALUE>}
-183,186c175,176
-<  * @param {function(this: THIS, VALUE, VALUE, SET)} callback
-<  * @param {THIS=} opt_thisArg
-<  * @this {SET}
-<  * @template SET,THIS
----
->  * @param {function(VALUE, VALUE, Set<VALUE>)} callback
->  * @param {*=} opt_thisArg
-232,234c222
-<  * @return {THIS}
-<  * @this {THIS}
-<  * @template THIS
----
->  * @return {WeakSet<VALUE>}