Copy Opt-ins from the original sample's function/class/file to a generated runnable sample
fzhinkin opened this issue · comments
Opt-in requirements are an excellent tool for getting a user's consent to use an experimental or unstable API.
For example, Kotlin Stdlib uses opt-ins when a new API is introduced to let users know that it might change in the near future.
If a KDoc for an API annotated with an opt-in requirement refers to a sample, that sample must either propagate the requirement or opt it in.
When Dokka generates a link to a runnable sample, the resulting sample does not include opt-ins from the original sample. As a result, when a person who opened the sample tries to run it, they get a compiler error.
For example, here's a small project: https://github.com/fzhinkin/dokka-sample-opt-ins
There's a function that requires opt-in. And there's a sample that opt-ins the required annotation.
Generated docs look nice: https://fzhinkin.github.io/dokka-sample-opt-ins/dokka-sample-opt-ins/org.example/experimental-function.html
But if you click on "Open in the playground", the main function won't contain the opt-in.
For this particular project, the sample won't run anyway, but for Stdlib samples, it affects user experience as an opened sample could not be executed as is.
It would be nice to annotate the main function of the generated runnable sample with all the annotations collected from the original sample function, class, file.
An update: the playground opt ins all require-opt-in annotations, and if something was not opted in yet, then it should in the near future.