Is there any recommended way of documenting a file...

# dokka

[simon.vergauwen]

Is there any recommended way of documenting a file of top-level functions? It seems like a common approach in many libraries, including Ktor but it typically doesn’t result in really nice pages in the API docs. I.e. https://arrow-kt.io/docs/apidocs/arrow-fx-coroutines/arrow.fx.coroutines/index.html
(Although I think some of our styling is broken here too 😕)

For example, I wish I could document this file similar to if it were a class. https://github.com/arrow-kt/arrow/blob/main/arrow-libs/fx/arrow-fx-coroutines/src/commonMain/kotlin/arrow/fx/coroutines/ParZip.kt

Or similarly for top-level functions that are related but spread over files:
• https://github.com/arrow-kt/arrow/blob/main/arrow-libs/fx/arrow-fx-coroutines/src/commonMain/kotlin/arrow/fx/coroutines/ParTraverse.kt
• https://github.com/arrow-kt/arrow/blob/main/arrow-libs/fx/arrow-fx-coroutines/src/commonMain/kotlin/arrow/fx/coroutines/ParTraverseEither.kt
• https://github.com/arrow-kt/arrow/blob/main/arrow-libs/fx/arrow-fx-coroutines/src/commonMain/kotlin/arrow/fx/coroutines/ParTraverseValidated.kt
Our goal is to document as much as possible in the actual code. That’s also why we have a tool (which I’m trying to move to a Dokka Plugin) that verifies our snippets inside the KDocs, so we have guarantees that they’re up-to-date and working. That way all documentation is also at the users finger tips from within IDEA.

Any and all tips welcome 🙂