From a3f16fd75c200020465f79563ca58b2833236865 Mon Sep 17 00:00:00 2001 From: Simon Ogorodnik Date: Tue, 24 Apr 2018 20:35:42 +0300 Subject: [backport] Stabilize signatures to fix linking from Java to Kotlin Basically there is 2 ways to get signature, from PSI and from descriptors, and there should be only one way in one session Original: adc09f2 --- core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt') diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index cf2b0514..646096e5 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -45,10 +45,10 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { private val refGraph: NodeReferenceGraph private val docParser: JavaDocumentationParser - @Inject constructor(options: DocumentationOptions, refGraph: NodeReferenceGraph, logger: DokkaLogger) { + @Inject constructor(options: DocumentationOptions, refGraph: NodeReferenceGraph, logger: DokkaLogger, signatureProvider: ElementSignatureProvider) { this.options = options this.refGraph = refGraph - this.docParser = JavadocParser(refGraph, logger) + this.docParser = JavadocParser(refGraph, logger, signatureProvider) } constructor(options: DocumentationOptions, refGraph: NodeReferenceGraph, docParser: JavaDocumentationParser) { @@ -61,7 +61,7 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { if (skipFile(file) || file.classes.all { skipElement(it) }) { return } - val packageNode = module.findOrCreatePackageNode(file.packageName, emptyMap(), refGraph) + val packageNode = findOrCreatePackageNode(module, file.packageName, emptyMap(), refGraph) appendClasses(packageNode, file.classes) } -- cgit From b00dabc4c53a71f745c29a135541b02f8dd7d266 Mon Sep 17 00:00:00 2001 From: Simon Ogorodnik Date: Fri, 4 May 2018 21:35:02 +0300 Subject: [backport] KT-24271: Support external link resolution in JavadocParser Original: ace3914 --- .../main/kotlin/Analysis/AnalysisEnvironment.kt | 8 ++-- .../kotlin/Java/JavaPsiDocumentationBuilder.kt | 10 ++++- core/src/main/kotlin/Java/JavadocParser.kt | 51 ++++++++++++++++------ .../kotlin/Kotlin/DescriptorDocumentationParser.kt | 12 +++-- .../Kotlin/ExternalDocumentationLinkResolver.kt | 14 ++++-- .../Kotlin/KotlinElementSignatureProvider.kt | 30 ++++++------- core/src/main/kotlin/Utilities/DokkaModules.kt | 3 +- 7 files changed, 87 insertions(+), 41 deletions(-) (limited to 'core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt') diff --git a/core/src/main/kotlin/Analysis/AnalysisEnvironment.kt b/core/src/main/kotlin/Analysis/AnalysisEnvironment.kt index 6854b323..d31fe187 100644 --- a/core/src/main/kotlin/Analysis/AnalysisEnvironment.kt +++ b/core/src/main/kotlin/Analysis/AnalysisEnvironment.kt @@ -99,7 +99,7 @@ class AnalysisEnvironment(val messageCollector: MessageCollector) : Disposable { } - fun createResolutionFacade(environment: KotlinCoreEnvironment): DokkaResolutionFacade { + fun createResolutionFacade(environment: KotlinCoreEnvironment): Pair { val projectContext = ProjectContext(environment.project) val sourceFiles = environment.getSourceFiles() @@ -164,15 +164,17 @@ class AnalysisEnvironment(val messageCollector: MessageCollector) : Disposable { builtIns = builtIns ) - resolverForProject.resolverForModule(library) // Required before module to initialize library properly + val resolverForLibrary = resolverForProject.resolverForModule(library) // Required before module to initialize library properly val resolverForModule = resolverForProject.resolverForModule(module) + val libraryModuleDescriptor = resolverForProject.descriptorForModule(library) val moduleDescriptor = resolverForProject.descriptorForModule(module) builtIns.initialize(moduleDescriptor, true) + val libraryResolutionFacade = DokkaResolutionFacade(environment.project, libraryModuleDescriptor, resolverForLibrary) val created = DokkaResolutionFacade(environment.project, moduleDescriptor, resolverForModule) val projectComponentManager = environment.project as MockComponentManager projectComponentManager.registerService(KotlinCacheService::class.java, CoreKotlinCacheService(created)) - return created + return created to libraryResolutionFacade } fun loadLanguageVersionSettings(languageVersionString: String?, apiVersionString: String?) { diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index 646096e5..8b30a6b4 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -45,10 +45,16 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { private val refGraph: NodeReferenceGraph private val docParser: JavaDocumentationParser - @Inject constructor(options: DocumentationOptions, refGraph: NodeReferenceGraph, logger: DokkaLogger, signatureProvider: ElementSignatureProvider) { + @Inject constructor( + options: DocumentationOptions, + refGraph: NodeReferenceGraph, + logger: DokkaLogger, + signatureProvider: ElementSignatureProvider, + externalDocumentationLinkResolver: ExternalDocumentationLinkResolver + ) { this.options = options this.refGraph = refGraph - this.docParser = JavadocParser(refGraph, logger, signatureProvider) + this.docParser = JavadocParser(refGraph, logger, signatureProvider, externalDocumentationLinkResolver) } constructor(options: DocumentationOptions, refGraph: NodeReferenceGraph, docParser: JavaDocumentationParser) { diff --git a/core/src/main/kotlin/Java/JavadocParser.kt b/core/src/main/kotlin/Java/JavadocParser.kt index 5e23e357..e1b15cb2 100644 --- a/core/src/main/kotlin/Java/JavadocParser.kt +++ b/core/src/main/kotlin/Java/JavadocParser.kt @@ -26,7 +26,8 @@ interface JavaDocumentationParser { class JavadocParser( private val refGraph: NodeReferenceGraph, private val logger: DokkaLogger, - private val signatureProvider: ElementSignatureProvider + private val signatureProvider: ElementSignatureProvider, + private val externalDocumentationLinkResolver: ExternalDocumentationLinkResolver ) : JavaDocumentationParser { private fun ContentSection.appendTypeElement(signature: String, selector: (DocumentationNode) -> DocumentationNode?) { @@ -197,25 +198,41 @@ class JavadocParser( private fun MutableContent.convertSeeTag(tag: PsiDocTag) { val linkElement = tag.linkElement() ?: return val seeSection = findSectionByTag(ContentTags.SeeAlso) ?: addSection(ContentTags.SeeAlso, null) - val linkSignature = resolveLink(tag.referenceElement()) + + val valueElement = tag.referenceElement() + val externalLink = resolveExternalLink(valueElement) val text = ContentText(linkElement.text) - if (linkSignature != null) { - val linkNode = - ContentNodeLazyLink((tag.valueElement ?: linkElement).text, { -> refGraph.lookupOrWarn(linkSignature, logger) }) - linkNode.append(text) - seeSection.append(linkNode) - } else { - seeSection.append(text) + + val linkSignature by lazy { resolveInternalLink(valueElement) } + val node = when { + externalLink != null -> { + val linkNode = ContentExternalLink(externalLink) + linkNode.append(text) + linkNode + } + linkSignature != null -> { + val linkNode = + ContentNodeLazyLink( + (tag.valueElement ?: linkElement).text, + { -> refGraph.lookupOrWarn(linkSignature, logger) } + ) + linkNode.append(text) + linkNode + } + else -> text } + seeSection.append(node) } private fun convertInlineDocTag(tag: PsiInlineDocTag, element: PsiNamedElement) = when (tag.name) { "link", "linkplain" -> { val valueElement = tag.referenceElement() - val linkSignature = resolveLink(valueElement) - if (linkSignature != null) { + val externalLink = resolveExternalLink(valueElement) + val linkSignature by lazy { resolveInternalLink(valueElement) } + if (externalLink != null || linkSignature != null) { val labelText = tag.dataElements.firstOrNull { it is PsiDocToken }?.text ?: valueElement!!.text - val link = "${labelText.htmlEscape()}" + val linkTarget = if (externalLink != null) "href=\"$externalLink\"" else "docref=\"$linkSignature\"" + val link = "${labelText.htmlEscape()}" if (tag.name == "link") "$link" else link } else if (valueElement != null) { valueElement.text @@ -256,7 +273,15 @@ class JavadocParser( private fun PsiDocTag.linkElement(): PsiElement? = valueElement ?: dataElements.firstOrNull { it !is PsiWhiteSpace } - private fun resolveLink(valueElement: PsiElement?): String? { + private fun resolveExternalLink(valueElement: PsiElement?): String? { + val target = valueElement?.reference?.resolve() + if (target != null) { + return externalDocumentationLinkResolver.buildExternalDocumentationLink(target) + } + return null + } + + private fun resolveInternalLink(valueElement: PsiElement?): String? { val target = valueElement?.reference?.resolve() if (target != null) { return signatureProvider.signature(target) diff --git a/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt b/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt index 5f1118e8..7817da18 100644 --- a/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt +++ b/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt @@ -34,8 +34,9 @@ class DescriptorDocumentationParser val resolutionFacade: DokkaResolutionFacade, val refGraph: NodeReferenceGraph, val sampleService: SampleProcessingService, - val signatureProvider: KotlinElementSignatureProvider - ) + val signatureProvider: KotlinElementSignatureProvider, + val externalDocumentationLinkResolver: ExternalDocumentationLinkResolver +) { fun parseDocumentation(descriptor: DeclarationDescriptor, inline: Boolean = false): Content = parseDocumentationAndDetails(descriptor, inline).first @@ -131,7 +132,12 @@ class DescriptorDocumentationParser fun parseJavadoc(descriptor: DeclarationDescriptor): Pair Unit> { val psi = ((descriptor as? DeclarationDescriptorWithSource)?.source as? PsiSourceElement)?.psi if (psi is PsiDocCommentOwner) { - val parseResult = JavadocParser(refGraph, logger, signatureProvider).parseDocumentation(psi as PsiNamedElement) + val parseResult = JavadocParser( + refGraph, + logger, + signatureProvider, + externalDocumentationLinkResolver + ).parseDocumentation(psi as PsiNamedElement) return parseResult.content to { node -> parseResult.deprecatedContent?.let { val deprecationNode = DocumentationNode("", it, NodeKind.Modifier) diff --git a/core/src/main/kotlin/Kotlin/ExternalDocumentationLinkResolver.kt b/core/src/main/kotlin/Kotlin/ExternalDocumentationLinkResolver.kt index 7be37177..c766b869 100644 --- a/core/src/main/kotlin/Kotlin/ExternalDocumentationLinkResolver.kt +++ b/core/src/main/kotlin/Kotlin/ExternalDocumentationLinkResolver.kt @@ -2,6 +2,7 @@ package org.jetbrains.dokka import com.google.inject.Inject import com.google.inject.Singleton +import com.intellij.psi.PsiElement import com.intellij.psi.PsiMethod import com.intellij.util.io.* import org.jetbrains.dokka.Formats.FileGeneratorBasedFormatDescriptor @@ -10,10 +11,7 @@ import org.jetbrains.dokka.Utilities.ServiceLocator import org.jetbrains.dokka.Utilities.lookup import org.jetbrains.kotlin.descriptors.* import org.jetbrains.kotlin.descriptors.impl.EnumEntrySyntheticClassDescriptor -import org.jetbrains.kotlin.load.java.descriptors.JavaCallableMemberDescriptor -import org.jetbrains.kotlin.load.java.descriptors.JavaClassDescriptor -import org.jetbrains.kotlin.load.java.descriptors.JavaMethodDescriptor -import org.jetbrains.kotlin.load.java.descriptors.JavaPropertyDescriptor +import org.jetbrains.kotlin.load.java.descriptors.* import org.jetbrains.kotlin.name.FqName import org.jetbrains.kotlin.resolve.DescriptorUtils import org.jetbrains.kotlin.resolve.descriptorUtil.fqNameSafe @@ -25,6 +23,7 @@ import java.net.URL import java.net.URLConnection import java.nio.file.Path import java.security.MessageDigest +import javax.inject.Named import kotlin.reflect.full.findAnnotation fun ByteArray.toHexString() = this.joinToString(separator = "") { "%02x".format(it) } @@ -32,6 +31,7 @@ fun ByteArray.toHexString() = this.joinToString(separator = "") { "%02x".format( @Singleton class ExternalDocumentationLinkResolver @Inject constructor( val options: DocumentationOptions, + @Named("libraryResolutionFacade") val libraryResolutionFacade: DokkaResolutionFacade, val logger: DokkaLogger ) { @@ -166,6 +166,12 @@ class ExternalDocumentationLinkResolver @Inject constructor( } } + fun buildExternalDocumentationLink(element: PsiElement): String? { + return element.extractDescriptor(libraryResolutionFacade)?.let { + buildExternalDocumentationLink(it) + } + } + fun buildExternalDocumentationLink(symbol: DeclarationDescriptor): String? { val packageFqName: FqName = when (symbol) { diff --git a/core/src/main/kotlin/Kotlin/KotlinElementSignatureProvider.kt b/core/src/main/kotlin/Kotlin/KotlinElementSignatureProvider.kt index 0a377dc1..bcac0182 100644 --- a/core/src/main/kotlin/Kotlin/KotlinElementSignatureProvider.kt +++ b/core/src/main/kotlin/Kotlin/KotlinElementSignatureProvider.kt @@ -2,7 +2,6 @@ package org.jetbrains.dokka import com.intellij.psi.PsiElement import com.intellij.psi.PsiMember -import com.intellij.psi.PsiNameIdentifierOwner import com.intellij.psi.PsiPackage import org.jetbrains.kotlin.asJava.elements.KtLightElement import org.jetbrains.kotlin.descriptors.DeclarationDescriptor @@ -14,21 +13,22 @@ class KotlinElementSignatureProvider @Inject constructor( val resolutionFacade: DokkaResolutionFacade ) : ElementSignatureProvider { override fun signature(forPsi: PsiElement): String { - - val desc = when (forPsi) { - is KtLightElement<*, *> -> return signature(forPsi.kotlinOrigin!!) - is PsiPackage -> resolutionFacade.moduleDescriptor.getPackage(FqName(forPsi.qualifiedName)) - is PsiMember -> forPsi.getJavaOrKotlinMemberDescriptor(resolutionFacade) - else -> resolutionFacade.resolveSession.bindingContext[BindingContext.DECLARATION_TO_DESCRIPTOR, forPsi] - } - - if (desc == null && (forPsi as? PsiNameIdentifierOwner)?.name == "remove") { - (forPsi as? PsiMember)?.getJavaOrKotlinMemberDescriptor(resolutionFacade) - } - - return desc?.let { signature(it) } + return forPsi.extractDescriptor(resolutionFacade) + ?.let { signature(it) } ?: run { "no desc for $forPsi in ${(forPsi as? PsiMember)?.containingClass}" } } override fun signature(forDesc: DeclarationDescriptor): String = forDesc.signature() -} \ No newline at end of file +} + + +fun PsiElement.extractDescriptor(resolutionFacade: DokkaResolutionFacade): DeclarationDescriptor? { + val forPsi = this + + return when (forPsi) { + is KtLightElement<*, *> -> return (forPsi.kotlinOrigin!!).extractDescriptor(resolutionFacade) + is PsiPackage -> resolutionFacade.moduleDescriptor.getPackage(FqName(forPsi.qualifiedName)) + is PsiMember -> forPsi.getJavaOrKotlinMemberDescriptor(resolutionFacade) + else -> resolutionFacade.resolveSession.bindingContext[BindingContext.DECLARATION_TO_DESCRIPTOR, forPsi] + } +} diff --git a/core/src/main/kotlin/Utilities/DokkaModules.kt b/core/src/main/kotlin/Utilities/DokkaModules.kt index 907d5ca7..732cbc48 100644 --- a/core/src/main/kotlin/Utilities/DokkaModules.kt +++ b/core/src/main/kotlin/Utilities/DokkaModules.kt @@ -24,8 +24,9 @@ class DokkaAnalysisModule(val environment: AnalysisEnvironment, val coreEnvironment = environment.createCoreEnvironment() binder.bind().toInstance(coreEnvironment) - val dokkaResolutionFacade = environment.createResolutionFacade(coreEnvironment) + val (dokkaResolutionFacade, libraryResolutionFacade) = environment.createResolutionFacade(coreEnvironment) binder.bind().toInstance(dokkaResolutionFacade) + binder.bind().annotatedWith(Names.named("libraryResolutionFacade")).toInstance(libraryResolutionFacade) binder.bind().toInstance(options) -- cgit From 9715d6300d6e0082a3e900c7e5cff873b8c294f2 Mon Sep 17 00:00:00 2001 From: Simon Ogorodnik Date: Sat, 26 May 2018 00:12:38 +0300 Subject: Provide signature for packages --- core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt | 1 + 1 file changed, 1 insertion(+) (limited to 'core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt') diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index 8b30a6b4..6d5825e9 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -14,6 +14,7 @@ import org.jetbrains.kotlin.psi.KtModifierListOwner import java.io.File fun getSignature(element: PsiElement?) = when(element) { + is PsiPackage -> element.qualifiedName is PsiClass -> element.qualifiedName is PsiField -> element.containingClass!!.qualifiedName + "$" + element.name is PsiMethod -> -- cgit From 633fda36403e8c5483054737d285dd01b5c190bb Mon Sep 17 00:00:00 2001 From: Simon Ogorodnik Date: Sat, 26 May 2018 00:15:47 +0300 Subject: KT-24025: Support constants in as java mode #KT-24025 fixed --- .../main/kotlin/Java/JavaPsiDocumentationBuilder.kt | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) (limited to 'core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt') diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index 6d5825e9..9eabc227 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -1,7 +1,9 @@ package org.jetbrains.dokka import com.google.inject.Inject +import com.intellij.openapi.util.text.StringUtil import com.intellij.psi.* +import com.intellij.psi.impl.JavaConstantExpressionEvaluator import com.intellij.psi.util.InheritanceUtil import com.intellij.psi.util.PsiTreeUtil import org.jetbrains.kotlin.asJava.elements.KtLightDeclaration @@ -207,11 +209,28 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { fun PsiField.build(): DocumentationNode { val node = nodeForElement(this, nodeKind()) node.appendType(type) - node.appendModifiers(this) + + node.appendConstantValueIfAny(this) register(this, node) return node } + private fun DocumentationNode.appendConstantValueIfAny(field: PsiField) { + val modifierList = field.modifierList ?: return + val initializer = field.initializer ?: return + if (field.type is PsiPrimitiveType && + modifierList.hasExplicitModifier(PsiModifier.FINAL) && + modifierList.hasExplicitModifier(PsiModifier.STATIC)) { + val value = JavaConstantExpressionEvaluator.computeConstantExpression(initializer, false) + val text = when(value) { + is String -> + "\"" + StringUtil.escapeStringCharacters(value) + "\"" + else -> value.toString() + } + append(DocumentationNode(text, Content.Empty, NodeKind.Value), RefKind.Detail) + } + } + private fun PsiField.nodeKind(): NodeKind = when { this is PsiEnumConstant -> NodeKind.EnumItem else -> NodeKind.Field -- cgit From 0485472951134685c434d148b6fe5b6393217023 Mon Sep 17 00:00:00 2001 From: Simon Ogorodnik Date: Sat, 9 Jun 2018 23:51:43 +0300 Subject: KT-24032: Fix parameter rendering in asJava mode #KT-24032 fixed --- core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt | 12 +++++++----- core/src/main/kotlin/Languages/NewJavaLanguageService.kt | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) (limited to 'core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt') diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index 9eabc227..332afffb 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -148,11 +148,13 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { hasSuppressDocTag(element) || skipElementBySuppressedFiles(element) - private fun skipElementByVisibility(element: Any): Boolean = element is PsiModifierListOwner && - !(options.effectivePackageOptions((element.containingFile as? PsiJavaFile)?.packageName ?: "").includeNonPublic) && - (element.hasModifierProperty(PsiModifier.PRIVATE) || - element.hasModifierProperty(PsiModifier.PACKAGE_LOCAL) || - element.isInternal()) + private fun skipElementByVisibility(element: Any): Boolean = + element is PsiModifierListOwner && + element !is PsiParameter && + !(options.effectivePackageOptions((element.containingFile as? PsiJavaFile)?.packageName ?: "").includeNonPublic) && + (element.hasModifierProperty(PsiModifier.PRIVATE) || + element.hasModifierProperty(PsiModifier.PACKAGE_LOCAL) || + element.isInternal()) private fun skipElementBySuppressedFiles(element: Any): Boolean = element is PsiElement && File(element.containingFile.virtualFile.path).absoluteFile in options.suppressedFiles diff --git a/core/src/main/kotlin/Languages/NewJavaLanguageService.kt b/core/src/main/kotlin/Languages/NewJavaLanguageService.kt index fa9f70fd..992cd090 100644 --- a/core/src/main/kotlin/Languages/NewJavaLanguageService.kt +++ b/core/src/main/kotlin/Languages/NewJavaLanguageService.kt @@ -20,7 +20,7 @@ class NewJavaLanguageService : CommonLanguageService() { NodeKind.TypeParameter -> renderTypeParameter(node) NodeKind.Type, NodeKind.UpperBound -> renderType(node) - + NodeKind.Parameter -> renderParameter(node) NodeKind.Constructor, NodeKind.Function -> renderFunction(node) NodeKind.Property -> renderProperty(node) -- cgit From b0310f8f3e242ffc64c56e8fd95710b25b37dfff Mon Sep 17 00:00:00 2001 From: Simon Ogorodnik Date: Fri, 23 Nov 2018 19:50:49 +0300 Subject: Fix constant values for Java --- .../main/kotlin/Java/JavaPsiDocumentationBuilder.kt | 4 ++-- core/src/main/kotlin/Kotlin/DocumentationBuilder.kt | 19 +++++-------------- core/src/test/kotlin/model/KotlinAsJavaTest.kt | 20 ++++++++++++++++++++ core/testdata/java/constants.java | 5 +++++ 4 files changed, 32 insertions(+), 16 deletions(-) create mode 100644 core/testdata/java/constants.java (limited to 'core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt') diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index 332afffb..f0b3a56b 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -220,11 +220,11 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { private fun DocumentationNode.appendConstantValueIfAny(field: PsiField) { val modifierList = field.modifierList ?: return val initializer = field.initializer ?: return - if (field.type is PsiPrimitiveType && - modifierList.hasExplicitModifier(PsiModifier.FINAL) && + if (modifierList.hasExplicitModifier(PsiModifier.FINAL) && modifierList.hasExplicitModifier(PsiModifier.STATIC)) { val value = JavaConstantExpressionEvaluator.computeConstantExpression(initializer, false) val text = when(value) { + null -> return // No value found is String -> "\"" + StringUtil.escapeStringCharacters(value) + "\"" else -> value.toString() diff --git a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt index f1b8e3d3..e15006cd 100644 --- a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt +++ b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt @@ -2,7 +2,6 @@ package org.jetbrains.dokka import com.google.inject.Inject import com.intellij.openapi.util.text.StringUtil -import com.intellij.psi.PsiField import com.intellij.psi.PsiJavaFile import org.jetbrains.dokka.DokkaConfiguration.* import org.jetbrains.dokka.Kotlin.DescriptorDocumentationParser @@ -23,7 +22,6 @@ 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.KtVariableDeclaration import org.jetbrains.kotlin.resolve.DescriptorUtils import org.jetbrains.kotlin.resolve.constants.ConstantValue import org.jetbrains.kotlin.resolve.descriptorUtil.* @@ -792,13 +790,7 @@ class DocumentationBuilder } if (isConst) { - val psi = sourcePsi() - val valueText = when (psi) { - is KtVariableDeclaration -> psi.initializer?.text - is PsiField -> psi.initializer?.text - else -> null - } - valueText?.let { node.appendTextNode(it, NodeKind.Value) } + this.compileTimeInitializer?.toDocumentationNode()?.let { node.append(it, RefKind.Detail) } } @@ -922,8 +914,8 @@ class DocumentationBuilder return node } - fun ConstantValue<*>.toDocumentationNode(): DocumentationNode? = value?.let { value -> - when (value) { + fun ConstantValue<*>.toDocumentationNode(): DocumentationNode? = value.let { value -> + val text = when (value) { is String -> "\"" + StringUtil.escapeStringCharacters(value) + "\"" is EnumEntrySyntheticClassDescriptor -> @@ -936,10 +928,9 @@ class DocumentationBuilder value.toString() } } - else -> value.toString() - }.let { valueString -> - DocumentationNode(valueString, Content.Empty, NodeKind.Value) + else -> "$value" } + DocumentationNode(text, Content.Empty, NodeKind.Value) } diff --git a/core/src/test/kotlin/model/KotlinAsJavaTest.kt b/core/src/test/kotlin/model/KotlinAsJavaTest.kt index d24d8bdd..22818038 100644 --- a/core/src/test/kotlin/model/KotlinAsJavaTest.kt +++ b/core/src/test/kotlin/model/KotlinAsJavaTest.kt @@ -2,6 +2,8 @@ package org.jetbrains.dokka.tests import org.jetbrains.dokka.DocumentationModule import org.jetbrains.dokka.NodeKind +import org.jetbrains.dokka.RefKind +import org.junit.Assert import org.junit.Test import org.junit.Assert.assertEquals @@ -27,6 +29,24 @@ class KotlinAsJavaTest { assertEquals("doc", getter.content.summary.toTestString()) } } + + + @Test fun constants() { + verifyModelAsJava("testdata/java/constants.java") { cls -> + selectNodes(cls) { + subgraphOf(RefKind.Member) + matching { it.name == "constStr" || it.name == "refConst" } + }.forEach { + assertEquals("In $it", "\"some value\"", it.detailOrNull(NodeKind.Value)?.name) + } + val nullConstNode = selectNodes(cls) { + subgraphOf(RefKind.Member) + withName("nullConst") + }.single() + + Assert.assertNull(nullConstNode.detailOrNull(NodeKind.Value)) + } + } } fun verifyModelAsJava(source: String, diff --git a/core/testdata/java/constants.java b/core/testdata/java/constants.java new file mode 100644 index 00000000..26f16639 --- /dev/null +++ b/core/testdata/java/constants.java @@ -0,0 +1,5 @@ +public class Constants { + public static final String constStr = "some value"; + public static final Object nullConst = null; + public static final String refConst = constStr; +} \ No newline at end of file -- cgit From 61b126692bb2ede06911ae1c493e8417f0bbe49d Mon Sep 17 00:00:00 2001 From: Kamil Doległo Date: Mon, 11 Mar 2019 17:11:50 +0100 Subject: Allow linking arguments with methods, change link label (#431) * Add PsiParameter to link arguments with methods, change link label --- core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt | 12 ++++++++++-- core/src/main/kotlin/Model/Content.kt | 5 +++++ core/src/main/kotlin/javadoc/tags.kt | 2 +- core/src/test/kotlin/javadoc/JavadocTest.kt | 12 ++++++++++++ core/testdata/javadoc/argumentReference.kt | 4 ++++ 5 files changed, 32 insertions(+), 3 deletions(-) create mode 100644 core/testdata/javadoc/argumentReference.kt (limited to 'core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt') diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index f0b3a56b..1ef601d3 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -20,11 +20,19 @@ fun getSignature(element: PsiElement?) = when(element) { is PsiClass -> element.qualifiedName is PsiField -> element.containingClass!!.qualifiedName + "$" + element.name is PsiMethod -> - element.containingClass!!.qualifiedName + "$" + element.name + "(" + - element.parameterList.parameters.map { it.type.typeSignature() }.joinToString(",") + ")" + methodSignature(element) + is PsiParameter -> { + val method = (element.parent.parent as PsiMethod) + methodSignature(method) + } else -> null } +private fun methodSignature(method: PsiMethod): String { + return method.containingClass!!.qualifiedName + "$" + method.name + "(" + + method.parameterList.parameters.map { it.type.typeSignature() }.joinToString(",") + ")" +} + private fun PsiType.typeSignature(): String = when(this) { is PsiArrayType -> "Array((${componentType.typeSignature()}))" is PsiPrimitiveType -> "kotlin." + canonicalText.capitalize() diff --git a/core/src/main/kotlin/Model/Content.kt b/core/src/main/kotlin/Model/Content.kt index 87a8023a..c142f4a4 100644 --- a/core/src/main/kotlin/Model/Content.kt +++ b/core/src/main/kotlin/Model/Content.kt @@ -115,6 +115,7 @@ class ContentBlockSampleCode(language: String = "kotlin", val importsBlock: Cont abstract class ContentNodeLink() : ContentBlock() { abstract val node: DocumentationNode? + abstract val text: String? } object ContentHardLineBreak : ContentNode { @@ -128,6 +129,8 @@ class ContentNodeDirectLink(override val node: DocumentationNode): ContentNodeLi override fun hashCode(): Int = children.hashCode() * 31 + node.name.hashCode() + + override val text: String? = null } class ContentNodeLazyLink(val linkText: String, val lazyNode: () -> DocumentationNode?): ContentNodeLink() { @@ -138,6 +141,8 @@ class ContentNodeLazyLink(val linkText: String, val lazyNode: () -> Documentatio override fun hashCode(): Int = children.hashCode() * 31 + linkText.hashCode() + + override val text: String? = linkText } class ContentExternalLink(val href : String) : ContentBlock() { diff --git a/core/src/main/kotlin/javadoc/tags.kt b/core/src/main/kotlin/javadoc/tags.kt index 05d98b71..99c9bfff 100644 --- a/core/src/main/kotlin/javadoc/tags.kt +++ b/core/src/main/kotlin/javadoc/tags.kt @@ -71,7 +71,7 @@ class SeeMethodTagAdapter(holder: Doc, val method: MethodAdapter, content: Conte override fun referencedPackage(): PackageDoc? = null override fun referencedClass(): ClassDoc? = method.containingClass() override fun referencedClassName(): String = method.containingClass()?.name() ?: "" - override fun label(): String = "${method.containingClass()?.name()}.${method.name()}" + override fun label(): String = content.text ?: "${method.containingClass()?.name()}.${method.name()}" override fun inlineTags(): Array = emptyArray() // TODO override fun firstSentenceTags(): Array = inlineTags() // TODO diff --git a/core/src/test/kotlin/javadoc/JavadocTest.kt b/core/src/test/kotlin/javadoc/JavadocTest.kt index 3e5b5ff8..6adbe7a0 100644 --- a/core/src/test/kotlin/javadoc/JavadocTest.kt +++ b/core/src/test/kotlin/javadoc/JavadocTest.kt @@ -259,6 +259,18 @@ class JavadocTest { } } + @Test + fun testArgumentReference() { + verifyJavadoc("testdata/javadoc/argumentReference.kt") { doc -> + val classDoc = doc.classNamed("ArgumentReferenceKt")!! + val method = classDoc.methods().first() + val tag = method.seeTags().first() + assertEquals("argNamedError", tag.referencedMemberName()) + assertEquals("error", tag.label()) + } + } + + private fun verifyJavadoc(name: String, withJdk: Boolean = false, withKotlinRuntime: Boolean = false, diff --git a/core/testdata/javadoc/argumentReference.kt b/core/testdata/javadoc/argumentReference.kt new file mode 100644 index 00000000..ac3104e9 --- /dev/null +++ b/core/testdata/javadoc/argumentReference.kt @@ -0,0 +1,4 @@ +/** + * [error] + */ +fun argNamedError(error: String) {} \ No newline at end of file -- cgit From 52b303d4251d54ddf9f09330f902621689a50f5d Mon Sep 17 00:00:00 2001 From: Krystian Ujma Date: Mon, 11 Mar 2019 17:12:44 +0100 Subject: Fix not null annotation java-as-html bug (#442) --- core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt') diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index 1ef601d3..e26fa13e 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -311,7 +311,7 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { } fun PsiAnnotation.build(): DocumentationNode { - val node = DocumentationNode(nameReferenceElement?.text ?: "", Content.Empty, NodeKind.Annotation) + val node = DocumentationNode(qualifiedName?.substringAfterLast(".") ?: "", Content.Empty, NodeKind.Annotation) parameterList.attributes.forEach { val parameter = DocumentationNode(it.name ?: "value", Content.Empty, NodeKind.Parameter) val value = it.value -- cgit From 69eefa767ccf692297cbdb9dc44240a4fa67aa3c Mon Sep 17 00:00:00 2001 From: Simon Ogorodnik Date: Wed, 13 Mar 2019 16:30:07 +0300 Subject: Fix nullability annotations in javadoc #446 fixed --- .../kotlin/Java/JavaPsiDocumentationBuilder.kt | 27 +++++++++++++++++++--- core/src/main/kotlin/Model/DocumentationNode.kt | 23 ++++++++++-------- core/src/main/kotlin/javadoc/docbase.kt | 5 +++- 3 files changed, 41 insertions(+), 14 deletions(-) (limited to 'core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt') diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt index e26fa13e..f1f170d7 100644 --- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt +++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt @@ -6,6 +6,7 @@ import com.intellij.psi.* import com.intellij.psi.impl.JavaConstantExpressionEvaluator import com.intellij.psi.util.InheritanceUtil import com.intellij.psi.util.PsiTreeUtil +import org.jetbrains.kotlin.asJava.elements.KtLightAbstractAnnotation import org.jetbrains.kotlin.asJava.elements.KtLightDeclaration import org.jetbrains.kotlin.asJava.elements.KtLightElement import org.jetbrains.kotlin.kdoc.parser.KDocKnownTag @@ -109,9 +110,11 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { fun nodeForElement(element: PsiNamedElement, kind: NodeKind, - name: String = element.name ?: ""): DocumentationNode { + name: String = element.name ?: "", + register: Boolean = false): DocumentationNode { val (docComment, deprecatedContent) = docParser.parseDocumentation(element) val node = DocumentationNode(name, docComment, kind) + if (register) register(element, node) if (element is PsiModifierListOwner) { node.appendModifiers(element) val modifierList = element.modifierList @@ -180,13 +183,13 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { fun PsiClass.build(): DocumentationNode { val kind = when { + isAnnotationType -> NodeKind.AnnotationClass isInterface -> NodeKind.Interface isEnum -> NodeKind.Enum - isAnnotationType -> NodeKind.AnnotationClass isException() -> NodeKind.Exception else -> NodeKind.Class } - val node = nodeForElement(this, kind) + val node = nodeForElement(this, kind, register = isAnnotationType) superTypes.filter { !ignoreSupertype(it) }.forEach { node.appendType(it, NodeKind.Supertype) val superClass = it.resolve() @@ -310,8 +313,26 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder { return node } + private fun lookupOrBuildClass(psiClass: PsiClass): DocumentationNode { + val existing = refGraph.lookup(getSignature(psiClass)!!) + if (existing != null) return existing + val new = psiClass.build() + val packageNode = findOrCreatePackageNode(null, (psiClass.parent as PsiJavaFile).packageName, emptyMap(), refGraph) + packageNode.append(new, RefKind.Member) + return new + } + fun PsiAnnotation.build(): DocumentationNode { + + val original = when (this) { + is KtLightAbstractAnnotation -> clsDelegate + else -> this + } val node = DocumentationNode(qualifiedName?.substringAfterLast(".") ?: "", Content.Empty, NodeKind.Annotation) + 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 value = it.value diff --git a/core/src/main/kotlin/Model/DocumentationNode.kt b/core/src/main/kotlin/Model/DocumentationNode.kt index a3388031..ad7801f2 100644 --- a/core/src/main/kotlin/Model/DocumentationNode.kt +++ b/core/src/main/kotlin/Model/DocumentationNode.kt @@ -179,17 +179,20 @@ val DocumentationNode.path: List } fun findOrCreatePackageNode(module: DocumentationNode?, packageName: String, packageContent: Map, refGraph: NodeReferenceGraph): DocumentationNode { - val existingNode = refGraph.lookup(packageName) - if (existingNode != null) { - return existingNode - } - val newNode = DocumentationNode(packageName, + val node = refGraph.lookup(packageName) ?: run { + val newNode = DocumentationNode( + packageName, packageContent.getOrElse(packageName) { Content.Empty }, - NodeKind.Package) + NodeKind.Package + ) - refGraph.register(packageName, newNode) - module?.append(newNode, RefKind.Member) - return newNode + refGraph.register(packageName, newNode) + newNode + } + if (module != null && node !in module.members) { + module.append(node, RefKind.Member) + } + return node } fun DocumentationNode.append(child: DocumentationNode, kind: RefKind) { @@ -215,7 +218,7 @@ fun DocumentationNode.qualifiedName(): String { } else if (kind == NodeKind.Package) { return name } - return path.drop(1).map { it.name }.filter { it.length > 0 }.joinToString(".") + return path.dropWhile { it.kind == NodeKind.Module }.map { it.name }.filter { it.isNotEmpty() }.joinToString(".") } fun DocumentationNode.simpleName() = name.substringAfterLast('.') diff --git a/core/src/main/kotlin/javadoc/docbase.kt b/core/src/main/kotlin/javadoc/docbase.kt index fbf8c464..118b134a 100644 --- a/core/src/main/kotlin/javadoc/docbase.kt +++ b/core/src/main/kotlin/javadoc/docbase.kt @@ -114,7 +114,7 @@ class AnnotationTypeDocAdapter(module: ModuleNodeAdapter, node: DocumentationNod } class AnnotationDescAdapter(val module: ModuleNodeAdapter, val node: DocumentationNode) : AnnotationDesc { - override fun annotationType(): AnnotationTypeDoc? = AnnotationTypeDocAdapter(module, node) // TODO ????? + override fun annotationType(): AnnotationTypeDoc? = AnnotationTypeDocAdapter(module, node.links.find { it.kind == NodeKind.AnnotationClass } ?: node) // TODO ????? override fun isSynthesized(): Boolean = false override fun elementValues(): Array? = emptyArray() // TODO } @@ -411,6 +411,9 @@ open class ClassDocumentationNodeAdapter(module: ModuleNodeAdapter, val classNod return classNode.simpleName() } + override fun qualifiedName(): String? { + return super.qualifiedName() + } override fun constructors(filter: Boolean): Array = classNode.members(NodeKind.Constructor).map { ConstructorAdapter(module, it) }.toTypedArray() override fun constructors(): Array = constructors(true) override fun importedPackages(): Array = emptyArray() -- cgit