See test with Java, we want preserve the invariant that if return type and
value parameter types are same in Kotlin, than we can use such return-value
as argument for that parameter
Before this change generic signature wasn't written because of wrong
assumption about it absence in all cases where we replace generic parameter
with Object
By default we would render 'MutableCollection<String>.addAll(Collection<String>)' as
'(LCollection<String>;)' (without wildcard) because String is final and
effectively it's the same as '(LCollection<? extends String>;)'.
But that's wrong signature in a sense that java.util.Collection has different
signature: '(LCollection<? extends E>)'.
Actually the problem is much wider than collections,
it concerns any Java code that uses Kotlin classes with covariant
parameters without '? extends E' wildcards.
Temporary solution is just to hardcode/enumerate builtin methods
with special signature.
Mostly this commit is about skipping wildcards that are redundant in some sense.
The motivation is that they looks `long` in Java code.
There are basically two important parts: return types and value parameters.
1. For return types default behaviour is skipping all declaration-site wildcards.
The intuition behind this rule is simple: return types are basically used in subtype position
(as an argument for another call), and here everything works well in case of 'out'-variance.
For example we have 'Out<Out<T>>>' as subtype both for 'Out<Out<T>>>' and 'Out<? extends Out<? extends T>>>',
so values of such type is more flexible in contrast to `Out<? extends Out<? extends T>>>` that could be used only
for the second case.
But we have choosen to treat `in`-variance in a different way: argument itself
should be rendered without wildcard while nested arguments are rendered by the rules
described further (see second part).
For example: 'In<Out<OpenClass>>' will have generic signature 'In<Out<? extends OpenClass>>'.
If we omit all wildcards here, then value of type 'In<Out<OpenClass>>'
will be impossible to use as argument for function expecting 'In<? super Out<? extends Derived>>'
where Derived <: OpenClass (you can check it manually :]).
And this exception should not be very inconvinient because in-variance is rather rare.
2. For value parameters we decided to skip wildcards if it doesn't make obtained signature weaker
in a sense of set of acceptable arguments.
More precisely:
a. We write wildcard for 'Out<T>' iff T ``can have subtypes ignoring nullability''
b. We write wildcard for 'In<T>' iff T is not equal to it's class upper bound (ignoring nullability again)
Definition of ``can have subtypes ignoring nullability'' is straightforward and you can see it in commit.
#KT-9801 Fixed
#KT-9890 Fixed
Michael Bogdanov