Before you read the question: I understand what

@DslMarker

means. Can anyone please clarify what

@DslMarker

annotation on a function means? The official documentation (see https://kotlinlang.org/docs/type-safe-builders.html#scope-control-dslmarker, https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-dsl-marker/) describes that the annotations affect classes, interfaces, and lambdas only. The documentation provides no clue on the meaning of

@DslMarker fun html(...) {

In practice, both

kotlinx-html

and

ktor

annotate their DSL functions with the corresponding DslMarker annotation: https://github.com/Kotlin/kotlinx.html/blob/24ef7f418687ce4241ec111f757b09e8b4f5bf79/src/commonMain/kotlin/generated/gen-tags-p.kt#L49-L50 Here's an example:

@HtmlTagMarker
inline fun PICTURE.img(alt : String? = null, src : String? = null, classes : String? = null, crossinline block : IMG.() -> Unit = {}) : Unit =
    IMG(attributesMapOf("alt", alt,"src", src,"class", classes), consumer).visit(block)

Of course, their

Tag

interface is annotated (

PICTURE

and

IMG

implement that interface):

@HtmlTagMarker
interface Tag {

However, my question is what does annotation on function mean? As a side-effect, I noticed that IDEA 2021.2.3 removes italic style from extension functions that have

@DslMarker

annotation. Is it a valid hack? Should it be documented somehow?

good question, i have been wondering this