Allow actual declarations to automatically "inherit" their documentation from expect counterparts in multiplatform

[mikeholler]

Is your feature request related to a problem? Please describe

src/kotlin/commonMain

/**
 * Documentation for X.
 **/
expect fun x(): Unit

src/kotlin/jvmMain:

actual fun x(): Unit {}

I would like to see "Documentation for X." show up in the documentation for the actual jvmMain function in the generated Dokka documentation. Currently, it does not. @IgnatBeresnev suggested I create a ticket here from kotlinlang Slack group. You can find that thread here: https://kotlinlang.slack.com/archives/C0F4UNJET/p1651761386753379 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] You can also paste a link to the relevant issue

Describe the solution you'd like

No changes to the above code, but a behavior change that if an actual signature does not have doc comments, then Dokka should check for comments in the expect function, and use them instead.

Describe alternatives you've considered

This behavior could also be opt-in, by using a documentation directive like @includeFromExpect, but I don't like this as much because it would lead to many duplicated doc blocks.

src/kotlin/jvmMain:

/**
 * @includeFromExpect
 **/
actual fun x(): Unit {}

Additional context

@IgnatBeresnev suggested that giving this issue a kdoc-spec label may be appropriate.

Are you willing to provide a PR? I'm not.

[IgnatBeresnev]

Thank you so much for creating the issue!

Indeed, it's unclear at the moment whether it should or should not be inherited and how (automatically or via additional tags), so this needs to be discussed.

I believe @owengray-google is also interested in this question/enhancement for android documentation reference, so adding the google tag

[joffrey-bion]

This behavior could also be opt-in, by using a documentation directive like @includeFromExpect, but I don't like this as much because it would lead to many duplicated doc blocks.

To draw a parallel, Java's @inheritDoc directive is NOT an opt-in mechanism for inheritance of Javadoc. Its purpose is to allow injecting the inherited doc somewhere in the child doc when the author wants to write child-specific stuff but still reuse doc from the parent.

The doc is inherited by default (from the inheritance hierarchy) if no Javadoc is present on the overriding member.

Indeed, it's unclear at the moment whether it should or should not be inherited and how

Could someone please clarify the exact problematic use cases for inheritance of expect doc in the actual entities?

The behaviour of an actual declaration should by definition match the documentation of the expect, otherwise it would be broken, so it makes sense IMO for it to be inherited by default when no KDoc is present on the actual declaration. Of course, people may want to document platform-specific stuff in actual declarations, and in that case it would override the doc from the expect. If they need to include the doc from the parent within the overridden doc, that can definitely be done by injection using an @inheritDoc approach similar to Java's.

Would this approach cause problems in some special cases?

[owengray-google]

The most obvious problematic case for actuals inheriting from expects is when that would cause an inheritance collision.

For example, if you had /** with docs*/ expect class EfficientSparseArray and then actual class EfficientSparseArray : android.util.SparseArray, it's not clear whether you would expect the android EfficientSparseArray ('s methods) to inherit docs from the expect class or the android.util supertype.

Similarly, the Kotlin language has expect class RuntimeException with actual typealias java.RuntimeException--should the jvm actual inherit docs from the expect class or java.RuntimeException?

[joffrey-bion]

I see, however I see this case as similar to having docs on the actual declarations: overriding the expect docs.

Since the actual methods are not actually written in the actual Kotlin class, I would consider the actual methods to be the ones declared in android.util.SparseArray, and these already have docs, so I think it's reasonable for this situation to behave as if the actual methods had that documentation.

So I would expect in both these cases to use the documentation from the actual platform and not the expect declarations (that is, if such platform doc is present, otherwise we can inherit from expect without collision).