I’m not sure if others have faced this problem, but I have a hard time searching for a function (along with a quick description) that are available for a given class. It would be nice, if there was a summary or Index on top of each page and a link to the detailed description
For example compare kotlin.collections - Kotlin Programming Language and this Collections (Java Platform SE 8 ) . In the java version I can easily scan through the list of methods that are available, but on the kotlin collection it is significantly more cumbersome. Most of the time on the kotlin page, I end up guessing a name and try to use browser search to find a function. Or find a function using intellisense that is close enough to match my needs without knowing if there is a simpler or better function to solve my problem.
Can some on the kotlin documentation team please take a look at this request.
Thank you.
2 Likes
We’re working now on redesign of documentation and we’ll think about this point, thanks for suggestion!
1 Like
While changing the html layout of the documentation would be nice (I also prefer the way the java docs look) I don’t think just copying the java style works. Fact is that the java API is far better documented. It just contains much more detailed information about each class/function. I sometimes would like to see more detail about some kotlin functions (Big O info, exceptions, etc). BigO data especially for some extensions would be nice. A lot of people stumble over the fact that List<T>.plus has a runtime of O(n) and not O(1), even if the underlying List is seemingly “immutable”. I understand why this is the case, but the number of discussions about this suggest it’s something that should be mentioned there.
That said I think the java documentation might be a bit to detailed in some cases, leading to so much documentation that I just skip it and look at the source, because it’s easier and faster to understand.
So while I’d like to see a rework of the html layout for the documentation I think there is definetly room to improve the content of the documentation as well.
Is there any document about it (KEEP, etc) which we can take a look at and give feedback or is this an internal discussion so far? I’d love to take a closer look at this, but I don’t think I’ll find the time to go through the entire documentation and give feedback on everything so some place to start would be greatly aprechiated.
So far we have internal discussions on rework of documentation layout.
Thanks for the feedback. Request for documenting algorithm complexity is tracked in https://youtrack.jetbrains.com/issue/KT-25425. If you have some specific suggestions to improve the docs, please create Youtrack issues.
1 Like
Thank you for taking this suggestion into consideration.