Stabilize ExternalDocumentableProvider (#3312)

4 files changed, 63 insertions, 30 deletions

diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin.kt
index 1df1dfe6..5a70b3f2 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin.kt
@@ -4,6 +4,7 @@
 
 package org.jetbrains.dokka.analysis.kotlin
 
+import org.jetbrains.dokka.analysis.kotlin.documentable.ExternalDocumentableProvider
 import org.jetbrains.dokka.analysis.kotlin.sample.SampleAnalysisEnvironmentCreator
 import org.jetbrains.dokka.analysis.kotlin.sample.SampleAnalysisEnvironment
 import org.jetbrains.dokka.plugability.DokkaPlugin
@@ -20,6 +21,14 @@ public class KotlinAnalysisPlugin : DokkaPlugin() {
      */
     public val sampleAnalysisEnvironmentCreator: ExtensionPoint<SampleAnalysisEnvironmentCreator> by extensionPoint()
 
+    /**
+     * An extension that helps to find external documentables that are not provided by Dokka by default,
+     * such as documentables that come from external dependencies.
+     *
+     * @see ExternalDocumentableProvider for more details
+     */
+    public val externalDocumentableProvider: ExtensionPoint<ExternalDocumentableProvider> by extensionPoint()
+
     @OptIn(DokkaPluginApiPreview::class)
     override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = PluginApiPreviewAcknowledgement
 }
diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/documentable/ExternalDocumentableProvider.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/documentable/ExternalDocumentableProvider.kt
new file mode 100644
index 00000000..6e2c7b33
--- /dev/null
+++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/documentable/ExternalDocumentableProvider.kt
@@ -0,0 +1,54 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.analysis.kotlin.documentable
+
+import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.DClasslike
+import org.jetbrains.dokka.model.DClass
+import org.jetbrains.dokka.transformers.sources.SourceToDocumentableTranslator
+
+/**
+ * Helps find external documentables that are not provided by Dokka by default.
+ *
+ * By default, Dokka parses and makes available only documentables of the declarations found
+ * in the user project itself. Meaning, if the project's source code contains a `fun foo()`,
+ * it must be returned by [SourceToDocumentableTranslator]. However, if the user project
+ * depends on an external library which has a `fun bar()`, it will __not__ be available and
+ * documented out of the box.
+ *
+ * This provider helps you find documentables for the declarations that are present in
+ * [DokkaSourceSet.classpath] during runtime, but are not necessarily from the user project itself.
+ *
+ * For example, it can help you find a class that comes from a dependency, which can be useful
+ * if you want to get more information about a supertype of the project's class,
+ * because [DClass.supertypes] only provides the supertype's DRI, but not its full documentable.
+ *
+ * It is expected to work with all languages supported by the analysis implementation,
+ * meaning it should return Java classes if Java as an input language is supported.
+ *
+ * If you query DRIs of local project declarations (not external), it should generally work, although
+ * it's not guaranteed that the returned value will be 100% equal to that provided by Dokka by default.
+ *
+ * Note: because classpath entries consist of compiled code, the returned documentables may have some
+ * properties set to null or empty, because some information cannot be extracted from it in any way.
+ * One such example is KDocs, they are present in source code, but not in compiled classes.
+ */
+public interface ExternalDocumentableProvider {
+
+    /**
+     * Returns a valid and fully initialized [DClasslike] if the [dri] points to a class-like
+     * declaration (annotation, class, enum, interface, object) that can be found among
+     * [DokkaSourceSet.classpath] entries.
+     *
+     * If the [dri] points to a non-class-like declaration (like a function),
+     * or the declaration cannot be found, it returns `null`.
+     *
+     * Note: the implementation is not expected to cache results or return pre-computed values, so
+     * it may need to analyze parts of the project and instantiate new documentables on every invocation.
+     * Use this function sparingly, and cache results on your side if you need to.
+     */
+    public fun getClasslike(dri: DRI, sourceSet: DokkaSourceSet): DClasslike?
+}
diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/ExternalDocumentablesProvider.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/ExternalDocumentablesProvider.kt
deleted file mode 100644
index 7c564880..00000000
--- a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/ExternalDocumentablesProvider.kt
+++ /dev/null
@@ -1,28 +0,0 @@
-/*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-package org.jetbrains.dokka.analysis.kotlin.internal
-
-import org.jetbrains.dokka.DokkaConfiguration
-import org.jetbrains.dokka.InternalDokkaApi
-import org.jetbrains.dokka.links.DRI
-import org.jetbrains.dokka.model.DClasslike
-
-/**
- * Service that can be queried with [DRI] and source set to obtain a documentable for classlike.
- *
- * There are some cases when there is a need to process documentables of classlikes that were not defined
- * in the project itself but are somehow related to the symbols defined in the documented project (e.g. are supertypes
- * of classes defined in project).
- */
-@InternalDokkaApi
-public fun interface ExternalDocumentablesProvider {
-
-    /**
-     * Returns [DClasslike] matching provided [DRI] in specified source set.
-     *
-     * Result is null if compiler haven't generated matching class descriptor.
-     */
-    public fun findClasslike(dri: DRI, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike?
-}
diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt
index d032d490..dbf33c8e 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt
@@ -27,8 +27,6 @@ public class InternalKotlinAnalysisPlugin : DokkaPlugin() {
 
     public val inheritanceBuilder: ExtensionPoint<InheritanceBuilder> by extensionPoint()
 
-    public val externalDocumentablesProvider: ExtensionPoint<ExternalDocumentablesProvider> by extensionPoint()
-
     public val documentableSourceLanguageParser: ExtensionPoint<DocumentableSourceLanguageParser> by extensionPoint()
 
     @OptIn(DokkaPluginApiPreview::class)