Option to de-emphasize some opt-in symbols

[martinbonnin]

See https://github.com/Kotlin/dokka/issues/1862 and https://github.com/Kotlin/dokka/issues/3922.

In addition to being able to filter out some opt-in symbols (@ExperimentalApi, @DelicatedApi, and the likes), it would be useful to have some visual clue that they are "low priority".

Maybe a badge or grey them out or thinner font, I'm not 100% sure but opening this for tracking.

[CLOVIS-AI]

Here is an example of a page where this would be useful: https://opensavvy.gitlab.io/ktmongo/api-docs/dsl/opensavvy.ktmongo.dsl.options/-count-options/index.html

Here, 90% of users are only interested in the limit method (and maybe the constructor). All other methods exist to let advanced users add their own functionality on top of the library type, via extension functions. They must remain public and documented for such users, but shouldn't make it harder to the average user to know which functionality is available.

Since IntelliJ already de-emphasizes these methods (they are ranked lower in auto-complete), it would be nice if Dokka did the same. However, I don't have strong opinions on how to do so.

A possible idea: whenever they are opt-in symbols, they should be at the end of their respective section. Thus, on that page, the order of properties would be:

Constructors:
 - Constructor
Properties:
 - allOptions (opt-in)
 - context (opt-in)
Functions:
 - limit
 - toString
 - accept (opt-in)
 - acceptAll (opt-in, extension)
 - freeze (opt-in)
 - option (opt-in, extension)
 - simplify (opt-in)
 - toBsonDocument (opt-in)
 - toJava (opt-in, JVM-only)
 - writeTo (opt-in)

[martinbonnin]

Been thinking a bit more about this and I'm not sure I see a simple way to achieve this. I've been toying a bit with saturation but it looks a bit odd IMO:

Putting opt-in symbols at the end of the list is also slightly unsatisfying IMO as it breaks the common expectation of lexicographical order.

FWIW, I favour exhaustivity vs abstract beauty in KDoc. I don't mind that much if the docs are not "nice" (think javadoc 🙃 ) as long as the information I need is there and easy to access. It's not like i'm going to browse KDoc to learn about a lib.

So I'd say it's ok to have too much information (compared to not enough). Until we figure out a good visual hint there, I think I'd be ok with just the filters for starters. Links from user guides could include the query param to filter them out by default (?filters=optIn1,optIn2) and anyone landing on the page without filters could remove them with one click.