Can't reference a specific function overload

ghost commented 8 years ago

Consider this scenario: I have two or more methods with the same name but different parameters, just simple function overloads. Then I can't reference one of them explicitly in the documentation.

For example:

class Sample {
    /**
     * If calling this, don't call [fancy] or [fancy] before [build].
     */
    fun fancy(value: String) { ... }
    fun fancy(value: Int) { ... }
    fun fancy(value: String, extra: String) { ... }
    fun build(): Something { ... }
}

Something like [fancy(Int)] and [fancy(String, String)] would be nice in the scenario, to separate the reference by parameter types and thus being able to reference one specific overload.

alexfacciorusso commented 6 years ago

Same problem here.

fabienmoritz commented 6 years ago

It is never too late to answer a good suggestion ! :sweat_smile:

Sxtanna commented 6 years ago

This should 100% be supported, this is essential...

NoHarmDan commented 5 years ago

How is this still not supported?! The suggested solution would look perfectly fine.

alllex commented 5 years ago

Moreover, this missing feature may make documentation browsing a bit misleading. It may be possible to dodge overloading with default parameters in Kotlin, but impossible when operating with JDK classes.

Consider the case when you mention Java method which has several overloads in your Kotlin doc of foo. When you open a quick documentation for foo the Java method mention is shown as a link clicking on which may bring you to the documentation of an incorrect overload.

chrisjenx commented 5 years ago

This still isn't supported?

projectdelta6 commented 5 years ago

I agree this is needed

MikhailShumenko commented 5 years ago

Is it fixed?

fo2rist commented 5 years ago

Looks like it's not. See the doc

Note that KDoc does not have any syntax for resolving overloaded members in links. Since the Kotlin documentation generation tool puts the documentation for all overloads of a function on the same page, identifying a specific overloaded function is not required for the link to work.

Any news from JetBrains team?

zach-klippenstein commented 4 years ago

It may not be required for HTML outputs, but when linking to code in the IDE it is extremely frustrating to not be able to link to a specific overload. E.g. Clicking a link to Job.cancel will take you to the deprecated cancel() function. Clicking a link to kotlinx.coroutines.cancel will take you to CoroutineContext.cancel, and there's no way to link to CoroutineScope.cancel.

christopherfrieler commented 4 years ago

I just came across this limitation and would definitely appreciate to see this fixed for the same reason: it is really annoying to have these "broken" links in my IDE.

At the same time I'm not sure if this is something to be done in dokka in the first place. The Kotlin Spec doesn't say anything about how links into Kotlin code are specified or resolved (see Documentation comments). Instead there's a big TODO.

I think the Spec should specify this first. Then (or maybe simultaneously) tools like dokka or any IDE can implement that. I assume IntelliJ/Android Studio doesn't use dokka internally anyway to resolve those links, so just implementing that in dokka wouldn't even help in my IDE.

DavidSonoda commented 4 years ago

It is never too late to answer a good suggestion ! 😅

Strongly agreed! It's confusing to see those broken links.

cgruber commented 4 years ago

I've now renamed methods to avoid this issue, and not actually useful renames. Please consider supporting function overload targeting, especially since not all overloads are the result of defaults, but may take very different types (but do the same thing, and thus be usefully named the same.

vincentfree commented 4 years ago

Same problem, this looks like something that just should be there. I'm trying to document some usage of the jdk Cipher's doFinal method, im trying to express the usage of .doFinal(ByteArray) but it defaults too .doFinal() this isn't what's happening so the documentation isn't documenting the intent this way

vad-zuev commented 3 years ago

still no updates on this? I can just repeat what others said: being unable to link a specific overload is really frustrating ><

kamildoleglo commented 3 years ago

Sorry, still nothing from our side as this is a change in KDoc that must be done by the IntelliJ team, here's the relevant ticket: https://youtrack.jetbrains.com/issue/KT-15984

akamuza commented 2 years ago

Still an issue in 2021

ichenhe commented 2 years ago

I have to give the function a different name. It's troublesome.

Ahmed-Mostafa-Ghanayem commented 2 years ago

This issue will celebrate 6th birthday soon and still no updates.

IgnatBeresnev commented 2 years ago

Hi, yeah :) Unfortunately, this problem spans beyond dokka (kdoc spec, probably some compiler/ide work as well), so it's not as easy to fix, but it's definitely on our radar, we'll keep you posted if anything update-worthy comes up.