Constructor-like functions should have KDoc

[okarmazin]

Kobweb is very fond of top level factory functions, they are used everywhere. But they aren't documented properly - the documentation typically resides on the type, which we as Kotlin programmers mostly don't declare.

It is then unnecessarily inconvenient to bring up documentation in the IDE since the primary element we work with is the undocumented function, not the documented type. Of course you can click on the type in the popup to switch to its KDoc, but it's a hassle. And it's also a hassle to specify types on the variables.

Then again, you don't want to duplicate vast amounts of text. If duplication of Kdoc is to be avoided, maybe there's a better pattern to use than the factory functions (something with operator fun invoke and companion objects?).

At least the factory functiuon KDoc should have a link to the type - "[Type](see documentation)" - to ensure the user knows there is a documentation. When the Kdoc is empty, you don't know if documentation doesn't exist or if it wasn't downloaded by the IDE (inaccessible documentation is a frequent problem in KMP projects, sometimes the IDE just refuses to download it). If you then think the documentation is missing, you might not even look for it on the type.

---

• [x] Code comments