diff options
author | Błażej Kardyś <bkardys@virtuslab.com> | 2020-10-06 04:54:31 +0200 |
---|---|---|
committer | Błażej Kardyś <bkardys@virtuslab.com> | 2020-11-12 11:44:32 +0100 |
commit | 7db15c357a417ccd9ff8ad1f90f5aff84eec132f (patch) | |
tree | 92e048e9986300eda0d1f2eeaef1aea424d79a30 /plugins | |
parent | 07e43676665bdc009e135b767e6d43c536b413fa (diff) | |
download | dokka-7db15c357a417ccd9ff8ad1f90f5aff84eec132f.tar.gz dokka-7db15c357a417ccd9ff8ad1f90f5aff84eec132f.tar.bz2 dokka-7db15c357a417ccd9ff8ad1f90f5aff84eec132f.zip |
Adding function division switch
Diffstat (limited to 'plugins')
11 files changed, 197 insertions, 36 deletions
diff --git a/plugins/base/src/main/kotlin/DokkaBaseConfiguration.kt b/plugins/base/src/main/kotlin/DokkaBaseConfiguration.kt index c18b3446..5b93c209 100644 --- a/plugins/base/src/main/kotlin/DokkaBaseConfiguration.kt +++ b/plugins/base/src/main/kotlin/DokkaBaseConfiguration.kt @@ -5,10 +5,12 @@ import java.io.File data class DokkaBaseConfiguration( var customStyleSheets: List<File> = defaultCustomStyleSheets, - var customAssets: List<File> = defaultCustomAssets + var customAssets: List<File> = defaultCustomAssets, + var separateInheritedMembers: Boolean = separateInheritedMembersDefault ): ConfigurableBlock { companion object { val defaultCustomStyleSheets: List<File> = emptyList() val defaultCustomAssets: List<File> = emptyList() + const val separateInheritedMembersDefault: Boolean = false } }
\ No newline at end of file diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt index f388ee44..4695dac5 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt @@ -405,6 +405,7 @@ private class DokkaDescriptorVisitor( ): DProperty { val dri = parent.dri.copy(callable = Callable.from(originalDescriptor)) val descriptor = originalDescriptor.getConcreteDescriptor() + val inheritedFrom = descriptor.createDRI().let { (originalDri, _) -> originalDri.takeIf { it != dri } } val isExpect = descriptor.isExpect val isActual = descriptor.isActual @@ -438,7 +439,8 @@ private class DokkaDescriptorVisitor( (descriptor.additionalExtras() + descriptor.getAnnotationsWithBackingField() .toAdditionalExtras()).toSet().toSourceSetDependent().toAdditionalModifiers(), descriptor.getAnnotationsWithBackingField().toSourceSetDependent().toAnnotations(), - descriptor.getDefaultValue()?.let { DefaultValue(it) } + descriptor.getDefaultValue()?.let { DefaultValue(it) }, + InheritedMember(inheritedFrom.toSourceSetDependent()), )) ) } @@ -484,7 +486,7 @@ private class DokkaDescriptorVisitor( sourceSets = setOf(sourceSet), isExpectActual = (isExpect || isActual), extra = PropertyContainer.withAll( - InheritedFunction(inheritedFrom.toSourceSetDependent()), + InheritedMember(inheritedFrom.toSourceSetDependent()), descriptor.additionalExtras().toSourceSetDependent().toAdditionalModifiers(), descriptor.getAnnotations().toSourceSetDependent().toAnnotations() ) diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt index 2aa3e2dc..18647207 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt @@ -1,8 +1,10 @@ package org.jetbrains.dokka.base.translators.documentables import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.DokkaBaseConfiguration import org.jetbrains.dokka.model.DModule import org.jetbrains.dokka.pages.ModulePageNode +import org.jetbrains.dokka.plugability.configuration import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.plugin import org.jetbrains.dokka.plugability.querySingle @@ -11,10 +13,11 @@ import org.jetbrains.dokka.transformers.documentation.DocumentableToPageTranslat class DefaultDocumentableToPageTranslator( context: DokkaContext ) : DocumentableToPageTranslator { + private val configuration = configuration<DokkaBase, DokkaBaseConfiguration>(context) private val commentsToContentConverter = context.plugin<DokkaBase>().querySingle { commentsToContentConverter } private val signatureProvider = context.plugin<DokkaBase>().querySingle { signatureProvider } private val logger = context.logger override fun invoke(module: DModule): ModulePageNode = - DefaultPageCreator(commentsToContentConverter, signatureProvider, logger).pageForModule(module) + DefaultPageCreator(configuration, commentsToContentConverter, signatureProvider, logger).pageForModule(module) }
\ No newline at end of file diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index e0ced0aa..355eff16 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -16,6 +16,7 @@ import org.jetbrains.kotlin.utils.addToStdlib.safeAs import kotlin.reflect.KClass import kotlin.reflect.full.isSubclassOf import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet +import org.jetbrains.dokka.base.DokkaBaseConfiguration import org.jetbrains.dokka.base.resolvers.anchors.SymbolAnchorHint import org.jetbrains.dokka.base.transformers.documentables.ClashingDriIdentifier @@ -25,12 +26,15 @@ private val specialTags: Set<KClass<out TagWrapper>> = setOf(Property::class, Description::class, Constructor::class, Receiver::class, Param::class, See::class) open class DefaultPageCreator( + configuration: DokkaBaseConfiguration?, commentsToContentConverter: CommentsToContentConverter, signatureProvider: SignatureProvider, val logger: DokkaLogger ) { protected open val contentBuilder = PageContentBuilder(commentsToContentConverter, signatureProvider, logger) + protected val separateInheritedMembers = configuration?.separateInheritedMembers ?: DokkaBaseConfiguration.separateInheritedMembersDefault + open fun pageForModule(m: DModule) = ModulePageNode(m.name.ifEmpty { "<root>" }, contentForModule(m), m, m.packages.map(::pageForPackage)) @@ -56,7 +60,7 @@ open class DefaultPageCreator( constructors.map(::pageForFunction) + c.classlikes.renameClashingDocumentable().map(::pageForClasslike) + c.filteredFunctions.renameClashingDocumentable().map(::pageForFunction) + - c.properties.renameClashingDocumentable().mapNotNull(::pageForProperty) + + c.filteredProperties.renameClashingDocumentable().mapNotNull(::pageForProperty) + if (c is DEnum) c.entries.map(::pageForEnumEntry) else emptyList() ) @@ -86,12 +90,17 @@ open class DefaultPageCreator( open fun pageForProperty(p: DProperty): MemberPageNode? = MemberPageNode(p.nameAfterClash(), contentForProperty(p), setOf(p.dri), p) + private fun <T> T.isInherited(): Boolean where T: Documentable, T: WithExtraProperties<T> = + sourceSets.all { sourceSet -> extra[InheritedMember]?.isInherited(sourceSet) == true } + private val WithScope.filteredFunctions: List<DFunction> - get() = functions.mapNotNull { function -> - function.takeIf { - it.sourceSets.any { sourceSet -> it.extra[InheritedFunction]?.isInherited(sourceSet) != true } - } - } + get() = functions.filterNot { it.isInherited() } + + private val WithScope.filteredProperties: List<DProperty> + get() = properties.filterNot { it.isInherited() } + + private fun <T> Collection<T>.splitInherited(): Pair<List<T>, List<T>> where T: Documentable, T: WithExtraProperties<T> = + partition { it.isInherited() } protected open fun contentForModule(m: DModule) = contentBuilder.contentFor(m) { group(kind = ContentKind.Cover) { @@ -153,26 +162,16 @@ open class DefaultPageCreator( (s as? DPackage)?.typealiases ?: emptyList() ).flatten() divergentBlock("Types", types, ContentKind.Classlikes, extra = mainExtra + SimpleAttr.header("Types")) - divergentBlock( - "Functions", - s.functions.sorted(), - ContentKind.Functions, - extra = mainExtra + SimpleAttr.header("Functions") - ) - block( - "Properties", - 2, - ContentKind.Properties, - s.properties, - sourceSets.toSet(), - needsAnchors = true, - extra = mainExtra + SimpleAttr.header("Properties") - ) { - link(it.name, it.dri, kind = ContentKind.Main) - sourceSetDependentHint(it.dri, it.sourceSets.toSet(), kind = ContentKind.SourceSetDependentHint, extra = PropertyContainer.empty()) { - +buildSignature(it) - contentForBrief(it) - } + if (separateInheritedMembers) { + val (inheritedFunctions, memberFunctions) = s.functions.splitInherited() + val (inheritedProperties, memberProperties) = s.properties.splitInherited() + propertiesBlock("Properties", memberProperties, sourceSets) + propertiesBlock("Inherited properties", inheritedProperties, sourceSets) + functionsBlock("Functions", memberFunctions) + functionsBlock("Inherited functions", inheritedFunctions) + } else { + functionsBlock("Functions", s.functions) + propertiesBlock("Properties", s.properties, sourceSets) } s.safeAs<WithExtraProperties<Documentable>>()?.let { it.extra[InheritorsInfo] }?.let { inheritors -> val map = inheritors.value.filter { it.value.isNotEmpty() } @@ -537,6 +536,30 @@ open class DefaultPageCreator( } } + private fun DocumentableContentBuilder.functionsBlock(name: String, list: Collection<DFunction>) = divergentBlock( + name, + list.sorted(), + ContentKind.Functions, + extra = mainExtra + SimpleAttr.header(name) + ) + private fun DocumentableContentBuilder.propertiesBlock(name: String, list: Collection<DProperty>, sourceSets: Set<DokkaSourceSet>) { + block( + name, + 2, + ContentKind.Properties, + list, + sourceSets, + needsAnchors = true, + extra = mainExtra + SimpleAttr.header(name) + ) { + link(it.name, it.dri, kind = ContentKind.Main) + sourceSetDependentHint(it.dri, it.sourceSets.toSet(), kind = ContentKind.SourceSetDependentHint) { + +buildSignature(it) + contentForBrief(it) + } + } + } + protected open fun DocumentableContentBuilder.divergentBlock( name: String, collection: Collection<Documentable>, diff --git a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt index 00fab531..1f52f373 100644 --- a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt @@ -367,7 +367,7 @@ class DefaultPsiToDocumentableTranslator( false, psi.additionalExtras().let { PropertyContainer.withAll( - InheritedFunction(inheritedFrom.toSourceSetDependent()), + InheritedMember(inheritedFrom.toSourceSetDependent()), it.toSourceSetDependent().toAdditionalModifiers(), (psi.annotations.toList() .toListOfAnnotations() + it.toListOfAnnotations()).toSourceSetDependent() diff --git a/plugins/base/src/test/kotlin/transformers/DivisionSwitchTest.kt b/plugins/base/src/test/kotlin/transformers/DivisionSwitchTest.kt new file mode 100644 index 00000000..58413074 --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/DivisionSwitchTest.kt @@ -0,0 +1,122 @@ +package transformers + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.PluginConfigurationImpl +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.model.dfs +import org.jetbrains.dokka.pages.ClasslikePageNode +import org.jetbrains.dokka.pages.ContentHeader +import org.jetbrains.dokka.pages.ContentNode +import org.jetbrains.dokka.pages.ContentText +import org.jetbrains.dokka.testApi.testRunner.AbstractCoreTest +import org.jetbrains.kotlin.utils.addIfNotNull +import org.junit.jupiter.api.Test +import kotlin.test.assertEquals +import kotlin.test.assertNotNull + +class DivisionSwitchTest : AbstractCoreTest() { + + private val query = """ + |/src/source0.kt + package package0 + /** + * Documentation for ClassA + */ + class ClassA { + val A: String = "A" + fun a() {} + fun b() {} + } + + /src/source1.kt + package package0 + /** + * Documentation for ClassB + */ + class ClassB : ClassA() { + val B: String = "B" + fun d() {} + fun e() {} + } + """.trimMargin() + + private fun configuration(switchOn: Boolean) = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src/") + } + } + pluginsConfigurations.addIfNotNull( + PluginConfigurationImpl( + DokkaBase::class.qualifiedName!!, + DokkaConfiguration.SerializationFormat.JSON, + """{ "separateInheritedMembers": $switchOn }""", + ) + ) + } + + private fun testClassB(switchOn: Boolean, operation: (ClasslikePageNode) -> Unit) { + testInline( + query, + configuration(switchOn), + cleanupOutput = true + ) { + pagesTransformationStage = { root -> + val classB = root.dfs { it.name == "ClassB" } as? ClasslikePageNode + assertNotNull(classB, "Tested class not found!") + operation(classB) + } + } + } + + private fun ClasslikePageNode.findSectionWithName(name: String) : ContentNode? { + var sectionHeader: ContentHeader? = null + return content.dfs { node -> + node.children.filterIsInstance<ContentHeader>().any { header -> + header.children.firstOrNull { it is ContentText && it.text == name }?.also { sectionHeader = header } != null + } + }?.children?.dropWhile { child -> child != sectionHeader }?.drop(1)?.firstOrNull() + } + + @Test + fun `should not split inherited and regular methods`() { + testClassB(false) { classB -> + val functions = classB.findSectionWithName("Functions") + assertNotNull(functions, "Functions not found!") + assertEquals(7, functions.children.size, "Incorrect number of functions found") + } + } + + @Test + fun `should not split inherited and regular properties`() { + testClassB(false) { classB -> + val properties = classB.findSectionWithName("Properties") + assertNotNull(properties, "Properties not found!") + assertEquals(2, properties.children.size, "Incorrect number of properties found") + } + } + + @Test + fun `should split inherited and regular methods`() { + testClassB(true) { classB -> + val functions = classB.findSectionWithName("Functions") + val inheritedFunctions = classB.findSectionWithName("Inherited functions") + assertNotNull(functions, "Functions not found!") + assertEquals(2, functions.children.size, "Incorrect number of functions found") + assertNotNull(inheritedFunctions, "Inherited functions not found!") + assertEquals(5, inheritedFunctions.children.size, "Incorrect number of inherited functions found") + } + } + + @Test + fun `should split inherited and regular properties`() { + testClassB(true) { classB -> + val properties = classB.findSectionWithName("Properties") + assertNotNull(properties, "Properties not found!") + assertEquals(1, properties.children.size, "Incorrect number of properties found") + val inheritedProperties = classB.findSectionWithName("Inherited properties") + assertNotNull(inheritedProperties, "Inherited properties not found!") + assertEquals(1, inheritedProperties.children.size, "Incorrect number of inherited properties found") + } + } +}
\ No newline at end of file diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt index 7433b46e..aee38596 100644 --- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt +++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt @@ -163,7 +163,7 @@ data class JavadocFunctionNode( ) : AnchorableJavadocNode(name, dri), WithJavadocExtra<DFunction>, WithBrief { val isInherited: Boolean get() { - val extra = extra[InheritedFunction] + val extra = extra[InheritedMember] return extra?.inheritedFrom?.keys?.firstOrNull { it.analysisPlatform == Platform.jvm }?.let { jvm -> extra.isInherited(jvm) } ?: false diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt index 15bb625a..a6eda405 100644 --- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt +++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt @@ -9,7 +9,7 @@ import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.links.parent import org.jetbrains.dokka.links.sureClassNames import org.jetbrains.dokka.model.ImplementedInterfaces -import org.jetbrains.dokka.model.InheritedFunction +import org.jetbrains.dokka.model.InheritedMember import org.jetbrains.dokka.pages.* import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.utilities.formatToEndWithHtml @@ -224,7 +224,7 @@ internal class JavadocContentToTemplateMapTranslator( } private fun templateMapForInheritedMethod(node: JavadocFunctionNode): TemplateMap { - val inheritedFrom = node.extra[InheritedFunction]?.inheritedFrom + val inheritedFrom = node.extra[InheritedMember]?.inheritedFrom return mapOf( "inheritedFrom" to inheritedFrom?.entries?.firstOrNull { it.key.analysisPlatform == Platform.jvm }?.value?.displayable() // TODO: REMOVE HARDCODED JVM DEPENDENCY .orEmpty(), diff --git a/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt b/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt index b390751c..2a9b857a 100644 --- a/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt +++ b/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt @@ -2,10 +2,12 @@ package org.jetbrains.dokka.kotlinAsJava import org.jetbrains.dokka.CoreExtensions import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.DokkaBaseConfiguration import org.jetbrains.dokka.kotlinAsJava.signatures.JavaSignatureProvider import org.jetbrains.dokka.kotlinAsJava.transformers.KotlinAsJavaDocumentableTransformer import org.jetbrains.dokka.kotlinAsJava.translators.KotlinAsJavaDocumentableToPageTranslator import org.jetbrains.dokka.plugability.DokkaPlugin +import org.jetbrains.dokka.plugability.configuration class KotlinAsJavaPlugin : DokkaPlugin() { val kotlinAsJavaDocumentableTransformer by extending { diff --git a/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaDocumentableToPageTranslator.kt b/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaDocumentableToPageTranslator.kt index ac526d57..0f7d74b6 100644 --- a/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaDocumentableToPageTranslator.kt +++ b/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaDocumentableToPageTranslator.kt @@ -1,21 +1,25 @@ package org.jetbrains.dokka.kotlinAsJava.translators import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.DokkaBaseConfiguration import org.jetbrains.dokka.base.signatures.SignatureProvider import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.transformers.documentation.DocumentableToPageTranslator import org.jetbrains.dokka.model.DModule import org.jetbrains.dokka.pages.ModulePageNode +import org.jetbrains.dokka.plugability.configuration import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.plugin import org.jetbrains.dokka.plugability.querySingle import org.jetbrains.dokka.utilities.DokkaLogger class KotlinAsJavaDocumentableToPageTranslator(context: DokkaContext) : DocumentableToPageTranslator { + private val configuration = configuration<DokkaBase, DokkaBaseConfiguration>(context) private val commentsToContentConverter = context.plugin<DokkaBase>().querySingle { commentsToContentConverter } private val signatureProvider = context.plugin<DokkaBase>().querySingle { signatureProvider } private val logger: DokkaLogger = context.logger override fun invoke(module: DModule): ModulePageNode = - KotlinAsJavaPageCreator(commentsToContentConverter, signatureProvider, logger).pageForModule(module) + KotlinAsJavaPageCreator(configuration, commentsToContentConverter, signatureProvider, logger).pageForModule(module) }
\ No newline at end of file diff --git a/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaPageCreator.kt b/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaPageCreator.kt index de998c55..b2cf6246 100644 --- a/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaPageCreator.kt +++ b/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaPageCreator.kt @@ -1,16 +1,19 @@ package org.jetbrains.dokka.kotlinAsJava.translators +import org.jetbrains.dokka.base.DokkaBaseConfiguration import org.jetbrains.dokka.base.signatures.SignatureProvider import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter import org.jetbrains.dokka.base.translators.documentables.DefaultPageCreator +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.model.DProperty import org.jetbrains.dokka.pages.MemberPageNode import org.jetbrains.dokka.utilities.DokkaLogger class KotlinAsJavaPageCreator( + configuration: DokkaBaseConfiguration?, commentsToContentConverter: CommentsToContentConverter, signatureProvider: SignatureProvider, logger: DokkaLogger -) : DefaultPageCreator(commentsToContentConverter, signatureProvider, logger) { +) : DefaultPageCreator(configuration, commentsToContentConverter, signatureProvider, logger) { override fun pageForProperty(p: DProperty): MemberPageNode? = null }
\ No newline at end of file |