https://kotlinlang.org logo
#dokka
Title
s

simon.vergauwen

07/29/2021, 11:05 AM
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.kthttps://github.com/arrow-kt/arrow/blob/main/arrow-libs/fx/arrow-fx-coroutines/src/commonMain/kotlin/arrow/fx/coroutines/ParTraverseEither.kthttps://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 🙂
👀 2