diff options
Diffstat (limited to 'subprojects/analysis-kotlin-api')
12 files changed, 255 insertions, 0 deletions
diff --git a/subprojects/analysis-kotlin-api/README.md b/subprojects/analysis-kotlin-api/README.md new file mode 100644 index 00000000..5b03b297 --- /dev/null +++ b/subprojects/analysis-kotlin-api/README.md @@ -0,0 +1,10 @@ +# Analysis: Kotlin API + +Public API for interacting with Kotlin analysis, regardless of implementation. Contains no business logic. + +Can be used to request additional information about Kotlin declarations. + +Has to be used as a `compileOnly` dependency as Dokka bundles it by default in all runners. + +The actual implementation (K1/K2/etc) will be resolved and bootstrapped during runtime, so the +user must not think about it. diff --git a/subprojects/analysis-kotlin-api/api/analysis-kotlin-api.api b/subprojects/analysis-kotlin-api/api/analysis-kotlin-api.api new file mode 100644 index 00000000..74bd7da9 --- /dev/null +++ b/subprojects/analysis-kotlin-api/api/analysis-kotlin-api.api @@ -0,0 +1,70 @@ +public final class org/jetbrains/kotlin/analysis/kotlin/KotlinAnalysisPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { + public fun <init> ()V +} + +public final class org/jetbrains/kotlin/analysis/kotlin/internal/DocumentableLanguage : java/lang/Enum { + public static final field JAVA Lorg/jetbrains/kotlin/analysis/kotlin/internal/DocumentableLanguage; + public static final field KOTLIN Lorg/jetbrains/kotlin/analysis/kotlin/internal/DocumentableLanguage; + public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/kotlin/analysis/kotlin/internal/DocumentableLanguage; + public static fun values ()[Lorg/jetbrains/kotlin/analysis/kotlin/internal/DocumentableLanguage; +} + +public abstract interface class org/jetbrains/kotlin/analysis/kotlin/internal/DocumentableSourceLanguageParser { + public abstract fun getLanguage (Lorg/jetbrains/dokka/model/Documentable;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/kotlin/analysis/kotlin/internal/DocumentableLanguage; +} + +public abstract interface class org/jetbrains/kotlin/analysis/kotlin/internal/ExternalDocumentablesProvider { + public abstract fun findClasslike (Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; +} + +public abstract interface class org/jetbrains/kotlin/analysis/kotlin/internal/FullClassHierarchyBuilder { + public abstract fun build (Lorg/jetbrains/dokka/model/DModule;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; +} + +public abstract interface class org/jetbrains/kotlin/analysis/kotlin/internal/InheritanceBuilder { + public abstract fun build (Ljava/util/Map;)Ljava/util/List; +} + +public final class org/jetbrains/kotlin/analysis/kotlin/internal/InheritanceNode { + public fun <init> (Lorg/jetbrains/dokka/links/DRI;Ljava/util/List;Ljava/util/List;Z)V + public synthetic fun <init> (Lorg/jetbrains/dokka/links/DRI;Ljava/util/List;Ljava/util/List;ZILkotlin/jvm/internal/DefaultConstructorMarker;)V + public final fun component1 ()Lorg/jetbrains/dokka/links/DRI; + public final fun component2 ()Ljava/util/List; + public final fun component3 ()Ljava/util/List; + public final fun component4 ()Z + public final fun copy (Lorg/jetbrains/dokka/links/DRI;Ljava/util/List;Ljava/util/List;Z)Lorg/jetbrains/kotlin/analysis/kotlin/internal/InheritanceNode; + public static synthetic fun copy$default (Lorg/jetbrains/kotlin/analysis/kotlin/internal/InheritanceNode;Lorg/jetbrains/dokka/links/DRI;Ljava/util/List;Ljava/util/List;ZILjava/lang/Object;)Lorg/jetbrains/kotlin/analysis/kotlin/internal/InheritanceNode; + public fun equals (Ljava/lang/Object;)Z + public final fun getChildren ()Ljava/util/List; + public final fun getDri ()Lorg/jetbrains/dokka/links/DRI; + public final fun getInterfaces ()Ljava/util/List; + public fun hashCode ()I + public final fun isInterface ()Z + public fun toString ()Ljava/lang/String; +} + +public final class org/jetbrains/kotlin/analysis/kotlin/internal/InternalKotlinAnalysisPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { + public fun <init> ()V + public final fun getDocumentableSourceLanguageParser ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getExternalDocumentablesProvider ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getFullClassHierarchyBuilder ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getInheritanceBuilder ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getKotlinToJavaService ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getModuleAndPackageDocumentationReader ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getSyntheticDocumentableDetector ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; +} + +public abstract interface class org/jetbrains/kotlin/analysis/kotlin/internal/KotlinToJavaService { + public abstract fun findAsJava (Lorg/jetbrains/dokka/links/DRI;)Lorg/jetbrains/dokka/links/DRI; +} + +public abstract interface class org/jetbrains/kotlin/analysis/kotlin/internal/ModuleAndPackageDocumentationReader { + public abstract fun read (Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Lorg/jetbrains/dokka/model/doc/DocumentationNode; + public abstract fun read (Lorg/jetbrains/dokka/model/DModule;)Ljava/util/Map; + public abstract fun read (Lorg/jetbrains/dokka/model/DPackage;)Ljava/util/Map; +} + +public abstract interface class org/jetbrains/kotlin/analysis/kotlin/internal/SyntheticDocumentableDetector { + public abstract fun isSynthetic (Lorg/jetbrains/dokka/model/Documentable;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Z +} + diff --git a/subprojects/analysis-kotlin-api/build.gradle.kts b/subprojects/analysis-kotlin-api/build.gradle.kts new file mode 100644 index 00000000..3a10ff55 --- /dev/null +++ b/subprojects/analysis-kotlin-api/build.gradle.kts @@ -0,0 +1,14 @@ +import org.jetbrains.registerDokkaArtifactPublication + +plugins { + id("org.jetbrains.conventions.kotlin-jvm") + id("org.jetbrains.conventions.maven-publish") +} + +dependencies { + compileOnly(projects.core) +} + +registerDokkaArtifactPublication("analysisKotlinApi") { + artifactId = "analysis-kotlin-api" +} diff --git a/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/KotlinAnalysisPlugin.kt b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/KotlinAnalysisPlugin.kt new file mode 100644 index 00000000..3138e17b --- /dev/null +++ b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/KotlinAnalysisPlugin.kt @@ -0,0 +1,17 @@ +package org.jetbrains.kotlin.analysis.kotlin + +import org.jetbrains.dokka.plugability.DokkaPlugin +import org.jetbrains.dokka.plugability.DokkaPluginApiPreview +import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement + +class KotlinAnalysisPlugin : DokkaPlugin() { + + /* + * This is where stable public API will go. + * + * No stable public API for now. + */ + + @OptIn(DokkaPluginApiPreview::class) + override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = PluginApiPreviewAcknowledgement +} diff --git a/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/DocumentableSourceLanguageParser.kt b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/DocumentableSourceLanguageParser.kt new file mode 100644 index 00000000..08a465c0 --- /dev/null +++ b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/DocumentableSourceLanguageParser.kt @@ -0,0 +1,16 @@ +package org.jetbrains.kotlin.analysis.kotlin.internal + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.InternalDokkaApi +import org.jetbrains.dokka.model.Documentable +import org.jetbrains.dokka.model.WithSources + +@InternalDokkaApi +enum class DocumentableLanguage { + JAVA, KOTLIN +} + +@InternalDokkaApi +interface DocumentableSourceLanguageParser { + fun getLanguage(documentable: Documentable, sourceSet: DokkaConfiguration.DokkaSourceSet): DocumentableLanguage? +} diff --git a/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/ExternalDocumentablesProvider.kt b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/ExternalDocumentablesProvider.kt new file mode 100644 index 00000000..ea418fba --- /dev/null +++ b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/ExternalDocumentablesProvider.kt @@ -0,0 +1,24 @@ +package org.jetbrains.kotlin.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 +fun interface ExternalDocumentablesProvider { + + /** + * Returns [DClasslike] matching provided [DRI] in specified source set. + * + * Result is null if compiler haven't generated matching class descriptor. + */ + fun findClasslike(dri: DRI, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike? +} diff --git a/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/FullClassHierarchyBuilder.kt b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/FullClassHierarchyBuilder.kt new file mode 100644 index 00000000..91460002 --- /dev/null +++ b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/FullClassHierarchyBuilder.kt @@ -0,0 +1,17 @@ +package org.jetbrains.kotlin.analysis.kotlin.internal + +import org.jetbrains.dokka.InternalDokkaApi +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.DModule +import org.jetbrains.dokka.model.SourceSetDependent + +@InternalDokkaApi +typealias Supertypes = List<DRI> + +@InternalDokkaApi +typealias ClassHierarchy = SourceSetDependent<Map<DRI, Supertypes>> + +@InternalDokkaApi +interface FullClassHierarchyBuilder { + suspend fun build(module: DModule): ClassHierarchy +} diff --git a/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/InheritanceBuilder.kt b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/InheritanceBuilder.kt new file mode 100644 index 00000000..7f0313ea --- /dev/null +++ b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/InheritanceBuilder.kt @@ -0,0 +1,21 @@ +package org.jetbrains.kotlin.analysis.kotlin.internal + +import org.jetbrains.dokka.InternalDokkaApi +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.Documentable + +@InternalDokkaApi +interface InheritanceBuilder { + fun build(documentables: Map<DRI, Documentable>): List<InheritanceNode> +} + +@InternalDokkaApi +data class InheritanceNode( + val dri: DRI, + val children: List<InheritanceNode> = emptyList(), + val interfaces: List<DRI> = emptyList(), + val isInterface: Boolean = false +) { + override fun equals(other: Any?): Boolean = other is InheritanceNode && other.dri == dri + override fun hashCode(): Int = dri.hashCode() +} diff --git a/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt new file mode 100644 index 00000000..e2335474 --- /dev/null +++ b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt @@ -0,0 +1,31 @@ +package org.jetbrains.kotlin.analysis.kotlin.internal + +import org.jetbrains.dokka.InternalDokkaApi +import org.jetbrains.dokka.plugability.DokkaPlugin +import org.jetbrains.dokka.plugability.DokkaPluginApiPreview +import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement + +/** + * A plugin for internal use, has no stable public API and thus must not be used by third party, + * external plugins. If you need any of the given API stabilized, please create an issue describing your use case. + */ +@InternalDokkaApi +class InternalKotlinAnalysisPlugin : DokkaPlugin() { + + val fullClassHierarchyBuilder by extensionPoint<FullClassHierarchyBuilder>() + + val syntheticDocumentableDetector by extensionPoint<SyntheticDocumentableDetector>() + + val moduleAndPackageDocumentationReader by extensionPoint<ModuleAndPackageDocumentationReader>() + + val kotlinToJavaService by extensionPoint<KotlinToJavaService>() + + val inheritanceBuilder by extensionPoint<InheritanceBuilder>() + + val externalDocumentablesProvider by extensionPoint<ExternalDocumentablesProvider>() + + val documentableSourceLanguageParser by extensionPoint<DocumentableSourceLanguageParser>() + + @OptIn(DokkaPluginApiPreview::class) + override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = PluginApiPreviewAcknowledgement +} diff --git a/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/KotlinToJavaService.kt b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/KotlinToJavaService.kt new file mode 100644 index 00000000..3631fac2 --- /dev/null +++ b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/KotlinToJavaService.kt @@ -0,0 +1,9 @@ +package org.jetbrains.kotlin.analysis.kotlin.internal + +import org.jetbrains.dokka.InternalDokkaApi +import org.jetbrains.dokka.links.DRI + +@InternalDokkaApi +interface KotlinToJavaService { + fun findAsJava(kotlinDri: DRI): DRI? +} diff --git a/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/ModuleAndPackageDocumentationReader.kt b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/ModuleAndPackageDocumentationReader.kt new file mode 100644 index 00000000..6e641c3a --- /dev/null +++ b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/ModuleAndPackageDocumentationReader.kt @@ -0,0 +1,15 @@ +package org.jetbrains.kotlin.analysis.kotlin.internal + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.InternalDokkaApi +import org.jetbrains.dokka.model.DModule +import org.jetbrains.dokka.model.DPackage +import org.jetbrains.dokka.model.SourceSetDependent +import org.jetbrains.dokka.model.doc.DocumentationNode + +@InternalDokkaApi +interface ModuleAndPackageDocumentationReader { + fun read(module: DModule): SourceSetDependent<DocumentationNode> + fun read(pkg: DPackage): SourceSetDependent<DocumentationNode> + fun read(module: DokkaConfiguration.DokkaModuleDescription): DocumentationNode? +} diff --git a/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/SyntheticDocumentableDetector.kt b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/SyntheticDocumentableDetector.kt new file mode 100644 index 00000000..3dc8afa5 --- /dev/null +++ b/subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/kotlin/analysis/kotlin/internal/SyntheticDocumentableDetector.kt @@ -0,0 +1,11 @@ +package org.jetbrains.kotlin.analysis.kotlin.internal + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.InternalDokkaApi +import org.jetbrains.dokka.model.Documentable + +// TODO [beresnev] isSynthetic could be a property of Documentable +@InternalDokkaApi +interface SyntheticDocumentableDetector { + fun isSynthetic(documentable: Documentable, sourceSet: DokkaConfiguration.DokkaSourceSet): Boolean +} |