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.

---

• Code comments

[bitspittle]

At some point before 1.0 we'll be doing an audit of the codebase and filing in all missing docs, including factory methods and multiple methods with the same docs but slightly different parameters.

I like the concerns of this bug but at the same time worry it's too broad... This is the sort of bug that doesn't have a clear "ok you can close me now" condition. This is really more an umbrella bug, but I think we already have one for docs? I'll check. But I'm sure I will do it eventually as I did a similar pass for my project Kotter.

Maybe you might want to file specific instances of missing docs instead. (It doesn't have to be one bug per method but maybe per method ) That will feel a lot less worrisome and easier for new developers to pick up and submit PRs for? (But also don't go crazy, we'd like to avoid blowing up the issue section)