Would it be possible to de-emphasize `@OptIn` meth...

# dokka

[CLOVIS]

Would it be possible to de-emphasize @OptIn methods somehow?

For example on this page, 99% of users only care about the limit method. All other methods are annotated with @LowLevelApi and are only useful to users who want to provide features missing from the library.

[Oleg Yukhnevich]

Yeah, I see, this looks reasonable for some cases, but I do think, that it's not the case for every OptIn annotation. So this should probably be somehow configurable, per OptIn... Should we also then have ability to sort public declaration above protected for the same reason?
I'm not even sure, if it will be possible to do this in custom Dokka plugin, as we do have some sorting in-place during HTML rendering

But overall, the sorting is rather complex issue for Dokka, as it's not clear how overall it should happen:
• should we sort declarations as in code?
• alphabetically?
• what to with extensions? do we sort them with members or separately
• what to do with top-level declarations from different files?
• etc
We even have some differences in K1 and soon-to-be K2 analysis (https://github.com/Kotlin/dokka/issues/3590)
Additionally, not saying that it's required, but the similar concern exists for IDEA

I could only suggest you filling a feature requests for now (http://kotl.in/dokka-issues)

[mbonnin]

My 2 cents

alphabetically?

yes. I think this is what javadoc is doing (and current dokka too)? Has always looked fine by me.

what to with extensions? do we sort them with members or separately

with members, with a filter.

what to do with top-level declarations from different files?

if it's all alphabetical, I think it's fine?

[mbonnin]

Re: opt-in, being able to show them grayed out or with some visual indication would be enough IMO + ability to filter them out if needed

[mbonnin]

Show:
[ ] Functions
[ ] Properties
[ ] Extensions
[ ] Deprecated symbols
[ ] Opt-in symbols

[Oleg Yukhnevich]

(and current dokka too)

yes, though there could be some places where it's not true (not 100% sure, there is a lot of code in Dokka 🙂 )

if it's all alphabetical, I think it's fine?

yeap, with alphabetical everything is easy

But, not saying that it should be big factor, there are cases when some functions are related, called differently, located in code near and it would be nice to show them in API reference near each other.
As an example, In my lib, I do have two functions verify and tryVerify (API reference) and because there are other functions with names between T and V, it feels less nice I believe (subjective of course).
Another theoretical example is kotlinx.coroutines.flow package - where alphabetical order could be not the best choice

Still, not sure that all of this should be handled by just sorting, some of such things could be handled by @see tag (to keep finding declarations easier). In other languages sometimes there are so called groups which allow to add a tag to declaration and so there will be a separate page for this - not sure what will be the best approach for Kotlin though

Regarding filters: yes! Filters are nice. But! First of all, it's not that easy to implement this with current Dokka FE. Secondly, then we should have some defaults and "memory" for them. E.g probably you will want to always show opt-in symbols if you are experienced user, but probably would want to hide by default internal APIs - there are a lot of things to keep in mind and so to design/research
All of it needs time...

The future is bright, but our resources are rather tight...
That's why it would be nice to have this as a feature request in our issues (e.g for here is one for opt-in) so that we will not forget about it, when there will be more resources 🙂

[mbonnin]

such things could be handled by @see tag

Yes!

we should have some defaults and "memory" for them

100%. I don't think the memory needs to be persistent though? I think I'd be happy with everything displayed by default and a query parameter to filter that out. When sharing a link, I can decide what filters to include. With everything being displayed by default, deprecated and opt-in symbols could have some kind of visual clue (striked out/grayed out) as an additional hint.

All of it needs time...

Yup, I hear you 100% this is full of tradeoffs and implementation is tough... I'd just thought I'd start my Christmas list 🎅 😄

it would be nice to have this as a feature request in our issues

I filed a bunch 😄
• https://github.com/Kotlin/dokka/issues/3922
• https://github.com/Kotlin/dokka/issues/3923
• https://github.com/Kotlin/dokka/issues/3924
Let me know if you need more details on any of those

[CLOVIS]

> Yeah, I see, this looks reasonable for some cases, but I do think, that it's not the case for every OptIn annotation.
I'm curious, do you have an example of when they are as important as everything else on the page? I've always seen them used as either "this is functionality that isn't stable yet" (would warrant some de-emphasizing) or "this functionality is easy to mis-use" (same)

By "de-emphasize", I don't mean completely removing them! But just nudging users towards regular methods instead of drowning them in opt-in methods

[CLOVIS]

alphabetically

💯

what to with extensions? do we sort them with members or separately

with members

Very often, I have extensions that build on top of members. In the link I gave, there is accept (member) and acceptAll (extension). It's nice that they're next to each other.

[Oleg Yukhnevich]

as important as everything else on the page?

IMO, experimental API's are one of them, e.g if we deprioritize them, then we could probably receive less feedback about them because users will know about them less, and so we could leave them experimentally
Additionally, an interesting case: what if one of overloads has optIn, but other not - we should not de-prioritize it probably 🙂

Also, in this case, alphabetical sorting might become confusing, as if there will be opt-ins, the sorting will be not intuitive probably

[Adam S]

one workaround idea:

• Configure the default JVM DokkaSourceSet to exclude all elements with the opt-in annotations.
• Create a new custom DokkaSourceSet called JVM-internal or JVM-advanced with the same content as the JVM source set, but don't exclude anything.
Users could toggle between the JVM and JVM-internal source sets.

I'm not 100% sure it's possible. And it's not very pretty/intuitive.