Ambiguous link for properties from a primary constructor

[vmishenev]

This example is from the Dokka unit test documented seealso with reference to property for class:

/**
* @see abc Comment to abc
*/
class Foo(val abc: String)

Here abc is a parameter and property.
From the point of IDE view, the link [abc] leads to the same position in a source file independently of whether the abc is a parameter or property.
From the point of generated documentation view, the link [abc] can lead to a parameter (currently, a constructor page) or a property page.
In K1 @see abc always refers to the property Foo.abc.
In K2 - to the parameter abc of constructor.

---

Proposal
In KDoc there is the same way to assign documentation for a parameter and property from a constructor - only via block tags. So both links are possible.

/**
* @param abc parameter doc
* @property abc property doc
* @constructor some KDoc
*/
class Foo(val abc: String)

To keep a link to the parameter, [abc] should lead to a parameter but [Foo.abc] should lead to a property.

[IgnatBeresnev]

Also relevant for plain symbol links, such as

/**
 * Enum class with param [x]
 */
enum class EnumKotlinParam(val x: String) {
    NORTH("n"),
    EAST("e")
}

Related: #3334

[atyrin]

JIC: A usage in the wild (if someone had doubts): https://github.com/square/okhttp/blob/0343ff823c17357c8e1994b4c0f0ea783dcace7a/mockwebserver/src/main/kotlin/mockwebserver3/SocketPolicy.kt#L83
In this case (nested class), with K2, we generate an incorrect link to the property.
http://localhost:63342/okhttp-parent/k2/mockwebserver3/mockwebserver3/-socket-policy/-do-not-read-request-body/--root--.html instead of http://localhost:63342/okhttp-parent/k2/mockwebserver3/mockwebserver3/-socket-policy/-do-not-read-request-body/http2-error-code.html

[atyrin]

One more point. It affects also references in the class body:

class ClassWithLongSeeAlsoList(val propInPrimaryConstructor: String) {
    val propInBody: String = ""

   
    /**
     * Adds a [propInPrimaryConstructor] to this group. [propInPrimaryConstructor] is a property from constructor
     *
     * Adds a [propInBody] to this group. [propInBody] is a property in the class body
     */
    fun ref() {
    }
}

[vmishenev]

This issues was addressed in Kotlin/KEEP#389