dokka: 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.

About this issue

Original URL
State: open
Created 8 years ago
Reactions: 117
Comments: 24 (3 by maintainers)

Commits related to this issue

docs: Fix incorrect link format The new format here I've used here is also incorrect because KDocs don't currently support documentation for overloaded methods: https://github.com/Kotlin/dokka/issues... — committed to corycaywood/android-miniapp by corycaywood 4 years ago
docs: Fix incorrect link format The new format here I've used here is also incorrect because KDocs don't currently support documentation for overloaded methods: https://github.com/Kotlin/dokka/issues... — committed to rakutentech/android-miniapp by corycaywood 4 years ago

Most upvoted comments

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.

+19

zach-klippenstein on Jul 9, 2019

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

+15

Ahmed-Mostafa-Ghanayem on Feb 2, 2022

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.

+12

IgnatBeresnev on Feb 2, 2022

Still an issue in 2023

HalfLegend on Sep 21, 2023

Still an issue in 2021

akamuza on Aug 30, 2021

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.

cgruber on Mar 27, 2020

Still an issue in 2023

And still in 2024

rexmtorres on Feb 4, 2024

Same problem here.

alexfacciorusso on Sep 10, 2017

This should 100% be supported, this is essential…

Sxtanna on Nov 24, 2017

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

kamildoleglo on Jul 7, 2020