Redesign platform / source set selector

[IgnatBeresnev]

Current selector that can be found in the header causes a lot of questions, it's unclear how to use it and what it's supposed to achieve.

It should be redesigned with the following questions in mind:

1. Which problem / use case should it address?
2. Do platforms need to be colored? If so, how should colors be chosen in complex configurations with a lot of shared source sets, such as in skikio

Notes:

• Currently, source set dependencies are not handled visually in any way, and it's difficult to understand which tabs are related and should be enabled/disabled together. For example, if I'm developing a macos application, I most likely want to see declarations from macos and other source sets that macos depends on. However, with the current selector, it's not always clear. I can assume I need native and common, but there's no confirmation. It would help if it was automatic (i.e native and common are selected as well if you click on macos) or if there was a graph/list of source set dependencies somewhere.

Related issue: #2696

[IgnatBeresnev]

Two more things to consider / address:

• Users might use the selector to determine module/package platform, as in some cases it's the only indicator.

---

• What should be the order in which platforms/source sets are enumerated in one line? It seems that currently it is not sorted by name only, but even if it was - sorting by the name might not be logical.

[ilya-g]

I've noticed that source set bubble sort order is different in header and in packages:

[IgnatBeresnev]

Could be useful: #2906

[IgnatBeresnev]

Related: #1549, #1534

[IgnatBeresnev]

Note: the current JS code that is responsible for these filters is a bit difficult to reason about and it contains some code that has nothing to do with the platform content (like scripts for the playground and the navigation menu, dark/light mode), and this leads to unexpected bugs like #3011 (should be kept in mind).

It would be ideal to refactor/get rid of the internal filtering logic along with this redesign.

[jeffdgr8]

I'll add some input for how my library behaves currently and what I would expect the behavior to be.

This is my library's source set hierarchy:

(Note: this changed slightly since posting this, native -> linuxMingw & nativeCommon -> native to align with the default hierarchy template.)

                     ┌────────┐
                     │ common │
                     └───┬────┘
              ┌──────────┴───────────┐
              │               ┌──────┴───────┐
              │               │ nativeCommon │
              │               └──────┬───────┘
              │           ┌──────────┴──────────┐
        ┌─────┴─────┐ ┌───┴───┐             ┌───┴────┐
        │ jvmCommon │ │ apple │             │ native │
        └─────┬─────┘ └───┬───┘             └───┬────┘
         ┌────┴────┐      │       ┌─────────────┼─────────────┐
    ╔════╩════╗ ╔══╩══╗   │  ╔════╩═════╗ ╔═════╩══════╗ ╔════╩═════╗
    ║ android ║ ║ jvm ║   │  ║ linuxX64 ║ ║ linuxArm64 ║ ║ mingwX64 ║
    ╚═════════╝ ╚═════╝   │  ╚══════════╝ ╚════════════╝ ╚══════════╝
     ┌─────────────────┬──┴────────────┬───────────┬─────────────┐
╔════╩═════╗ ╔═════════╩═════════╗ ╔═══╩════╗ ╔════╩═════╗ ╔═════╩══════╗
║ iosArm64 ║ ║ iosSimulatorArm64 ║ ║ iosX64 ║ ║ macosX64 ║ ║ macosArm64 ║
╚══════════╝ ╚═══════════════════╝ ╚════════╝ ╚══════════╝ ╚════════════╝

And this is how the Dokka source set selector appears:

First of all, it's odd that ANDROID appears in all caps. This might be a side-effect of JVM being all-caps? They're also the only two in green, with the remaining common/intermediate source sets all being gray, probably since no other target-specific source sets have source code in them.

The majority of my library's public API is declared as expect in common. The majority of the actual implementations are in jvmCommon, apple, and native. There's only a single API actual implemented in nativeCommon. android, jvm, and apple also additionally add a few platform-specific public APIs.

I consider it relevant for a library consumer to see expect APIs at the level they're declared, with visibility into which platforms appear beneath that level. But which source set actuals are implemented in is just an implementation detail, not relevant for library consumers reading the API docs.

For this reason, I wouldn't expect nativeCommon or even jvmCommon to appear in the source set selector at all. No public APIs are documented specific to those source sets.

Consideration should also be made for what should be communicated as a supported platform. It isn't clear to a reader that the apple source set encompasses both iOS and macOS (but not watchOS or tvOS), or that native encompasses both Linux and Windows.

There could be a concept of a supported platform which can encapsulate all its architectures, maybe with a way to also see which architectures are supported within each of them. For example, iOS should encapsulate iosArm64, iosX64, and iosSimulatorArm64, and Linux should encapsulate linuxX64 and linuxArm64, with the ability to see both x64 and ARM64 architectures are supported for each. Windows should be used to encapsulate mingwX64, as the platform's name.

A specific platform target architecture could be broken out as a selector if it does actually provide some unique public API. But this is rare, where the more common use-case would be common API between platform architectures.

In my library, native doesn't add any additional public API, but Linux and Windows as supported platforms should appear in the selector themselves instead.

Taking these ideas into consideration, I'd expect the platform / source set selector for my library to be:

         Common         Apple
JVM  Android  iOS  macOS  Linux  Windows

These are the supported platforms (combining architectures), as well as intermediate/common source sets that contribute to the documented public API.

The platform colors could align with the standard lib docs: JVM and Android green, native targets (iOS, macOS, Linux, and Windows) purple, and JS yellow, with the top-level Common blue. Intermediate source sets could inherit their colors from the targets beneath them (Apple purple in this case), with gray for intermediate source sets that bridge multiple colors. An API to modify the color for a platform or source set would be nice too.

Selecting a platform would also select the intermediate/common source sets that the platform is in, i.e. selecting iOS would select Apple and Common as well. Selecting Linux or JVM would also select Common. (Currently selecting a source set will only select the single source set directly above it in the hierarchy.)

Hopefully this is helpful, describing from the perspective of my own library, and thinking how this might work for other use cases as well.