Is there any guide explaining how to properly use @DslMarker annotations?

# stdlib

[Big Chungus]

Is there any guide explaining how to properly use @DslMarker annotations?

[CLOVIS]

Is there an improper way to use it?

[Big Chungus]

Somehow I've managed 😀 For instance, annotating non-extension member method does not prevent scope leakage. All it does is just colour the method calls in IDE.

[CLOVIS]

Did you create your own annotation? You're not supposed to use @DslMarker directly, but apart from that I'm not aware of anything 😕

[Big Chungus]

e.g.

@MyDslMarker
fun action(block: Action<DomainClass>)

[Big Chungus]

I did create my own annotation. The above can be fixed by annotating DomainClass directly but I might not always have access to modify that.

[CLOVIS]

The doc seems to say marking methods is not supported: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-dsl-marker/

[CLOVIS]

it says it applies to types directly

[Big Chungus]

What do docs mean by "type's classifier" there?

[CLOVIS]

I would assume this: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.reflect/-k-type/classifier.html

[CLOVIS]

Not sure though

[CLOVIS]

I think you have to annotate the receiver type though, not the methods called on it

[Big Chungus]

Yeah that works, but what if the receiver type is external? Would something like this work?

fun action (block: Action<@MyDslMarker ExternalType>)

[CLOVIS]

I don't know, maybe that's the reason you can annotate classifiers? This seems to say you can annotate typealiases: https://discuss.kotlinlang.org/t/status-of-annotations-on-typealias-supported/5586/3

[CLOVIS]

Have not tried it though

[CLOVIS]

I don't think the @DslMarker behavior is local to a function anyway, if you manage to annotate the type it will probably affect all code. It seems a bit dangerous to me to be able to annotate external classes

[Big Chungus]

Assuming all your dsl types are always internal is a bit naive if you ask me.

[CLOVIS]

True, but I also wouldn't want a library I'm depending on to suddenly change the behavior of classes from another library

[Big Chungus]

It won't and it cannot since it has no way to modify those types. The annotations can only ve applied inside dsl method scope so the behaviour only changes there

[CLOVIS]

Can it really be applied in function argument? I don't think I've ever seen it applied to anything other than a type

[Big Chungus]

i.e. annotating external type argument does not affect that type usages outside of method scope

[Big Chungus]

I have no idea if it can. I'm just arguing for a potential usecase 😀