Return the generated path from FileSpec.writeTo().

[fejesjoco]

Hi,

I have a use case where it would be nice to know the path that is generated in the writeTo method.

This is similar to how JavaPoet's JavaFile.writeToPath() and JavaFile.writeToFile() work.

Note: I haven't updated all methods in FileWritingTest because I wanted to get a round of review first. I'll be happy to do the same to the rest of the file for consistency.

Closes #1719

[fejesjoco]

For reasons I don't understand, Path.toFile() may throw UnsupportedOperationException so technically this could be a regression even if nobody wants to know the return value. But JavaPoet does the same here, and since we already had a File to begin with, I hope it should be fine.

[JakeWharton]

This is a binary breaking change and this must be done as a new method with a JvmName that differs from the existing one and the existing one marked as hidden. That will retain binary compatibility and source compatibility for Kotlin (probably) but break source compatibility with Java callers, if there are any.

[fejesjoco]

How about doing exactly what JavaPoet did: introduce new writeToPath/writeToFile methods which are the same as writeTo but with a return type. That way it should be source and binary compatible.

[JakeWharton]

Note that we had no choice in JavaPoet. Kotlin affords us the choice of using hidden methods. I think the risk is probably worth it.

[fejesjoco]

This doesn't seem to work: https://pl.kotl.in/7_gQxvl0X . Also I would find it strange if the Java and Kotlin API surfaces differ only be the name of a method.

[lukellmann]

This doesn't seem to work: https://pl.kotl.in/7_gQxvl0X . Also I would find it strange if the Java and Kotlin API surfaces differ only be the name of a method.

It is possible with something like this:

@Throws(IOException::class)
@Deprecated("Binary compatibility", level = DeprecationLevel.HIDDEN)
@JvmName("writeTo") // preserve the old name in the bytecode for binary compatibility
public fun oldWriteTo(directory: Path) { // change the Kotlin name so the compiler won't complain about conflicting overloads
    writeTo(directory) // resolves to non-hidden variant
}

@Throws(IOException::class)
public fun writeTo(directory: Path): Path {
    // ...
}

That way both Kotlin and Java callers (after recompilation) would call into the variant with return value while still preserving binary compatibility and without needing a name change.

To verify this works you can look at the API dump of the Binary compatibility validator:

-public final fun writeTo (Ljava/nio/file/Path;)V
+public final fun writeTo (Ljava/nio/file/Path;)Ljava/nio/file/Path;
+public final synthetic fun writeTo (Ljava/nio/file/Path;)V

The old variant was only changed to have the ACC_SYNTHETIC flag set (not a binary-incompatible change) and will therefore be inaccessible for newly compiled Java sources (see @JvmSynthetic).

[ebraminio]

I think #1730 is probably related to this.