Kotlin documentation of API

Support
1

I have listened from many developers , that the APIs documentation of Kotlin is poor in STYLE.
Like for example if I want to know what are, ALL properties and functions supported by String class in kotlin and will try to have quick reference BUT
I have to scroll through the entire page to see all the properties and functions in the →
String - Kotlin Programming Language .
BUT
Kotlin team can simplify this by placing a summary table at the start of the page .

This is what most language /library does while documenting the APIs . Please see
https://docs.oracle.com/javase/8/docs/api/java/lang/String.html

Or you can see any library documentation . You will see a “Summary” section and followed by "Description section " .
Please please update your documentation with this simple thing. This will help the developer to refer all the APIs fast .

3 Likes
2

is very important, I agree!

Another serious issue is the lack of examples. Aforementioned oracle docs have plenty of usage examples with commentaries.
Kotlin for the most of API has no examples!

2 Likes
3

Kotlin documentation unfortunately is very poor in general. it doesn’t even specify what happens if you call "abc".get(17) for example.

1 Like
4

You are wrong. Please search the documentation before making such statements.

Kotlin in fact has very good (one of the best) documentation for stdlib.

Correction: OK, It does not say what exception it will throw since it is platform dependent.

5

It doesn’t even say that it throws an exception. Or that it’s platform dependent. Or which platforms throw which exceptions. According to the documentation, it might also return " :space_invader:" or eat your pictures folder.

6

OK, you’ve got the point here. Basic platform classes are not that well documented.They delegate directly to platform classes and in most cases it is obvious. In this particular case the platform has different name charAt. You can open a ticket for that.

7

I’ve already created issues about missing documentation, and there are much worse cases than this one. For example Java contracts for classes like List and CharSequence aren’t documented in Kotlin, so if you implement these interfaces in Kotlin without looking at the Java documentation, your classes will violate the Java contracts which will cause issues in Java as well as in Kotlin (on all platforms).

Fun fact for the above example: "abc".get(17) seems to return a 0 char in JavaScript instead of throwing an exception. Stuff like this is really not obvious from looking at the code and should be documented.