Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Copy Opt-ins from the original sample's function/class/file to a generated runnable sample #3638

Open
fzhinkin opened this issue May 31, 2024 · 1 comment
Labels
enhancement An issue for a feature or an overall improvement feedback: Kotlin libs Feedback from Kotlin's internal libraries

Comments

@fzhinkin
Copy link

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.

@fzhinkin fzhinkin added the enhancement An issue for a feature or an overall improvement label May 31, 2024
@IgnatBeresnev IgnatBeresnev added the feedback: Kotlin libs Feedback from Kotlin's internal libraries label May 31, 2024
@fzhinkin
Copy link
Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement An issue for a feature or an overall improvement feedback: Kotlin libs Feedback from Kotlin's internal libraries
Projects
None yet
Development

No branches or pull requests

2 participants