Kotlin Standard Lib: Extensions for External Classes

1

Hey!

So both Kotlin and Groovy provide extensions for existing classes of the JDK. The Kotlin standard library consists of multiple files where it uses statically resolved extension functions to extend existing JDK classes. Groovy has a single god class (nearly 20000 LOC) called DefaultGroovyMethods where all methods are listed that extend existing JDK classes.

In Groovy I always found it very useful to have API docs for the extended JDK classes. Kotlin also provides documentation for new Kotlin-specific classes along with extension functions of JDK classes and they are always listed in the section “extensions for external classes”. The main difference is, that the Groovy documentation is splited into GAPI and Groovy-JDK and the Groovy-JDK sticks to the package structure of the JDK and the Kotlin standard lib has its own package structure.

Example: The Groovy-JDK has an “extension method” called “java.io.File.getText()” [G1] which is defined in code at [G2]. The Kotlin standard lib has an extension function called “kotlin.io.File.readText()” [K1] which is defined in code at [K2].

The problem is, that in IDEA we actually work with “java.io.File” instead of “kotlin.io.File”.

Are there chances to have a documentation of extensions for external classes in the Kotlin standard library that are listed with the JDK package structure? Or is this even possible, because we also use “kotlin.Double” instead of “java.lang.Double”, so we should ignore “java.lang.Double” in this case.

[K1]: http://kotlinlang.org/api/latest/jvm/stdlib/kotlin.io/-file/read-text.html
[K2]: https://github.com/JetBrains/kotlin/blob/build-0.12.1218.5/libraries/stdlib/src/kotlin/io/ReadWrite.kt#L70
[G1]: http://docs.groovy-lang.org/docs/groovy-2.4.0/html/groovy-jdk/java/io/File.html#getText%28%29
[G2]: https://github.com/apache/incubator-groovy/blob/GROOVY_2_4_0/src/main/org/codehaus/groovy/runtime/DefaultGroovyMethods.java#L16899

2

So the story is somewhat complicated here. For the primitive types (such as kotlin.Double) and collections, we do provide Kotlin's own counterparts in the type system. You do indeed work with kotlin.Double and kotlin.List, and the documentation page does list all of the APIs that are available for those classes - both regular methods and extension functions.

On the other hand, there is no such thing as kotlin.io.File. The Kotlin standard library defines a number of extension functions for the File class, and those functions are defined in the kotlin.io package, but the class you’re extending is the same old java.io.File.

All the extension functions defined for java.io.File are indeed shown on a single page, so it shouldn’t be hard to see what APIs are available.

It’s true that we don’t currently group those pages according to the Java package structure. Adding such a view sounds like a good idea, and we’ll consider adding it in an update of our documentation tool.

3

The link seems to be broken. I guess it should be kotlin.io - Kotlin Programming Language

4

No, the correct new link is java.io.File - Kotlin Programming Language