Hi :wave: I would like to suggest an enhancement ...

# language-evolution

[nisrulz]

Hi 👋

I would like to suggest an enhancement to the @OptIn annotation.

My usecase is that when we start using non-propagating opt-in, lets say internal to library in a multi-module library project, then there is no ability to provide reasoning for why we are @OptIn . In this particular case the reasoning would be “Internal to main library” for example. The reason can vary though. The actual annotation of say ShinyNewAPI does have the message via the @RequireOptIn annotation, like so

@RequiresOptIn(message = "This API is experimental. It may be changed in the future without notice.")

However this message is for clients who try to use the class marked with the annotation. When writing code for internal modules, the reason to opt in could vary. Maybe it could be like “Donot want to propagate to client code, but want to use code from another sub module”. This can be fixed by adding a code comment, but I was thinking if it could be part of the Annotation somehow, so one can wrap a new annotation with it and then use that, thus not requiring to add the message everytime.

// Function doSomething uses API marked with ShinyNewAPI and is also
// required to opt in. Here, we choose a non-propagating opt-in, because the
// API is used in the function body and it should not concern our clients
@OptIn(ShinyNewAPI::class)
fun doSomething() {
    val foo = Foo()
    foo.bar()
}

Please follow more in thread.

[nisrulz]

Resources I have looked at already: Opt-in requirements | Kotlin (kotlinlang.org)

KEEP/experimental.md at master · Kotlin/KEEP (github.com)

…and I believe this is where I would add my comment to request for this enhancement: Opt-in requirements (aka Experimental API support) · Issue #95 · Kotlin/KEEP (github.com)

Although I want to validate it in slack before adding it there, no need to add extra noise there unless it makes sense.

[elizarov]

What’s wrong with just adding comment?

[nisrulz]

Nothing, I guess we can’t have any checks on it via the compiler like we do with RequireOptIn . Something like a warning that shows up when running from the terminal.

An example that comes to mind is highlighting usage of this annotation in code.

[elizarov]

You can have your custom annotation instead of comments if you use-case is to explain to the reader why such and such opt-in was written.

[nisrulz]

Can you give me some pointers how? Maybe that is what I want and I am not able to understand how?

Are you suggesting that I create a custom annotation and then parse it at compile time? Mostly confused with the direction here.

[elizarov]

Maybe I misunderstood your-use cases. You are asking for something that you can use internally (as opposed to getting a message to your clients) and I assume that that’s exactly what comments are designed to do.

[elizarov]

Now, if you want them to be searchable/highlightable in IDE, you can just attach any annotation as a way to comment it. This way, you’ll be able to quickly search your code for all functions annotated with a specific annotation.

[nisrulz]

Ok, I think you used better words than me. Apologies for not being clear.

I am trying to process the source code to
1. search/highlight in IDE
2. via terminal, also be able to flag those classes where certain code is used.
My AnnotationRetention would be set to SOURCE . So yes, still internal nothing going out to clients.

[nisrulz]

By terminal, I meant something like this.

[gildor]

I would just use OptIn for this, not sure how do you expect this to work if it not propagated

After all if some code is using OptIn it stop propagation of warning, so OptIn on your public API should be enough, isn’t it?

[nisrulz]

Yes, I was looking a way to highlight the usage of these instances as warnings, when team members use it in code as well as get more context with a message field in the OptIn annotation that describes why did they choose to Suppress the RequiresOptIn warning. Afterall they can just the say @ShinyNewAPI on that same class to stop the error/warning. However the usage of OptIn is used to suppress the warning from bubbling up to Clients. With no field for reason/message it just goes down to guess work/siloed knowledge with a team member.

I believe the best way for me to do it is add a specific kind of a comment, // REASON_FOR_OPTING_IN <messsage> and then run a bash command to grep for it in code, so I can highlight it part of my code base health check within AndroidStudio (using a gradle task that ingest output of this bash script) and on terminal/CI I can just run the bash script.

[nisrulz]

My usecase is internal to our teams, having a library that is multi module. We use @RequiresOptIn to reference classes that live in one module by other module, but these shouldn’t be used by our Clients of Library. So like an Internal Class, that is public but marked as @RequiresOptIn