[K2] Fix sample resolving

[vmishenev]

No description provided.

[IgnatBeresnev]

Thanks for taking care of it! It thought it'd be more difficult for some reason

[IgnatBeresnev]

good idea to add a comment! nitpick: it explains the code below, but it doesn't explain the intention, which is the less obvious part :)

Suggested change

	// fallback to default roots of the source set even if sample roots are assigned
	// fallback to default roots of the source set even if sample roots are assigned,
	// because `@sample` tag can contain links to local project functions

[vmishenev]

Can you elaborate on what local project functions means? Why is it "local"? I did not understand.

[IgnatBeresnev]

I understood the problem and the fix the following way:

If you have the code like

/src/kotlin/com/example/MyFile.kt

/**
 * @sample bar
 */
fun foo() {
    
}

fun bar() {}

where @sample references a function declared in the project sources itself, like literally the function below it, we need to use projectKotlinAnalysis. This is what I meant by a "local" function.

And if you store sample functions outside of the project sources, like in a separate directory somewhere, and you configure it using DokkaSourceSet#samples, then it needs to use samplesKotlinAnalysis. I'd consider this "external"

The problem was that it was always using samplesKotlinAnalysis, which pointed to external sample functions, but it needs to resolve "local" project functions as well

If I got the idea and the fix correctly, you can use whatever words you find more suitable, that was just a suggestion :) But I might've misunderstood it, in which case it definitely needs some sort of a comment :)

[vmishenev]

I have changed a little to avoid a "local" function.

// because `@sample` tag can contain links to functions from project sources

[IgnatBeresnev]

Calling listOfNotNull to then do list.firstNotNullOfOrNull seems excessive in this case, and could be avoided like so

    private fun findPsiElement(sourceSet: DokkaSourceSet, fqLink: String): PsiElement? {
        // fallback to default roots of the source set even if sample roots are assigned,
        // because `@sample` tag can contain links to local project functions
        return samplesKotlinAnalysis.findPsiElement(sourceSet, fqLink)
            ?: projectKotlinAnalysis.findPsiElement(sourceSet, fqLink)
    }

    private fun KotlinAnalysis.findPsiElement(sourceSet: DokkaSourceSet, fqLink: String): PsiElement? {
        val ktSourceModule = this.getModuleOrNull(sourceSet) ?: return null
        return analyze(ktSourceModule) {
            resolveKDocTextLinkSymbol(fqLink)
                ?.kotlinAndJavaSourcePsiSafe()
        }
    }