Inconsistent behaviour for overloaded declarations in multi-platform projects

[whyoleg]

In case there are multiple declarations with the same name but with different parameters (overloaded functions) Dokka will render such declarations in one group (even if it's overloaded by receiver) and create an additional separate page for all such declarations with extended details (full description, parameters descriptions, samples and so on).

For example kotlinx-io has function indexOf which has multiple overloads for both parameters and receivers and so they are shown in one group on functions page and have a separate page. There is no issues in this case because indexOf is declared only in common source set.

Now let's take a look on readString function from kotlinx-io (functions page and specific function page). In case of readString we have multiple common declarations + additional overloads on JVM.
But if we will look on documentation (for both pages), we will see tabs, by selecting them declarations will be filtered explicitly by source set where they are defined. For this declarations this looks more or less natural and expected (because overloads only add additional parameter), though it could be not convenient as you can't see all available declarations for jvm on one page.
Just for reference, if we will look on similar declaration in current stdlib documentation (build with older dokka) we will be able to see all available declarations.
Here is an example for String.lowercase specific function page and screenshot from functions page (as there is no possibility to create an anchor link there):

functions page

Now, if we will continue looking on other declarations, f.e write (functions page and separate function page) we will see the same behaviour, but in this case, because the declarations have more difference, it becomes harder to understand which declarations are available on specific platform as there is no view to show all functions available, only switch between tabs.

And last example will be with asSink/asSource functions (links for asSink, functions page and separate function page). Here we have no common declarations but only platform specific ones (for apple using NSOutputStream and jvm using OutputStream). Here the inconvenience is a little different - we now will see only declaration from one platform by default, while the other one will be hidden under tab selection.

This can become even more confusing if we will have both extension functions and basic top-level functions, like in case with serializer function in kotlinx-serialization where we generate two separate groups on functions page (one for extensions and one for top-level functions) and only one separate page for both extensions and top-level functions with both common and jvm declarations there. Additional note here regarding tabs selector which is located just above first declaration but selection one or another will affect full page (both extensions with different receivers and top-level functions)

Similar/related issues in other projects:

• kotlinx-datetime
  • *.toKotlinInstant on functions page and separate function page
• kotlinx-coroutines
  • [js]asPromise and [wasmJs]asPromise are on different pages for specific functions: js and wasmJs, but single line on functions page (same for other functions related to promises)
  • *.asCoroutineDispatcher on functions page and specific function page
  • Flow.debounce on Flow members & extensions page and 2 separate function pages in different packages kotlinx.coroutines.flow and JDK specific kotlinx.coroutines.time
• kotlinx-serialization
  • serializer and serializerOrNull functions on functions page and specific function page
• could be related
  • Provide spec for multiple platform-specific non-actuals with identical DRIs #3503 - the same could happen with types instead of functions, though, most likely it's more rare

Expected behaviour is TBD but possible solutions could be:

• when selecting more specific tab (f.e jvm) show all declarations there, so both from jvm and common - as they will be all available for use in code (though, this will not help with asSink case)
• always show all declarations + additionally show tags if declaration is available only in specific source set (so similar to current stdlib), could be shown similar to how we show platform tags for packages:

packages in coroutines

Checked with Dokka version: 1.7.0, 1.8.10, 1.9.10 and 1.9.20 behaviour is identical.