Hello! I'm wondering, how do people document files...

# dokka

[adte]

Hello! I'm wondering, how do people document files or packages?

For functions there's the /** doc */ syntax, but what if I want to document what's inclided in a given file or a package?
Do people write a README.md file inside the package, or what is the convention?

I didn't see any guidance about that in the Kotlin documentation style guide.
Thanks!

[Ignat Beresnev]

Hi! At the moment, I don't think there's any official and recommended way to document packages/modules that would be backed by the Kotlin specification, like package-info.java in Java.

In regards to documenting files, I personally never felt the need to document the file itself, usually it's enough to document the declarations within the file separately. But I can see how it can be useful if you have a common file like Math.kt with a bunch of top-level functions, and you want to provide some common documentation. I'd be interested to hear if anyone has had such cases

[Ignat Beresnev]

However, Dokka does support embedding documentation from .md files, so you can leverage that. There's no strict rules on where the files should be defined though, as long as you can pass it to Dokka. Example of what it'll look like: https://kotlinlang.org/api/kotlinx.coroutines/

Given that it's a simple markdown file, you don't have to use Dokka and can just read it from within the IDE, of course.

Documentation on this: https://kotlinlang.org/docs/dokka-module-and-package-docs.html

For instance, in kotlinx.coroutines you have README.md files in the root of each module, which contain descriptions for both the module (only one) and the packages within it. Example: https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/README.md

In kotlinx.serialization there's a single file in the root of the project that describes all modules and all packages at once. Example: https://github.com/Kotlin/kotlinx.serialization/blob/master/dokka/moduledoc.md

[adte]

Thanks Ignat! I will look to document packages with .md files, I think it's a good solution and then people can also read the files when browsing GitHub 🙂