From c33e8e16a0e446b78496cbcd878ba76ea51c0940 Mon Sep 17 00:00:00 2001 From: Błażej Kardyś Date: Thu, 31 Oct 2019 11:44:03 +0100 Subject: Temp changes --- .../main/kotlin/Generation/DocumentationMerger.kt | 235 ------ core/src/main/kotlin/Generation/DokkaGenerator.kt | 71 +- .../kotlin/Java/JavaPsiDocumentationBuilder.kt | 81 +- .../kotlin/Kotlin/DescriptorDocumentationParser.kt | 75 +- .../src/main/kotlin/Kotlin/DocumentationBuilder.kt | 914 ++++----------------- .../Kotlin/KotlinAsJavaDocumentationBuilder.kt | 3 +- core/src/main/kotlin/Model/DocumentationNode.kt | 339 +------- .../main/kotlin/Model/DocumentationReference.kt | 115 --- core/src/main/kotlin/Utilities/DokkaModules.kt | 3 - core/src/main/kotlin/links/DRI.kt | 2 + 10 files changed, 297 insertions(+), 1541 deletions(-) delete mode 100644 core/src/main/kotlin/Generation/DocumentationMerger.kt delete mode 100644 core/src/main/kotlin/Model/DocumentationReference.kt (limited to 'core') diff --git a/core/src/main/kotlin/Generation/DocumentationMerger.kt b/core/src/main/kotlin/Generation/DocumentationMerger.kt deleted file mode 100644 index 53dc23a9..00000000 --- a/core/src/main/kotlin/Generation/DocumentationMerger.kt +++ /dev/null @@ -1,235 +0,0 @@ -package org.jetbrains.dokka.Generation - -import org.jetbrains.dokka.* - -class DocumentationMerger( - private val documentationModules: List, - val logger: DokkaLogger -) { - private val producedNodeRefGraph: NodeReferenceGraph = NodeReferenceGraph() - private val signatureMap: Map - private val oldToNewNodeMap: MutableMap = mutableMapOf() - - init { - if (documentationModules.groupBy { it.name }.size > 1) { - throw IllegalArgumentException("Modules should have similar names: ${documentationModules.joinToString(", ") {it.name}}") - } - - signatureMap = documentationModules - .flatMap { it.nodeRefGraph.nodeMapView.entries } - .associate { (k, v) -> v to k } - - - documentationModules.map { it.nodeRefGraph } - .flatMap { it.references } - .forEach { producedNodeRefGraph.addReference(it) } - } - - private fun mergePackageReferences( - from: DocumentationNode, - packages: List - ): List { - val packagesByName = packages - .map { it.to } - .groupBy { it.name } - - val resultReferences = mutableListOf() - for ((name, listOfPackages) in packagesByName) { - try { - val producedPackage = mergePackagesWithEqualNames(name, from, listOfPackages) - updatePendingReferences() - - resultReferences.add( - DocumentationReference(from, producedPackage, RefKind.Member) - ) - } catch (t: Throwable) { - val entries = listOfPackages.joinToString(",") { "references:${it.allReferences().size}" } - throw Error("Failed to merge package $name from $from with entries $entries. ${t.message}", t) - } - } - - return resultReferences - } - - private fun mergePackagesWithEqualNames( - name: String, - from: DocumentationNode, - packages: List - ): DocumentationNode { - val mergedPackage = DocumentationNode(name, Content.Empty, NodeKind.Package) - - for (contentToAppend in packages.map { it.content }.distinct()) { - mergedPackage.updateContent { - for (otherChild in contentToAppend.children) { - children.add(otherChild) - } - } - } - - for (node in packages) { - oldToNewNodeMap[node] = mergedPackage - } - - val references = packages.flatMap { it.allReferences() } - val mergedReferences = mergeReferences(mergedPackage, references) - for (ref in mergedReferences) { - if (ref.kind == RefKind.Owner) { - continue - } - mergedPackage.addReference(ref) - } - - from.append(mergedPackage, RefKind.Member) - - return mergedPackage - } - - private fun mergeMemberGroupBy(it: DocumentationNode): String { - val signature = signatureMap[it] - - if (signature != null) { - return signature - } - - logger.error("Failed to find signature for $it in \n${it.allReferences().joinToString { "\n ${it.kind} ${it.to}" }}") - return "" - } - - private fun mergeMemberReferences( - from: DocumentationNode, - refs: List - ): List { - val membersBySignature: Map> = refs.map { it.to } - .groupBy(this::mergeMemberGroupBy) - - val mergedMembers: MutableList = mutableListOf() - for ((signature, members) in membersBySignature) { - val newNode = mergeMembersWithEqualSignature(signature, members) - - producedNodeRefGraph.register(signature, newNode) - updatePendingReferences() - from.append(newNode, RefKind.Member) - - mergedMembers.add(DocumentationReference(from, newNode, RefKind.Member)) - } - - return mergedMembers - } - - private fun mergeMembersWithEqualSignature( - signature: String, - nodes: List - ): DocumentationNode { - require(nodes.isNotEmpty()) - - val singleNode = nodes.singleOrNull() - if (singleNode != null) { - singleNode.dropReferences { it.kind == RefKind.Owner } - return singleNode - } - - // Specialization processing - // Given (Common, JVM, JRE6, JS) and (JVM, JRE6) and (JVM, JRE7) - // Sorted: (JVM, JRE6), (JVM, JRE7), (Common, JVM, JRE6, JS) - // Should output: (JVM, JRE6), (JVM, JRE7), (Common, JS) - // Should not remove first platform - val nodesSortedByPlatformCount = nodes.sortedBy { it.platforms.size } - val allPlatforms = mutableSetOf() - nodesSortedByPlatformCount.forEach { node -> - node.platforms - .filterNot { allPlatforms.add(it) } - .filter { it != node.platforms.first() } - .forEach { platform -> - node.dropReferences { it.kind == RefKind.Platform && it.to.name == platform } - } - } - - // TODO: Quick and dirty fox for merging extensions for external classes. Fix this probably in StructuredFormatService - // TODO: while refactoring documentation model - - val groupNode = if(nodes.first().kind == NodeKind.ExternalClass){ - DocumentationNode(nodes.first().name, Content.Empty, NodeKind.ExternalClass) - } else { - DocumentationNode(nodes.first().name, Content.Empty, NodeKind.GroupNode) - } - groupNode.appendTextNode(signature, NodeKind.Signature, RefKind.Detail) - - for (node in nodes) { - node.dropReferences { it.kind == RefKind.Owner } - groupNode.append(node, RefKind.Origin) - node.append(groupNode, RefKind.TopLevelPage) - - oldToNewNodeMap[node] = groupNode - } - - if (groupNode.kind == NodeKind.ExternalClass){ - val refs = nodes.flatMap { it.allReferences() }.filter { it.kind != RefKind.Owner && it.kind != RefKind.TopLevelPage } - refs.forEach { - if (it.kind != RefKind.Link) { - it.to.dropReferences { ref -> ref.kind == RefKind.Owner } - it.to.append(groupNode, RefKind.Owner) - } - groupNode.append(it.to, it.kind) - } - } - - // if nodes are classes, nested members should be also merged and - // inserted at the same level with class - if (nodes.all { it.kind in NodeKind.classLike }) { - val members = nodes.flatMap { it.allReferences() }.filter { it.kind == RefKind.Member } - val mergedMembers = mergeMemberReferences(groupNode, members) - - for (ref in mergedMembers) { - if (ref.kind == RefKind.Owner) { - continue - } - - groupNode.append(ref.to, RefKind.Member) - } - } - - return groupNode - } - - - private fun mergeReferences( - from: DocumentationNode, - refs: List - ): List { - val (refsToPackages, otherRefs) = refs.partition { it.to.kind == NodeKind.Package } - val mergedPackages = mergePackageReferences(from, refsToPackages) - - val (refsToMembers, refsNotToMembers) = otherRefs.partition { it.kind == RefKind.Member } - val mergedMembers = mergeMemberReferences(from, refsToMembers) - - return mergedPackages + mergedMembers + refsNotToMembers - } - - fun merge(): DocumentationModule { - val mergedDocumentationModule = DocumentationModule( - name = documentationModules.first().name, - content = documentationModules.first().content, - nodeRefGraph = producedNodeRefGraph - ) - - val refs = documentationModules.flatMap { - it.allReferences() - } - mergeReferences(mergedDocumentationModule, refs) - - return mergedDocumentationModule - } - - private fun updatePendingReferences() { - for (ref in producedNodeRefGraph.references) { - ref.lazyNodeFrom.update() - ref.lazyNodeTo.update() - } - } - - private fun NodeResolver.update() { - if (this is NodeResolver.Exact && exactNode in oldToNewNodeMap) { - exactNode = oldToNewNodeMap[exactNode]!! - } - } -} \ No newline at end of file diff --git a/core/src/main/kotlin/Generation/DokkaGenerator.kt b/core/src/main/kotlin/Generation/DokkaGenerator.kt index 90d7cfcc..51d70fbd 100644 --- a/core/src/main/kotlin/Generation/DokkaGenerator.kt +++ b/core/src/main/kotlin/Generation/DokkaGenerator.kt @@ -7,9 +7,7 @@ import com.intellij.openapi.vfs.VirtualFileManager import com.intellij.psi.PsiFile import com.intellij.psi.PsiJavaFile import com.intellij.psi.PsiManager -import org.jetbrains.dokka.Generation.DocumentationMerger import org.jetbrains.dokka.Utilities.DokkaAnalysisModule -import org.jetbrains.dokka.Utilities.DokkaOutputModule import org.jetbrains.dokka.Utilities.DokkaRunModule import org.jetbrains.kotlin.cli.common.CLIConfigurationKeys import org.jetbrains.kotlin.cli.common.messages.CompilerMessageLocation @@ -24,12 +22,13 @@ import org.jetbrains.kotlin.resolve.LazyTopDownAnalyzer import org.jetbrains.kotlin.resolve.TopDownAnalysisMode import org.jetbrains.kotlin.utils.PathUtil import java.io.File -import kotlin.system.measureTimeMillis -class DokkaGenerator(val dokkaConfiguration: DokkaConfiguration, - val logger: DokkaLogger) { +class DokkaGenerator( + val dokkaConfiguration: DokkaConfiguration, + val logger: DokkaLogger +) { - private val documentationModules: MutableList = mutableListOf() + private val documentationModules: MutableList = mutableListOf() private val globalInjector = Guice.createInjector(DokkaRunModule(dokkaConfiguration)) @@ -37,26 +36,15 @@ class DokkaGenerator(val dokkaConfiguration: DokkaConfiguration, for (pass in passesConfigurations) { - val documentationModule = DocumentationModule(pass.moduleName) + val documentationModule = DocumentationNodes.Module(pass.moduleName) appendSourceModule(pass, documentationModule) documentationModules.add(documentationModule) } - - val totalDocumentationModule = DocumentationMerger(documentationModules, logger).merge() - totalDocumentationModule.prepareForGeneration(dokkaConfiguration) - - val timeBuild = measureTimeMillis { - logger.info("Generating pages... ") - val outputInjector = globalInjector.createChildInjector(DokkaOutputModule(dokkaConfiguration, logger)) - val instance = outputInjector.getInstance(Generator::class.java) - instance.buildAll(totalDocumentationModule) - } - logger.info("done in ${timeBuild / 1000} secs") } private fun appendSourceModule( passConfiguration: DokkaConfiguration.PassConfiguration, - documentationModule: DocumentationModule + documentationModule: DocumentationNodes.Module ) = with(passConfiguration) { val sourcePaths = passConfiguration.sourceRoots.map { it.path } @@ -84,9 +72,15 @@ class DokkaGenerator(val dokkaConfiguration: DokkaConfiguration, } val injector = globalInjector.createChildInjector( - DokkaAnalysisModule(environment, dokkaConfiguration, defaultPlatformsProvider, documentationModule.nodeRefGraph, passConfiguration, logger)) + DokkaAnalysisModule(environment, dokkaConfiguration, defaultPlatformsProvider, passConfiguration, logger) + ) - buildDocumentationModule(injector, documentationModule, { isNotSample(it, passConfiguration.samples) }, includes) + buildDocumentationModule( + injector, + documentationModule, + { isNotSample(it, passConfiguration.samples) }, + includes + ) val timeAnalyse = System.currentTimeMillis() - startAnalyse logger.info("done in ${timeAnalyse / 1000} secs") @@ -118,7 +112,7 @@ class DokkaGenerator(val dokkaConfiguration: DokkaConfiguration, return environment } - private fun isNotSample(file: PsiFile, samples: List): Boolean { + private fun isNotSample(file: PsiFile, samples: List): Boolean { val sourceFile = File(file.virtualFile!!.path) return samples.none { sample -> val canonicalSample = File(sample).canonicalPath @@ -145,10 +139,12 @@ class DokkaMessageCollector(val logger: DokkaLogger) : MessageCollector { override fun hasErrors() = seenErrors } -fun buildDocumentationModule(injector: Injector, - documentationModule: DocumentationModule, - filesToDocumentFilter: (PsiFile) -> Boolean = { file -> true }, - includes: List = listOf()) { +fun buildDocumentationModule( + injector: Injector, + documentationModule: DocumentationNodes.Module, + filesToDocumentFilter: (PsiFile) -> Boolean = { file -> true }, + includes: List = listOf() +) { val coreEnvironment = injector.getInstance(KotlinCoreEnvironment::class.java) val fragmentFiles = coreEnvironment.getSourceFiles().filter(filesToDocumentFilter) @@ -158,25 +154,20 @@ fun buildDocumentationModule(injector: Injector, analyzer.analyzeDeclarations(TopDownAnalysisMode.TopLevelDeclarations, fragmentFiles) val fragments = fragmentFiles.mapNotNull { resolutionFacade.resolveSession.getPackageFragment(it.packageFqName) } - .distinct() + .distinct() val packageDocs = injector.getInstance(PackageDocs::class.java) for (include in includes) { packageDocs.parse(include, fragments) } - if (documentationModule.content.isEmpty()) { - documentationModule.updateContent { - for (node in packageDocs.moduleContent.children) { - append(node) - } - } - } parseJavaPackageDocs(packageDocs, coreEnvironment) with(injector.getInstance(DocumentationBuilder::class.java)) { - documentationModule.appendFragments(fragments, packageDocs.packageContent, - injector.getInstance(PackageDocumentationBuilder::class.java)) + documentationModule.appendFragments( + fragments, + injector.getInstance(PackageDocumentationBuilder::class.java) + ) propagateExtensionFunctionsToSubclasses(fragments, resolutionFacade) } @@ -189,8 +180,8 @@ fun buildDocumentationModule(injector: Injector, fun parseJavaPackageDocs(packageDocs: PackageDocs, coreEnvironment: KotlinCoreEnvironment) { val contentRoots = coreEnvironment.configuration.get(CLIConfigurationKeys.CONTENT_ROOTS) - ?.filterIsInstance() - ?.map { it.file } + ?.filterIsInstance() + ?.map { it.file } ?: listOf() contentRoots.forEach { root -> root.walkTopDown().filter { it.name == "overview.html" }.forEach { @@ -202,8 +193,8 @@ fun parseJavaPackageDocs(packageDocs: PackageDocs, coreEnvironment: KotlinCoreEn fun KotlinCoreEnvironment.getJavaSourceFiles(): List { val sourceRoots = configuration.get(CLIConfigurationKeys.CONTENT_ROOTS) - ?.filterIsInstance() - ?.map { it.file } + ?.filterIsInstance() + ?.map { it.file } ?: listOf() val result = arrayListOf() diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index 3b368329..d3fc7048 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -12,7 +12,6 @@ import org.jetbrains.kotlin.asJava.elements.KtLightElement import org.jetbrains.kotlin.kdoc.parser.KDocKnownTag import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag import org.jetbrains.kotlin.lexer.KtTokens -import org.jetbrains.kotlin.psi.KtDeclaration import org.jetbrains.kotlin.psi.KtModifierListOwner fun getSignature(element: PsiElement?) = when(element) { @@ -55,30 +54,33 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { private val passConfiguration: DokkaConfiguration.PassConfiguration private val refGraph: NodeReferenceGraph private val docParser: JavaDocumentationParser + private val documentationBuilder: DocumentationBuilder @Inject constructor( - passConfiguration: DokkaConfiguration.PassConfiguration, + documentationBuilder: DocumentationBuilder, refGraph: NodeReferenceGraph, logger: DokkaLogger, signatureProvider: ElementSignatureProvider, externalDocumentationLinkResolver: ExternalDocumentationLinkResolver ) { - this.passConfiguration = passConfiguration + this.passConfiguration = documentationBuilder.passConfiguration + this.documentationBuilder = documentationBuilder this.refGraph = refGraph this.docParser = JavadocParser(refGraph, logger, signatureProvider, externalDocumentationLinkResolver) } - constructor(passConfiguration: DokkaConfiguration.PassConfiguration, refGraph: NodeReferenceGraph, docParser: JavaDocumentationParser) { - this.passConfiguration = passConfiguration + constructor(documentationBuilder: DocumentationBuilder, refGraph: NodeReferenceGraph, docParser: JavaDocumentationParser) { + this.passConfiguration = documentationBuilder.passConfiguration this.refGraph = refGraph this.docParser = docParser + this.documentationBuilder = documentationBuilder } override fun appendFile(file: PsiJavaFile, module: DocumentationModule, packageContent: Map) { if (skipFile(file) || file.classes.all { skipElement(it) }) { return } - val packageNode = findOrCreatePackageNode(module, file.packageName, emptyMap(), refGraph) + val packageNode = documentationBuilder.findOrCreatePackageNode(module, file.packageName, emptyMap(), refGraph) appendClasses(packageNode, file.classes) } @@ -108,7 +110,7 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { } fun nodeForElement(element: PsiNamedElement, - kind: NodeKind, + kind: DocumentationNodes, name: String = element.name ?: "", register: Boolean = false): DocumentationNode { val (docComment, deprecatedContent) = docParser.parseDocumentation(element) @@ -125,14 +127,6 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { } } } - if (deprecatedContent != null) { - val deprecationNode = DocumentationNode("", deprecatedContent, NodeKind.Modifier) - node.append(deprecationNode, RefKind.Deprecation) - } - if (element is PsiDocCommentOwner && element.isDeprecated && node.deprecation == null) { - val deprecationNode = DocumentationNode("", Content.of(ContentText("Deprecated")), NodeKind.Modifier) - node.append(deprecationNode, RefKind.Deprecation) - } return node } @@ -182,15 +176,15 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { fun PsiClass.build(): DocumentationNode { val kind = when { - isAnnotationType -> NodeKind.AnnotationClass - isInterface -> NodeKind.Interface - isEnum -> NodeKind.Enum - isException() -> NodeKind.Exception - else -> NodeKind.Class + isAnnotationType -> DocumentationNodes.AnnotationClass + isInterface -> DocumentationNodes.Interface + isEnum -> DocumentationNodes.Enum + isException() -> DocumentationNodes.Exception + else -> DocumentationNodes.Class } val node = nodeForElement(this, kind, register = isAnnotationType) superTypes.filter { !ignoreSupertype(it) }.forEach { - node.appendType(it, NodeKind.Supertype) + node.appendType(it, DocumentationNodes.Supertype) val superClass = it.resolve() if (superClass != null) { link(superClass, node, RefKind.Inheritor) @@ -239,13 +233,13 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { "\"" + StringUtil.escapeStringCharacters(value) + "\"" else -> value.toString() } - append(DocumentationNode(text, Content.Empty, NodeKind.Value), RefKind.Detail) + append(DocumentationNode(text, Content.Empty, DocumentationNodes.Value), RefKind.Detail) } } - private fun PsiField.nodeKind(): NodeKind = when { - this is PsiEnumConstant -> NodeKind.EnumItem - else -> NodeKind.Field + private fun PsiField.nodeKind(): DocumentationNodes = when { + this is PsiEnumConstant -> DocumentationNodes.EnumItem + else -> DocumentationNodes.Field } fun PsiMethod.build(): DocumentationNode { @@ -261,24 +255,21 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { return node } - private fun PsiMethod.nodeKind(): NodeKind = when { - isConstructor -> NodeKind.Constructor - else -> NodeKind.Function + private fun PsiMethod.nodeKind(): DocumentationNodes = when { + isConstructor -> DocumentationNodes.Constructor + else -> DocumentationNodes.Function } fun PsiParameter.build(): DocumentationNode { - val node = nodeForElement(this, NodeKind.Parameter) + val node = nodeForElement(this, DocumentationNodes.Parameter::class) node.appendType(type) - if (type is PsiEllipsisType) { - node.appendTextNode("vararg", NodeKind.Modifier, RefKind.Detail) - } return node } fun PsiTypeParameter.build(): DocumentationNode { - val node = nodeForElement(this, NodeKind.TypeParameter) - extendsListTypes.forEach { node.appendType(it, NodeKind.UpperBound) } - implementsListTypes.forEach { node.appendType(it, NodeKind.UpperBound) } + val node = nodeForElement(this, DocumentationNodes.TypeParameter) + extendsListTypes.forEach { node.appendType(it, DocumentationNodes.UpperBound) } + implementsListTypes.forEach { node.appendType(it, DocumentationNodes.UpperBound) } return node } @@ -287,27 +278,27 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { PsiModifier.MODIFIERS.forEach { if (modifierList.hasExplicitModifier(it)) { - appendTextNode(it, NodeKind.Modifier) + appendTextNode(it, DocumentationNodes.Modifier) } } } - fun DocumentationNode.appendType(psiType: PsiType?, kind: NodeKind = NodeKind.Type) { + fun DocumentationNode.appendType(psiType: PsiType?, kind: DocumentationNodes = DocumentationNodes.Type) { if (psiType == null) { return } append(psiType.build(kind), RefKind.Detail) } - fun PsiType.build(kind: NodeKind = NodeKind.Type): DocumentationNode { + fun PsiType.build(kind: DocumentationNodes = DocumentationNodes.Type): DocumentationNode { val name = mapTypeName(this) val node = DocumentationNode(name, Content.Empty, kind) if (this is PsiClassType) { - node.appendDetails(parameters) { build(NodeKind.Type) } + node.appendDetails(parameters) { build(DocumentationNodes.Type) } link(node, resolve()) } if (this is PsiArrayType && this !is PsiEllipsisType) { - node.append(componentType.build(NodeKind.Type), RefKind.Detail) + node.append(componentType.build(DocumentationNodes.Type), RefKind.Detail) } return node } @@ -316,7 +307,7 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { val existing = refGraph.lookup(getSignature(psiClass)!!) if (existing != null) return existing val new = psiClass.build() - val packageNode = findOrCreatePackageNode(null, (psiClass.containingFile as PsiJavaFile).packageName, emptyMap(), refGraph) + val packageNode = documentation. findOrCreatePackageNode(null, (psiClass.containingFile as PsiJavaFile).packageName, emptyMap(), refGraph) packageNode.append(new, RefKind.Member) return new } @@ -327,20 +318,20 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { is KtLightAbstractAnnotation -> clsDelegate else -> this } - val node = DocumentationNode(qualifiedName?.substringAfterLast(".") ?: "", Content.Empty, NodeKind.Annotation) + val node = DocumentationNodes.Annotation(qualifiedName?.substringAfterLast(".") ?: "") val psiClass = original.nameReferenceElement?.resolve() as? PsiClass if (psiClass != null && psiClass.isAnnotationType) { node.append(lookupOrBuildClass(psiClass), RefKind.Link) } parameterList.attributes.forEach { - val parameter = DocumentationNode(it.name ?: "value", Content.Empty, NodeKind.Parameter) + val parameter = DocumentationNodes.Parameter(it.name ?: "value", this.extractDescriptor()) val value = it.value if (value != null) { val valueText = (value as? PsiLiteralExpression)?.value as? String ?: value.text - val valueNode = DocumentationNode(valueText, Content.Empty, NodeKind.Value) + val valueNode = DocumentationNode(valueText, Content.Empty, DocumentationNodes.Value) parameter.append(valueNode, RefKind.Detail) } - node.append(parameter, RefKind.Detail) + node.append(parameter, RefKind.Detail)m } return node } diff --git a/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt b/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt index ce20aeec..7c9f2d15 100644 --- a/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt +++ b/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt @@ -30,20 +30,28 @@ import org.jetbrains.kotlin.resolve.scopes.getDescriptorsFiltered import org.jetbrains.kotlin.resolve.source.PsiSourceElement class DescriptorDocumentationParser - @Inject constructor(val options: DokkaConfiguration.PassConfiguration, - val logger: DokkaLogger, - val linkResolver: DeclarationLinkResolver, - val resolutionFacade: DokkaResolutionFacade, - val refGraph: NodeReferenceGraph, - val sampleService: SampleProcessingService, - val signatureProvider: KotlinElementSignatureProvider, - val externalDocumentationLinkResolver: ExternalDocumentationLinkResolver -) -{ - fun parseDocumentation(descriptor: DeclarationDescriptor, inline: Boolean = false, isDefaultNoArgConstructor: Boolean = false): Content = - parseDocumentationAndDetails(descriptor, inline, isDefaultNoArgConstructor).first +@Inject constructor( + val options: DokkaConfiguration.PassConfiguration, + val logger: DokkaLogger, + val linkResolver: DeclarationLinkResolver, + val resolutionFacade: DokkaResolutionFacade, + val refGraph: NodeReferenceGraph, + val sampleService: SampleProcessingService, + val signatureProvider: KotlinElementSignatureProvider, + val externalDocumentationLinkResolver: ExternalDocumentationLinkResolver +) { + fun parseDocumentation( + descriptor: DeclarationDescriptor, + inline: Boolean = false, + isDefaultNoArgConstructor: Boolean = false + ): Content = + parseDocumentationAndDetails(descriptor, inline, isDefaultNoArgConstructor).first - fun parseDocumentationAndDetails(descriptor: DeclarationDescriptor, inline: Boolean = false, isDefaultNoArgConstructor: Boolean = false): Pair Unit> { + fun parseDocumentationAndDetails( + descriptor: DeclarationDescriptor, + inline: Boolean = false, + isDefaultNoArgConstructor: Boolean = false + ): Pair Unit> { if (descriptor is JavaClassDescriptor || descriptor is JavaCallableMemberDescriptor) { return parseJavadoc(descriptor) } @@ -51,8 +59,8 @@ class DescriptorDocumentationParser val kdoc = descriptor.findKDoc() ?: findStdlibKDoc(descriptor) if (kdoc == null) { if (options.effectivePackageOptions(descriptor.fqNameSafe).reportUndocumented && !descriptor.isDeprecated() && - descriptor !is ValueParameterDescriptor && descriptor !is TypeParameterDescriptor && - descriptor !is PropertyAccessorDescriptor && !descriptor.isSuppressWarning()) { + descriptor !is ValueParameterDescriptor && descriptor !is TypeParameterDescriptor && + descriptor !is PropertyAccessorDescriptor && !descriptor.isSuppressWarning()) { logger.warn("No documentation for ${descriptor.signatureWithSourceLocation()}") } return Content.Empty to { node -> } @@ -62,7 +70,7 @@ class DescriptorDocumentationParser (PsiTreeUtil.getParentOfType(kdoc, KDoc::class.java)?.context as? KtDeclaration) ?.takeIf { it != descriptor.original.sourcePsi() } ?.resolveToDescriptorIfAny() - ?: descriptor + ?: descriptor var kdocText = if (isDefaultNoArgConstructor) { getConstructorTagContent(descriptor) ?: kdoc.getContent() @@ -74,7 +82,11 @@ class DescriptorDocumentationParser } val tree = parseMarkdown(kdocText) val linkMap = LinkMap.buildLinkMap(tree.node, kdocText) - val content = buildContent(tree, LinkResolver(linkMap) { href -> linkResolver.resolveContentLink(contextDescriptor, href) }, inline) + val content = buildContent( + tree, + LinkResolver(linkMap) { href -> linkResolver.resolveContentLink(contextDescriptor, href) }, + inline + ) if (kdoc is KDocSection) { val tags = kdoc.getTags() tags.forEach { @@ -87,7 +99,10 @@ class DescriptorDocumentationParser val section = content.addSection(javadocSectionDisplayName(it.name), it.getSubjectName()) val sectionContent = it.getContent() val markdownNode = parseMarkdown(sectionContent) - buildInlineContentTo(markdownNode, section, LinkResolver(linkMap) { href -> linkResolver.resolveContentLink(contextDescriptor, href) }) + buildInlineContentTo( + markdownNode, + section, + LinkResolver(linkMap) { href -> linkResolver.resolveContentLink(contextDescriptor, href) }) } } } @@ -102,7 +117,7 @@ class DescriptorDocumentationParser } - private fun DeclarationDescriptor.isSuppressWarning() : Boolean { + private fun DeclarationDescriptor.isSuppressWarning(): Boolean { val suppressAnnotation = annotations.findAnnotation(FqName(Suppress::class.qualifiedName!!)) return if (suppressAnnotation != null) { @Suppress("UNCHECKED_CAST") @@ -126,11 +141,12 @@ class DescriptorDocumentationParser } if (DescriptorUtils.getFqName(deepestDescriptor.containingDeclaration).asString() == "kotlin.Any") { val anyClassDescriptors = resolutionFacade.resolveSession.getTopLevelClassifierDescriptors( - FqName.fromSegments(listOf("kotlin", "Any")), NoLookupLocation.FROM_IDE) + FqName.fromSegments(listOf("kotlin", "Any")), NoLookupLocation.FROM_IDE + ) anyClassDescriptors.forEach { val anyMethod = (it as ClassDescriptor).getMemberScope(listOf()) - .getDescriptorsFiltered(DescriptorKindFilter.FUNCTIONS) { it == descriptor.name } - .single() + .getDescriptorsFiltered(DescriptorKindFilter.FUNCTIONS) { it == descriptor.name } + .single() val kdoc = anyMethod.findKDoc() if (kdoc != null) { return kdoc @@ -145,17 +161,12 @@ class DescriptorDocumentationParser val psi = ((descriptor as? DeclarationDescriptorWithSource)?.source as? PsiSourceElement)?.psi if (psi is PsiDocCommentOwner) { val parseResult = JavadocParser( - refGraph, - logger, - signatureProvider, - externalDocumentationLinkResolver + refGraph, + logger, + signatureProvider, + externalDocumentationLinkResolver ).parseDocumentation(psi as PsiNamedElement) - return parseResult.content to { node -> - parseResult.deprecatedContent?.let { - val deprecationNode = DocumentationNode("", it, NodeKind.Modifier) - node.append(deprecationNode, RefKind.Deprecation) - } - } + return parseResult.content to { node -> } } return Content.Empty to { node -> } } diff --git a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt index 3168e033..6d258564 100644 --- a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt +++ b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt @@ -1,61 +1,51 @@ package org.jetbrains.dokka import com.google.inject.Inject -import com.intellij.openapi.util.text.StringUtil import com.intellij.psi.PsiJavaFile import org.jetbrains.dokka.DokkaConfiguration.PassConfiguration -import org.jetbrains.dokka.Kotlin.DescriptorDocumentationParser import org.jetbrains.kotlin.builtins.KotlinBuiltIns -import org.jetbrains.kotlin.coroutines.hasFunctionOrSuspendFunctionType import org.jetbrains.kotlin.descriptors.* -import org.jetbrains.kotlin.descriptors.annotations.Annotated -import org.jetbrains.kotlin.descriptors.annotations.AnnotationDescriptor -import org.jetbrains.kotlin.descriptors.impl.EnumEntrySyntheticClassDescriptor import org.jetbrains.kotlin.idea.kdoc.findKDoc -import org.jetbrains.kotlin.idea.util.fuzzyExtensionReceiverType -import org.jetbrains.kotlin.idea.util.makeNotNullable -import org.jetbrains.kotlin.idea.util.toFuzzyType import org.jetbrains.kotlin.js.resolve.diagnostics.findPsi import org.jetbrains.kotlin.kdoc.psi.impl.KDocSection -import org.jetbrains.kotlin.lexer.KtTokens -import org.jetbrains.kotlin.name.ClassId import org.jetbrains.kotlin.name.FqName -import org.jetbrains.kotlin.name.Name -import org.jetbrains.kotlin.psi.KtModifierListOwner -import org.jetbrains.kotlin.psi.KtParameter -import org.jetbrains.kotlin.psi.addRemoveModifier.MODIFIERS_ORDER import org.jetbrains.kotlin.resolve.DescriptorUtils -import org.jetbrains.kotlin.resolve.constants.ConstantValue import org.jetbrains.kotlin.resolve.descriptorUtil.* import org.jetbrains.kotlin.resolve.findTopMostOverriddenDescriptors import org.jetbrains.kotlin.resolve.scopes.DescriptorKindFilter import org.jetbrains.kotlin.resolve.scopes.getDescriptorsFiltered import org.jetbrains.kotlin.resolve.source.PsiSourceElement -import org.jetbrains.kotlin.resolve.source.getPsi import org.jetbrains.kotlin.types.* import org.jetbrains.kotlin.types.typeUtil.immediateSupertypes import org.jetbrains.kotlin.types.typeUtil.isAnyOrNullableAny import org.jetbrains.kotlin.types.typeUtil.isTypeParameter import org.jetbrains.kotlin.types.typeUtil.supertypes import org.jetbrains.kotlin.util.supertypesWithAny +import kotlin.reflect.KClass import com.google.inject.name.Named as GuiceNamed -private fun isExtensionForExternalClass(extensionFunctionDescriptor: DeclarationDescriptor, - extensionReceiverDescriptor: DeclarationDescriptor, - allFqNames: Collection): Boolean { - val extensionFunctionPackage = DescriptorUtils.getParentOfType(extensionFunctionDescriptor, PackageFragmentDescriptor::class.java) - val extensionReceiverPackage = DescriptorUtils.getParentOfType(extensionReceiverDescriptor, PackageFragmentDescriptor::class.java) +private fun isExtensionForExternalClass( + extensionFunctionDescriptor: DeclarationDescriptor, + extensionReceiverDescriptor: DeclarationDescriptor, + allFqNames: Collection +): Boolean { + val extensionFunctionPackage = + DescriptorUtils.getParentOfType(extensionFunctionDescriptor, PackageFragmentDescriptor::class.java) + val extensionReceiverPackage = + DescriptorUtils.getParentOfType(extensionReceiverDescriptor, PackageFragmentDescriptor::class.java) return extensionFunctionPackage != null && extensionReceiverPackage != null && extensionFunctionPackage.fqName != extensionReceiverPackage.fqName && extensionReceiverPackage.fqName !in allFqNames } interface PackageDocumentationBuilder { - fun buildPackageDocumentation(documentationBuilder: DocumentationBuilder, - packageName: FqName, - packageNode: DocumentationNode, - declarations: List, - allFqNames: Collection) + fun buildPackageDocumentation( + documentationBuilder: DocumentationBuilder, + packageName: FqName, + packageNode: DocumentationNodes.Package, + declarations: List, + allFqNames: Collection + ) } interface DefaultPlatformsProvider { @@ -67,121 +57,33 @@ val ignoredSupertypes = setOf( ) class DocumentationBuilder -@Inject constructor(val resolutionFacade: DokkaResolutionFacade, - val descriptorDocumentationParser: DescriptorDocumentationParser, - val passConfiguration: DokkaConfiguration.PassConfiguration, - val refGraph: NodeReferenceGraph, - val platformNodeRegistry: PlatformNodeRegistry, - val logger: DokkaLogger, - val linkResolver: DeclarationLinkResolver, - val defaultPlatformsProvider: DefaultPlatformsProvider) { - val boringBuiltinClasses = setOf( - "kotlin.Unit", "kotlin.Byte", "kotlin.Short", "kotlin.Int", "kotlin.Long", "kotlin.Char", "kotlin.Boolean", - "kotlin.Float", "kotlin.Double", "kotlin.String", "kotlin.Array", "kotlin.Any") - val knownModifiers = setOf( - KtTokens.PUBLIC_KEYWORD, KtTokens.PROTECTED_KEYWORD, KtTokens.INTERNAL_KEYWORD, KtTokens.PRIVATE_KEYWORD, - KtTokens.OPEN_KEYWORD, KtTokens.FINAL_KEYWORD, KtTokens.ABSTRACT_KEYWORD, KtTokens.SEALED_KEYWORD, - KtTokens.OVERRIDE_KEYWORD, KtTokens.INLINE_KEYWORD) - - fun link(node: DocumentationNode, descriptor: DeclarationDescriptor, kind: RefKind) { - refGraph.link(node, descriptor.signature(), kind) - } - - fun link(fromDescriptor: DeclarationDescriptor?, toDescriptor: DeclarationDescriptor?, kind: RefKind) { - if (fromDescriptor != null && toDescriptor != null) { - refGraph.link(fromDescriptor.signature(), toDescriptor.signature(), kind) - } - } - - fun register(descriptor: DeclarationDescriptor, node: DocumentationNode) { - refGraph.register(descriptor.signature(), node) - } - - fun nodeForDescriptor( - descriptor: T, - kind: NodeKind, - external: Boolean = false - ): DocumentationNode where T : DeclarationDescriptor, T : Named { - val (doc, callback) = - if (external) { - Content.Empty to { node -> } - } else { - descriptorDocumentationParser.parseDocumentationAndDetails( - descriptor, - kind == NodeKind.Parameter - ) - } - val node = DocumentationNode(descriptor.name.asString(), doc, kind).withModifiers(descriptor) - node.appendSignature(descriptor) - callback(node) - return node - } - - private fun DocumentationNode.withModifiers(descriptor: DeclarationDescriptor): DocumentationNode { - if (descriptor is MemberDescriptor) { - appendVisibility(descriptor) - if (descriptor !is ConstructorDescriptor) { - appendModality(descriptor) - } - } - return this - } +@Inject constructor( + val resolutionFacade: DokkaResolutionFacade, + val passConfiguration: DokkaConfiguration.PassConfiguration, + val logger: DokkaLogger +) { - fun DocumentationNode.appendModality(descriptor: MemberDescriptor) { - var modality = descriptor.modality - if (modality == Modality.OPEN) { - val containingClass = descriptor.containingDeclaration as? ClassDescriptor - if (containingClass?.modality == Modality.FINAL) { - modality = Modality.FINAL - } - } - val modifier = modality.name.toLowerCase() - appendTextNode(modifier, NodeKind.Modifier) - } - - fun DocumentationNode.appendInline(descriptor: DeclarationDescriptor, psi: KtModifierListOwner) { - if (!psi.hasModifier(KtTokens.INLINE_KEYWORD)) return - if (descriptor is FunctionDescriptor - && descriptor.valueParameters.none { it.hasFunctionOrSuspendFunctionType }) return - appendTextNode(KtTokens.INLINE_KEYWORD.value, NodeKind.Modifier) - } - - fun DocumentationNode.appendVisibility(descriptor: DeclarationDescriptorWithVisibility) { - val modifier = descriptor.visibility.normalize().displayName - appendTextNode(modifier, NodeKind.Modifier) - } - - fun DocumentationNode.appendSupertype(descriptor: ClassDescriptor, superType: KotlinType, backref: Boolean) { + private fun DocumentationNodes.Class.appendSupertype(descriptor: ClassDescriptor, superType: KotlinType, backref: Boolean) { val unwrappedType = superType.unwrap() if (unwrappedType is AbbreviatedType) { appendSupertype(descriptor, unwrappedType.abbreviation, backref) } else { - appendType(unwrappedType, NodeKind.Supertype) - val superclass = unwrappedType.constructor.declarationDescriptor - if (backref) { - link(superclass, descriptor, RefKind.Inheritor) - } - link(descriptor, superclass, RefKind.Superclass) + appendType(unwrappedType, descriptor) } } - fun DocumentationNode.appendProjection(projection: TypeProjection, kind: NodeKind = NodeKind.Type) { - if (projection.isStarProjection) { - appendTextNode("*", NodeKind.Type) - } else { - appendType(projection.type, kind, projection.projectionKind.label) - } - } - - fun DocumentationNode.appendType(kotlinType: KotlinType?, kind: NodeKind = NodeKind.Type, prefix: String = "") { + private fun DocumentationNodes.Class.appendType( + kotlinType: KotlinType?, + descriptor: ClassDescriptor? + ) { if (kotlinType == null) return (kotlinType.unwrap() as? AbbreviatedType)?.let { - return appendType(it.abbreviation) + return appendType(it.abbreviation, descriptor) } if (kotlinType.isDynamic()) { - append(DocumentationNode("dynamic", Content.Empty, kind), RefKind.Detail) + append(kind.createNode("dynamic", descriptor), RefKind.Detail) return } @@ -198,244 +100,80 @@ class DocumentationBuilder is Named -> classifierDescriptor.name.asString() else -> "" } - val node = DocumentationNode(name, Content.Empty, kind) - if (prefix != "") { - node.appendTextNode(prefix, NodeKind.Modifier) - } - if (kotlinType.isNullabilityFlexible()) { - node.appendTextNode("!", NodeKind.NullabilityModifier) - } else if (kotlinType.isMarkedNullable) { - node.appendTextNode("?", NodeKind.NullabilityModifier) - } - if (classifierDescriptor != null) { - val externalLink = - linkResolver.externalDocumentationLinkResolver.buildExternalDocumentationLink(classifierDescriptor) - if (externalLink != null) { - if (classifierDescriptor !is TypeParameterDescriptor) { - val targetNode = - refGraph.lookup(classifierDescriptor.signature()) ?: classifierDescriptor.build(true) - node.append(targetNode, RefKind.ExternalType) - node.append(DocumentationNode(externalLink, Content.Empty, NodeKind.ExternalLink), RefKind.Link) - } - } else { - link( - node, classifierDescriptor, - if (classifierDescriptor.isBoringBuiltinClass()) RefKind.HiddenLink else RefKind.Link - ) - } - if (classifierDescriptor !is TypeParameterDescriptor) { - node.append( - DocumentationNode( - classifierDescriptor.fqNameUnsafe.asString(), - Content.Empty, - NodeKind.QualifiedName - ), RefKind.Detail - ) - } - } - + val node = kind.createNode(name, descriptor) append(node, RefKind.Detail) - node.appendAnnotations(kotlinType) for (typeArgument in kotlinType.arguments) { - node.appendProjection(typeArgument) - } - } - - fun ClassifierDescriptor.isBoringBuiltinClass(): Boolean = - DescriptorUtils.getFqName(this).asString() in boringBuiltinClasses - - fun DocumentationNode.appendAnnotations(annotated: Annotated) { - annotated.annotations.forEach { - it.build()?.let { annotationNode -> - if (annotationNode.isSinceKotlin()) { - appendSinceKotlin(annotationNode) - } - else { - val refKind = when { - it.isDocumented() -> - when { - annotationNode.isDeprecation() -> RefKind.Deprecation - else -> RefKind.Annotation - } - it.isHiddenInDocumentation() -> RefKind.HiddenAnnotation - else -> return@forEach - } - append(annotationNode, refKind) - } - - } - } - } - - fun DocumentationNode.appendExternalLink(externalLink: String) { - append(DocumentationNode(externalLink, Content.Empty, NodeKind.ExternalLink), RefKind.Link) - } - - fun DocumentationNode.appendExternalLink(descriptor: DeclarationDescriptor) { - val target = linkResolver.externalDocumentationLinkResolver.buildExternalDocumentationLink(descriptor) - if (target != null) { - appendExternalLink(target) - } - } - - fun DocumentationNode.appendSinceKotlin(annotation: DocumentationNode) { - val kotlinVersion = annotation - .detail(NodeKind.Parameter) - .detail(NodeKind.Value) - .name.removeSurrounding("\"") - - sinceKotlin = kotlinVersion - } - - fun DocumentationNode.appendDefaultSinceKotlin() { - if (sinceKotlin == null) { - sinceKotlin = passConfiguration.sinceKotlin - } - } - - fun DocumentationNode.appendModifiers(descriptor: DeclarationDescriptor) { - val psi = (descriptor as DeclarationDescriptorWithSource).source.getPsi() as? KtModifierListOwner ?: return - KtTokens.MODIFIER_KEYWORDS_ARRAY.filter { - it !in knownModifiers - }.sortedBy { - MODIFIERS_ORDER.indexOf(it) - }.forEach { - if (psi.hasModifier(it)) { - appendTextNode(it.value, NodeKind.Modifier) - } + node.appendProjection(typeArgument, null) } - appendInline(descriptor, psi) } - fun DocumentationNode.appendDefaultPlatforms(descriptor: DeclarationDescriptor) { - for (platform in defaultPlatformsProvider.getDefaultPlatforms(descriptor)) { - append(platformNodeRegistry[platform], RefKind.Platform) - } - } - - fun DocumentationNode.isDeprecation() = name == "Deprecated" || name == "deprecated" - - fun DocumentationNode.isSinceKotlin() = name == "SinceKotlin" && kind == NodeKind.Annotation - - fun DocumentationNode.appendSourceLink(sourceElement: SourceElement) { - appendSourceLink(sourceElement.getPsi(), passConfiguration.sourceLinks) - } - - fun DocumentationNode.appendSignature(descriptor: DeclarationDescriptor) { - appendTextNode(descriptor.signature(), NodeKind.Signature, RefKind.Detail) - } - - fun DocumentationNode.appendChild(descriptor: DeclarationDescriptor, kind: RefKind): DocumentationNode? { + fun DocumentationNode<*>.appendChild(descriptor: DeclarationDescriptor) { if (!descriptor.isGenerated() && descriptor.isDocumented(passConfiguration)) { val node = descriptor.build() append(node, kind) - return node } - return null } - fun createGroupNode(signature: String, nodes: List) = (nodes.find { it.kind == NodeKind.GroupNode } ?: - DocumentationNode(nodes.first().name, Content.Empty, NodeKind.GroupNode).apply { - appendTextNode(signature, NodeKind.Signature, RefKind.Detail) - }) - .also { groupNode -> - nodes.forEach { node -> - if (node != groupNode) { - node.owner?.let { owner -> - node.dropReferences { it.to == owner && it.kind == RefKind.Owner } - owner.dropReferences { it.to == node && it.kind == RefKind.Member } - owner.append(groupNode, RefKind.Member) - } - groupNode.append(node, RefKind.Member) - } - } - } - - - fun DocumentationNode.appendOrUpdateMember(descriptor: DeclarationDescriptor) { - if (descriptor.isGenerated() || !descriptor.isDocumented(passConfiguration)) return - - val existingNode = refGraph.lookup(descriptor.signature()) - if (existingNode != null) { - if (existingNode.kind == NodeKind.TypeAlias && descriptor is ClassDescriptor - || existingNode.kind == NodeKind.Class && descriptor is TypeAliasDescriptor) { - val node = createGroupNode(descriptor.signature(), listOf(existingNode, descriptor.build())) - register(descriptor, node) - return - } - - existingNode.updatePlatforms(descriptor) - - if (descriptor is ClassDescriptor) { - val membersToDocument = descriptor.collectMembersToDocument() - for ((memberDescriptor, inheritedLinkKind, extraModifier) in membersToDocument) { - if (memberDescriptor is ClassDescriptor) { - existingNode.appendOrUpdateMember(memberDescriptor) // recurse into nested classes - } - else { - val existingMemberNode = refGraph.lookup(memberDescriptor.signature()) - if (existingMemberNode != null) { - existingMemberNode.updatePlatforms(memberDescriptor) - } - else { - existingNode.appendClassMember(memberDescriptor, inheritedLinkKind, extraModifier) + fun DocumentationNode.appendMember(descriptor: DeclarationDescriptor) { + if (!descriptor.isGenerated() && descriptor.isDocumented(passConfiguration)) { + val existingNode = members.firstOrNull { it.descriptor?.fqNameSafe == descriptor.fqNameSafe } + if (existingNode != null) { + if (descriptor is ClassDescriptor) { + val membersToDocument = descriptor.collectMembersToDocument() + for ((memberDescriptor, _, _) in membersToDocument) { + if (memberDescriptor is ClassDescriptor) { + existingNode.appendMember(memberDescriptor) // recurse into nested classes + } else { + if (members.any { it.descriptor?.fqNameSafe == memberDescriptor.fqNameSafe }) { + existingNode.appendClassMember(memberDescriptor) + } } } } + } else { + appendChild(descriptor, RefKind.Member) } } - else { - appendChild(descriptor, RefKind.Member) - } - } - - private fun DocumentationNode.updatePlatforms(descriptor: DeclarationDescriptor) { - for (platform in defaultPlatformsProvider.getDefaultPlatforms(descriptor) - platforms) { - append(platformNodeRegistry[platform], RefKind.Platform) - } } - fun DocumentationNode.appendClassMember(descriptor: DeclarationDescriptor, - inheritedLinkKind: RefKind = RefKind.InheritedMember, - extraModifier: String?) { - if (descriptor is CallableMemberDescriptor && descriptor.kind == CallableMemberDescriptor.Kind.FAKE_OVERRIDE) { - val baseDescriptor = descriptor.overriddenDescriptors.firstOrNull() - if (baseDescriptor != null) { - link(this, baseDescriptor, inheritedLinkKind) - } - } else { + private fun DocumentationNode.appendClassMember(descriptor: DeclarationDescriptor) { + if (descriptor !is CallableMemberDescriptor || descriptor.kind != CallableMemberDescriptor.Kind.FAKE_OVERRIDE) { val descriptorToUse = if (descriptor is ConstructorDescriptor) descriptor else descriptor.original - val child = appendChild(descriptorToUse, RefKind.Member) - if (extraModifier != null) { - child?.appendTextNode("static", NodeKind.Modifier) - } + appendChild(descriptorToUse, RefKind.Member) } } - fun DocumentationNode.appendInPageChildren(descriptors: Iterable, kind: RefKind) { - descriptors.forEach { descriptor -> - val node = appendChild(descriptor, kind) - node?.addReferenceTo(this, RefKind.TopLevelPage) - } - } - - fun DocumentationModule.appendFragments(fragments: Collection, - packageContent: Map, - packageDocumentationBuilder: PackageDocumentationBuilder) { - val allFqNames = fragments.filter{ it.isDocumented(passConfiguration) }.map { it.fqName }.distinct() + fun DocumentationNodes.Module.appendFragments( + fragments: Collection, + packageDocumentationBuilder: PackageDocumentationBuilder + ) { + val allFqNames = fragments.filter { it.isDocumented(passConfiguration) }.map { it.fqName }.distinct() for (packageName in allFqNames) { if (packageName.isRoot && !passConfiguration.includeRootPackage) continue - val declarations = fragments.filter { it.fqName == packageName }.flatMap { it.getMemberScope().getContributedDescriptors() } + val declarations = fragments.filter { it.fqName == packageName } + .flatMap { it.getMemberScope().getContributedDescriptors() } if (passConfiguration.skipEmptyPackages && declarations.none { it.isDocumented(passConfiguration) }) continue logger.info(" package $packageName: ${declarations.count()} declarations") - val packageNode = findOrCreatePackageNode(this, packageName.asString(), packageContent, this@DocumentationBuilder.refGraph) - packageDocumentationBuilder.buildPackageDocumentation(this@DocumentationBuilder, packageName, packageNode, - declarations, allFqNames) + val packageNode = findOrCreatePackageNode(this, packageName.asString()) + packageDocumentationBuilder.buildPackageDocumentation( + this@DocumentationBuilder, packageName, packageNode, + declarations, allFqNames + ) } + } + fun findOrCreatePackageNode( + module: DocumentationNodes.Module, + packageName: String + ): DocumentationNode<*> { + val node = module?.member(DocumentationNodes.Package::class) ?: DocumentationNodes.Package(packageName) + if (module != null && node !in module.members) { + module.append(node, RefKind.Member) + } + return node } fun propagateExtensionFunctionsToSubclasses( @@ -466,12 +204,6 @@ class DocumentationBuilder ).asSequence() } - - val documentingDescriptors = fragments.flatMap { it.getMemberScope().getContributedDescriptors() } - val documentingClasses = documentingDescriptors.filterIsInstance() - - val classHierarchy = buildClassHierarchy(documentingClasses) - val allExtensionFunctions = allDescriptors .filterIsInstance() @@ -479,9 +211,9 @@ class DocumentationBuilder val extensionFunctionsByName = allExtensionFunctions.groupBy { it.name } fun isIgnoredReceiverType(type: KotlinType) = - type.isDynamic() || - type.isAnyOrNullableAny() || - (type.isTypeParameter() && type.immediateSupertypes().all { it.isAnyOrNullableAny() }) + type.isDynamic() || + type.isAnyOrNullableAny() || + (type.isTypeParameter() && type.immediateSupertypes().all { it.isAnyOrNullableAny() }) for (extensionFunction in allExtensionFunctions) { @@ -492,53 +224,9 @@ class DocumentationBuilder ?: emptyList() if (isIgnoredReceiverType(extensionReceiverParameter.type)) continue - val subclasses = - classHierarchy.filter { (key) -> key.isExtensionApplicable(extensionFunction) } - if (subclasses.isEmpty()) continue - subclasses.values.flatten().forEach { subclass -> - if (subclass.isExtensionApplicable(extensionFunction) && - possiblyShadowingFunctions.none { subclass.isExtensionApplicable(it) }) { - - val hasExternalLink = - linkResolver.externalDocumentationLinkResolver.buildExternalDocumentationLink( - extensionFunction - ) != null - if (hasExternalLink) { - val containerDesc = - extensionFunction.containingDeclaration as? PackageFragmentDescriptor - if (containerDesc != null) { - val container = refGraph.lookup(containerDesc.signature()) - ?: containerDesc.buildExternal() - container.append(extensionFunction.buildExternal(), RefKind.Member) - } - } - - refGraph.link(subclass.signature(), extensionFunction.signature(), RefKind.Extension) - } - } } } - private fun ClassDescriptor.isExtensionApplicable(extensionFunction: CallableMemberDescriptor): Boolean { - val receiverType = extensionFunction.fuzzyExtensionReceiverType()?.makeNotNullable() - val classType = defaultType.toFuzzyType(declaredTypeParameters) - return receiverType != null && classType.checkIsSubtypeOf(receiverType) != null - } - - private fun buildClassHierarchy(classes: List): Map> { - val result = hashMapOf>() - classes.forEach { cls -> - TypeUtils.getAllSupertypes(cls.defaultType).forEach { supertype -> - val classDescriptor = supertype.constructor.declarationDescriptor as? ClassDescriptor - if (classDescriptor != null) { - val subtypesList = result.getOrPut(classDescriptor) { arrayListOf() } - subtypesList.add(cls) - } - } - } - return result - } - private fun CallableMemberDescriptor.canShadow(other: CallableMemberDescriptor): Boolean { if (this == other) return false if (this is PropertyDescriptor && other is PropertyDescriptor) { @@ -570,89 +258,47 @@ class DocumentationBuilder else -> throw IllegalStateException("Descriptor $this is not known") } - fun PackageFragmentDescriptor.buildExternal(): DocumentationNode { - val node = DocumentationNode(fqName.asString(), Content.Empty, NodeKind.Package) - - val externalLink = linkResolver.externalDocumentationLinkResolver.buildExternalDocumentationLink(this) - if (externalLink != null) { - node.append(DocumentationNode(externalLink, Content.Empty, NodeKind.ExternalLink), RefKind.Link) - } - register(this, node) - return node - } - - fun CallableDescriptor.buildExternal(): DocumentationNode = when(this) { - is FunctionDescriptor -> build(true) - is PropertyDescriptor -> build(true) - else -> throw IllegalStateException("Descriptor $this is not known") - } - - fun ClassifierDescriptor.build(external: Boolean = false): DocumentationNode = when (this) { - is ClassDescriptor -> build(external) - is TypeAliasDescriptor -> build(external) + is ClassDescriptor -> build(this, external) + is TypeAliasDescriptor -> build() is TypeParameterDescriptor -> build() else -> throw IllegalStateException("Descriptor $this is not known") } -