Want to annotate Docs -- can we?

Site Feedback
1

For example, I’d love to add a note to File.outputStream of “This will use the default setting, which is ‘append’” If you need to overwrite the file, consider OutputStreamWriter(FileOutputStream(file, false)).use { ... }

And I’m sure everyone else has plenty of “gotchas” that they only figured out after some pain, and would love to help others with. And, let’s be honest - the Kotlin docs are not the best. (Good luck glancing at the docs for Set and figuring out which functions are Set-specific and which are Collection-generic!) We would all love to chip in and help.

Proposed: Crowdsource it! A link on the docs page that lets anyone (or anyone with an https://discuss.kotlinlang.org/ account) suggest a one-line addition. It would go through a review process before being shown on the site.

2

The docs, like everything else in Kotlin is open source.
The source of the website can be found here and the docs of the standard library are generated from the kdocs in the source.
You can always send a pull request there.

3

Which is great, but is a lot of friction to add a one-line helpful comment.

  1. Search on the existing comment.
  2. Look through results to find the right file. (in my case kotlin/libraries/stdlib/jvm/src/kotlin/io/FileReadWrite.kt)
  3. Fork the repository.
  4. find the file again. (but forked respositories aren’t searchable)
  5. Edit the code to add the note.
  6. Create a pull request.

This is 5 steps more than the ideal.

1 Like
4

Please follow https://youtrack.jetbrains.com/issue/KT-28642 for updates