diff options
Diffstat (limited to 'dokka-subprojects/analysis-kotlin-api')
51 files changed, 2650 insertions, 0 deletions
diff --git a/dokka-subprojects/analysis-kotlin-api/README.md b/dokka-subprojects/analysis-kotlin-api/README.md new file mode 100644 index 00000000..5b03b297 --- /dev/null +++ b/dokka-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/dokka-subprojects/analysis-kotlin-api/api/analysis-kotlin-api.api b/dokka-subprojects/analysis-kotlin-api/api/analysis-kotlin-api.api new file mode 100644 index 00000000..c65dfe5a --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/api/analysis-kotlin-api.api @@ -0,0 +1,85 @@ +public final class org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { + public fun <init> ()V +} + +public final class org/jetbrains/dokka/analysis/kotlin/internal/DocumentableLanguage : java/lang/Enum { + public static final field JAVA Lorg/jetbrains/dokka/analysis/kotlin/internal/DocumentableLanguage; + public static final field KOTLIN Lorg/jetbrains/dokka/analysis/kotlin/internal/DocumentableLanguage; + public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/dokka/analysis/kotlin/internal/DocumentableLanguage; + public static fun values ()[Lorg/jetbrains/dokka/analysis/kotlin/internal/DocumentableLanguage; +} + +public abstract interface class org/jetbrains/dokka/analysis/kotlin/internal/DocumentableSourceLanguageParser { + public abstract fun getLanguage (Lorg/jetbrains/dokka/model/Documentable;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/analysis/kotlin/internal/DocumentableLanguage; +} + +public abstract interface class org/jetbrains/dokka/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/dokka/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/dokka/analysis/kotlin/internal/InheritanceBuilder { + public abstract fun build (Ljava/util/Map;)Ljava/util/List; +} + +public final class org/jetbrains/dokka/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/dokka/analysis/kotlin/internal/InheritanceNode; + public static synthetic fun copy$default (Lorg/jetbrains/dokka/analysis/kotlin/internal/InheritanceNode;Lorg/jetbrains/dokka/links/DRI;Ljava/util/List;Ljava/util/List;ZILjava/lang/Object;)Lorg/jetbrains/dokka/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/dokka/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 getSampleProviderFactory ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getSyntheticDocumentableDetector ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; +} + +public abstract interface class org/jetbrains/dokka/analysis/kotlin/internal/KotlinToJavaService { + public abstract fun findAsJava (Lorg/jetbrains/dokka/links/DRI;)Lorg/jetbrains/dokka/links/DRI; +} + +public abstract interface class org/jetbrains/dokka/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/dokka/analysis/kotlin/internal/SampleProvider : java/lang/AutoCloseable { + public abstract fun getSample (Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Ljava/lang/String;)Lorg/jetbrains/dokka/analysis/kotlin/internal/SampleProvider$SampleSnippet; +} + +public final class org/jetbrains/dokka/analysis/kotlin/internal/SampleProvider$SampleSnippet { + public fun <init> (Ljava/lang/String;Ljava/lang/String;)V + public final fun getBody ()Ljava/lang/String; + public final fun getImports ()Ljava/lang/String; +} + +public abstract interface class org/jetbrains/dokka/analysis/kotlin/internal/SampleProviderFactory { + public abstract fun build ()Lorg/jetbrains/dokka/analysis/kotlin/internal/SampleProvider; +} + +public abstract interface class org/jetbrains/dokka/analysis/kotlin/internal/SyntheticDocumentableDetector { + public abstract fun isSynthetic (Lorg/jetbrains/dokka/model/Documentable;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Z +} + diff --git a/dokka-subprojects/analysis-kotlin-api/build.gradle.kts b/dokka-subprojects/analysis-kotlin-api/build.gradle.kts new file mode 100644 index 00000000..7e834e1c --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/build.gradle.kts @@ -0,0 +1,36 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +import dokkabuild.overridePublicationArtifactId + +plugins { + id("dokkabuild.kotlin-jvm") + id("dokkabuild.publish-jvm") + `java-test-fixtures` +} + +overridePublicationArtifactId("analysis-kotlin-api") + +dependencies { + compileOnly(projects.dokkaSubprojects.dokkaCore) + + testFixturesApi(projects.dokkaSubprojects.dokkaCore) + + testImplementation(kotlin("test")) + testImplementation(projects.dokkaSubprojects.analysisKotlinDescriptors) +} + +disableTestFixturesPublishing() + +/** + * Test fixtures are automatically published by default, which at this moment in time is unwanted + * as the test api is unstable and is internal to the Dokka project, so it shouldn't be used outside of it. + * + * @see https://docs.gradle.org/current/userguide/java_testing.html#ex-disable-publishing-of-test-fixtures-variants + */ +fun disableTestFixturesPublishing() { + val javaComponent = components["java"] as AdhocComponentWithVariants + javaComponent.withVariantsFromConfiguration(configurations["testFixturesApiElements"]) { skip() } + javaComponent.withVariantsFromConfiguration(configurations["testFixturesRuntimeElements"]) { skip() } +} 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 new file mode 100644 index 00000000..7d434bd5 --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin.kt @@ -0,0 +1,21 @@ +/* + * 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 + +import org.jetbrains.dokka.plugability.DokkaPlugin +import org.jetbrains.dokka.plugability.DokkaPluginApiPreview +import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement + +public 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/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/DocumentableSourceLanguageParser.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/DocumentableSourceLanguageParser.kt new file mode 100644 index 00000000..116adb06 --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/DocumentableSourceLanguageParser.kt @@ -0,0 +1,20 @@ +/* + * 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.model.Documentable +import org.jetbrains.dokka.model.WithSources + +@InternalDokkaApi +public enum class DocumentableLanguage { + JAVA, KOTLIN +} + +@InternalDokkaApi +public interface DocumentableSourceLanguageParser { + public fun getLanguage(documentable: Documentable, sourceSet: DokkaConfiguration.DokkaSourceSet): DocumentableLanguage? +} 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 new file mode 100644 index 00000000..7c564880 --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/ExternalDocumentablesProvider.kt @@ -0,0 +1,28 @@ +/* + * 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/FullClassHierarchyBuilder.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/FullClassHierarchyBuilder.kt new file mode 100644 index 00000000..5b975fd8 --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/FullClassHierarchyBuilder.kt @@ -0,0 +1,21 @@ +/* + * 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.InternalDokkaApi +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.DModule +import org.jetbrains.dokka.model.SourceSetDependent + +@InternalDokkaApi +public typealias Supertypes = List<DRI> + +@InternalDokkaApi +public typealias ClassHierarchy = SourceSetDependent<Map<DRI, Supertypes>> + +@InternalDokkaApi +public interface FullClassHierarchyBuilder { + public suspend fun build(module: DModule): ClassHierarchy +} diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InheritanceBuilder.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InheritanceBuilder.kt new file mode 100644 index 00000000..32077cde --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InheritanceBuilder.kt @@ -0,0 +1,25 @@ +/* + * 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.InternalDokkaApi +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.Documentable + +@InternalDokkaApi +public interface InheritanceBuilder { + public fun build(documentables: Map<DRI, Documentable>): List<InheritanceNode> +} + +@InternalDokkaApi +public 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/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 new file mode 100644 index 00000000..0ef1399a --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt @@ -0,0 +1,38 @@ +/* + * 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.InternalDokkaApi +import org.jetbrains.dokka.plugability.DokkaPlugin +import org.jetbrains.dokka.plugability.DokkaPluginApiPreview +import org.jetbrains.dokka.plugability.ExtensionPoint +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 +public class InternalKotlinAnalysisPlugin : DokkaPlugin() { + + public val fullClassHierarchyBuilder: ExtensionPoint<FullClassHierarchyBuilder> by extensionPoint() + + public val syntheticDocumentableDetector: ExtensionPoint<SyntheticDocumentableDetector> by extensionPoint() + + public val moduleAndPackageDocumentationReader: ExtensionPoint<ModuleAndPackageDocumentationReader> by extensionPoint() + + public val kotlinToJavaService: ExtensionPoint<KotlinToJavaService> by extensionPoint() + + public val inheritanceBuilder: ExtensionPoint<InheritanceBuilder> by extensionPoint() + + public val externalDocumentablesProvider: ExtensionPoint<ExternalDocumentablesProvider> by extensionPoint() + + public val documentableSourceLanguageParser: ExtensionPoint<DocumentableSourceLanguageParser> by extensionPoint() + + public val sampleProviderFactory: ExtensionPoint<SampleProviderFactory> 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/internal/KotlinToJavaService.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/KotlinToJavaService.kt new file mode 100644 index 00000000..1ce47031 --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/KotlinToJavaService.kt @@ -0,0 +1,29 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package |