Kotlin / dokka

API documentation engine for Kotlin
https://kotl.in/dokka
Apache License 2.0
3.42k stars 405 forks source link

Samples are rendered only with fqn reference #2656

Closed atyrin closed 2 years ago

atyrin commented 2 years ago
  1. Create a function containing a sample in a non-root package
    
    package org.jetbrains.qa.kdoc.rendering

fun sample() { val x = 100 println(x + 100) }

2. Reference the sample from a KDoc (the functions in the same package, so the function is resolved)
```Kotlin
package org.jetbrains.qa.kdoc.rendering

/**
 * Function with sample.
 * @see [sample]
 * @sample [sample]
 */
fun withSample(a: Int): Int{
    return a + 1
}

/**
 * Function with sample
 * @see [org.jetbrains.qa.kdoc.rendering.sample]
 * @sample [org.jetbrains.qa.kdoc.rendering.sample]
 */
fun withSampleFqdn(a: Int): Int{
    return a + 1
}
  1. Render the dokka

For the first function the sample is not rendered (that's the issue)

image

For the second with fqn everything is fine:

image

For the @see param the same scenario works fine

2032 might be relevant

vmishenev commented 2 years ago

The behaviour corresponds to KDoc specification for @sample. It is complicated to find a needed scope since sample sources should be taken from a detached folder by design.