Enhance logging for unresolved KDoc links

Print location in an IDE-recognizable format

Author: vmishenev

dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/kdoc/KDocProvider.kt

@@ -7,6 +7,7 @@ package org.jetbrains.dokka.analysis.kotlin.symbols.kdoc
 import com.intellij.psi.PsiNamedElement
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.analysis.java.parsers.JavadocParser
+import org.jetbrains.dokka.analysis.kotlin.symbols.utils.getLocation
 import org.jetbrains.dokka.model.doc.DocumentationNode
 import org.jetbrains.dokka.utilities.DokkaLogger
 import org.jetbrains.kotlin.analysis.api.KaNonPublicApi
@@ -62,7 +63,7 @@ internal fun KaSession.getKDocDocumentationFrom(
 
     parseFromKDocTag(
         kDocTag = kDocContent.primaryTag,
-        externalDri = { resolveKDocLink(it, kdocLocation, logger, sourceSet) },
+        externalDri = { resolveKDocLink(it, getLocation(it) ?: kdocLocation, logger, sourceSet) },
         kdocLocation = kdocLocation
     )
 }

dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/kdoc/java/KotlinDocCommentParser.kt

@@ -11,6 +11,7 @@ import org.jetbrains.dokka.analysis.java.parsers.DocCommentParser
 import org.jetbrains.dokka.analysis.kotlin.symbols.kdoc.parseFromKDocTag
 import org.jetbrains.dokka.analysis.kotlin.symbols.kdoc.resolveKDocLink
 import org.jetbrains.dokka.analysis.kotlin.symbols.plugin.SymbolsAnalysisPlugin
+import org.jetbrains.dokka.analysis.kotlin.symbols.utils.getLocation
 import org.jetbrains.dokka.model.doc.DocumentationNode
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.plugin
@@ -40,7 +41,7 @@ internal class KotlinDocCommentParser(
         return analyze(kotlinAnalysis.getModule(sourceSet)) {
             parseFromKDocTag(
                 kDocTag = element.comment,
-                externalDri = { resolveKDocLink(it, elementName, context.logger, sourceSet) },
+                externalDri = { resolveKDocLink(it, getLocation(it) ?: elementName, context.logger, sourceSet) },
                 kdocLocation = null,
                 parseWithChildren = parseWithChildren
             )

dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/TranslatorError.kt

@@ -16,18 +16,22 @@ internal inline fun <R> KaSession.withExceptionCatcher(symbol: KaSymbol, action:
     } catch (e: TranslatorError) {
         throw e
     } catch (e: Throwable) {
-        val file = try {
+        val filePath = try {
             symbol.psi?.containingFile?.virtualFile?.path
         } catch (e: Throwable) {
             "[$e]"
         }
-        val textRange = try {
-            symbol.psi?.textRange.toString()
+        val lineSuffix = try {
+            val offset = symbol.psi?.textOffset
+            val fileDocument = symbol.psi?.containingFile?.fileDocument
+            val lineNumber = offset?.let { fileDocument?.getLineNumber(it) }
+            if (lineNumber != null) ":${lineNumber + 1}"
+            else ""
         } catch (e: Throwable) {
             "[$e]"
         }
         throw TranslatorError(
-            "Error in translating of symbol (${(symbol as? KaNamedSymbol)?.name}) $symbol in file: $file, $textRange",
+            "Error in translating of symbol (${(symbol as? KaNamedSymbol)?.name}) $symbol in file:///$filePath$lineSuffix",
             e
         )
     }

dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/utils/getURILocation.kt

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2014-2026 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.analysis.kotlin.symbols.utils
+
+import com.intellij.psi.PsiElement
+
+/**
+ * @return a string in the format `file://file.kt:<line>:<column>`,
+ * or `null` if [psiElement] is not from a source file
+ */
+internal fun getLocation(psiElement: PsiElement): String? {
+    val filePath = psiElement.containingFile?.virtualFile?.path ?: return null
+    val offset = psiElement.textOffset
+    val fileDocument = psiElement.containingFile?.fileDocument
+    val lineNumber = fileDocument?.getLineNumber(offset)
+
+    return if (lineNumber != null) {
+        val column =  offset - fileDocument.getLineStartOffset(lineNumber)
+        "file:///$filePath:${lineNumber + 1}:${column + 1}"
+    } else
+        "file:///$filePath"
+}

dokka-subprojects/plugin-base/src/test/kotlin/markdown/LinkTest.kt

@@ -1730,6 +1730,32 @@ class LinkTest : BaseAbstractTest() {
         }
     }
 
+    @Test
+    fun `should warn about unresolved links`() {
+        testInline(
+            """
+            |/src/main/kotlin/Testing.kt
+            |
+            |/**
+            |* [property] is unresolved
+            | */
+            |fun usage() = 0
+            |}
+        """.trimMargin(),
+            configuration
+        ) {
+            documentablesMergingStage = { m ->
+                val warn = logger.warnMessages.first()
+                val path = m.sourceSets.first().sourceRoots.first().path
+
+                assertEquals(
+                    "Couldn't resolve link: [property] in file:///PATH/main/kotlin/Testing.kt:2:3 (root/main)",
+                    warn.replace(path, "PATH")
+                )
+            }
+        }
+    }
+
     private fun DModule.getLinkDRIFrom(name: String): DRI? {
         val doc = this.dfs { it.name == name }?.documentation?.values?.single()
             ?: throw IllegalStateException("Can't find documentation for declaration '$name'")