Hello! I'm wondering, how do people document files...
# dokka
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!
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
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
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
However, Dokka does support embedding documentation from
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
you have
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
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
👍 2
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 🙂
🦜 1