Resolution of links to extensions in KDoc

[whyoleg]

This is an issue to discuss Resolution of links to extensions in KDoc. The full text of the proposal is here.

During the migration of Dokka analysis to K2, several questions arose around KDoc links resolution.
In particular, it was unclear how a link to an extension should be resolved in the presence of type parameters.
Link resolution in KDoc is not fully specified, and for this reason some cases are currently implemented
differently in K1 and K2 analysis.

The goal of the proposal is to try to describe consistent rules on how KDoc links to extensions should be resolved.

[CLOVIS-AI]

I'm not sure this is on-topic for this KEEP, but I'd very much like to see a way to disambiguate links of different things that have the same name. For example, when a class and a top-level function exist, it is not currently possible to create a link that refers to one of them specifically. Unlike regular function overloads, which are all listed on the same page, so the disambiguation isn't particularly needed, homonyms on different pages hinder the documentation quality at the moment.

[whyoleg]

Hey @CLOVIS-AI, this is known and tracked in https://youtrack.jetbrains.com/issue/KT-19765/KDoc-Provide-ability-disambiguate-links-to-classes-vs-links-to-functions
Feel free to add a use-case there.