I want to use `@sample` to reference some example ...

# dokka

[Justin (Midas) Gilman]

I want to use @sample to reference some example code and I cannot get it to work. I'm looking at https://github.com/JetBrains/kotlin/blob/bd4d8479430a3ebda030ce4856886e9985cacd75/libraries/stdlib/src/kotlin/collections/Iterators.kt#L8 as an example but I can't figure out how to make it work.

[PabloCasia]

You need to add samples dir (or a list of files) to dokka task config

tasks.withType<DokkaTask> {
    dokkaSourceSets {
        register("main") {
            samples  = listOf("$projectDir/src/sample")
        }
    }
}

Then add a sample to that dir, for example:

internal class SomeSample {
    fun someFunction() {
        val a = 5
    }
}

And use it in your code doc:

public object SomeObject {
    /**
     * Some doc.
     *
     * @sample your.package.SomeSample.someFunction
     */
    public fun someFunction() {
        ...
    }
}

You will see val a = 5 in dokka sample output

[Ignat Beresnev]

This should also work starting from 1.6.10 (without any extra configuration):

package <http://org.jetbrains.qa|org.jetbrains.qa>

/**
 * Hello, Sample
 * @sample org.jetbrains.qa.runSample
 */
fun withSample(a: Int): Int{
    return a + 1
}

fun runSample(){
    withSample(41)
}

[Justin (Midas) Gilman]

This worked! Thanks so much! I spent like 4 hours yesterday trying out configurations

[Ignat Beresnev]

I can relate :)) Also tried to find a way myself for an hour before stumbling upon this in an issues. We'll update the documentation to make it more clear