Version overloading

[faizilham]

This is an issue for discussion of version overloading proposal. The full text of the proposal is here.

Please use this issue for the discussion on the substance of the proposal. For minor corrections to the text, please open comment directly in the PR #423.

[udalov]

functions with @JvmOverloads annotation may not have version annotated parameter.

Why? It seems beneficial to have deprecated-hidden $default methods generated for those too.

[faizilham]

Why? It seems beneficial to have deprecated-hidden $default methods generated for those too.

Mainly because of the implementation clashes due to the different use cases.

The current implementation of @JvmOverloads does not copy the default values of the optional parameters to the generated overloads, while the version overloading does. As far as I know, this is done in JvmOverloads lowering to prevent problems with optional parameters that depend on other parameters:

@JvmOverloads
fun xyz(a: Int = b, b: Int = 1) { ... }

The generated overload is fun xyz(a: Int), without the default value of a. This is not a problem for JvmOverloads since the main use case is Java interoperability.

For version overloading though we need to copy the default values since the use case is compatibility with older (mostly Kotlin) binaries. In this case, the compiler can copy the default value as long as b has older or the same version annotation as a, otherwise it reports an error.

fun xyz(@IntroducedAt("2") a: Int = b, b: Int = 1) { ... } // deprecated overload: fun xyz(b: B = 1)

fun xyz(a: Int = b, @IntroducedAt("2") b: Int = 1) { ... } // error! 'a' depends on a "future" parameter 'b'

There are also problems with the overload deprecation. JvmOverloads does not deprecate-hide the generated overloads to allow discoverability from Java source code, while version overloading deprecates to prevent users from using older signatures.

The implementations will also have to be tightly coupled in order to prevent overload signatures clash, but this might be a lesser concern.

[udalov]

So, @JvmOverloads and @IntroducedAt solve different use cases. I agree with that, and that's why I think they should be orthogonal features, so you can use either or both of them on the same declaration. Otherwise, as a library author, I can't use this feature for an already existing @JvmOverloads-annotated declaration.

There are also problems with the overload deprecation. JvmOverloads does not deprecate-hide the generated overloads to allow discoverability from Java source code, while version overloading deprecates to prevent users from using older signatures.

Maybe I'm not seeing something, but this should be solved by lowering @IntroducedAt before @JvmOverloads, and tweaking the @JvmOverloads lowering to avoid generating declarations with an already existing signature.

[faizilham]

I just realized the example fun xyz(a: Int = b, b: Int = 1) already won't compile because b is seen as uninitialized. The signature clash problem is still not yet solved though.

[...] this should be solved by lowering @IntroducedAt before @JvmOverloads, and tweaking the @JvmOverloads lowering to avoid generating declarations with an already existing signature.

This could work, although I'm not sure how we should handle cases like this:

@JvmOverloads
fun xyz(
    a: Int = 1,
    @IntroducedAt("3") a1: Int = 2,
    @IntroducedAt("2") b : Int = 3,
) { }

/* Which ones to choose?
IntroducedAt overloads:
  1. @Deprecated fun xyz(a: Int = 1)
  2. @Deprecated fun xyz(a: Int = 1, b: Int = 3)

JvmOverloads overloads: 
  3. fun xyz()
  4. fun xyz(a: Int)             // clash with 1
  5. fun xyz(a: Int, a1: Int)    // clash with 2
*/

If we choose the overloads 1, 2, and 3, it preserves binary compatibility but breaks the expected behavior of JvmOverloads.

Let's say we call xyz(1, 2) from Java. This won't work directly because it is deprecated-hidden, but even if it is not hidden, it would actually call xyz(a=1, b=2) instead of the expected xyz(a=1, a1=2).

This is very similar with the source compatibility problem mentioned in the text which can be solved by providing arguments by name, but we can't do that in Java.

This might still be a reasonable trade-off, but I don't know how acceptable it is to most users. What do you think?