Kotlin
Can't reference a specific function overload
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.
How is this still not supported?! The suggested solution would look perfectly fine.
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.
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?
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.
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.
It is never too late to answer a good suggestion ! 😅
Strongly agreed! It's confusing to see those broken links.
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.
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
still no updates on this? I can just repeat what others said: being unable to link a specific overload is really frustrating ><
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
This issue will celebrate 6th birthday soon and still no updates.
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.
This is actual for a function and a property with the same name:
val name = ""
fun name() = ""
Adding my voice as someone who just went to do this, and found I could not....bummer.
Also, to add a laugh, JetBrains AI Assistant lied to me and told me I could 🙃 ...lol - ai-telling-lies-about-kdoc.txt
