From f45750699d089e0101dcde5d38c7e08ec2f03708 Mon Sep 17 00:00:00 2001 From: irina-turova <31963497+irina-turova@users.noreply.github.com> Date: Wed, 31 May 2023 16:16:10 +0500 Subject: Add support for `@author`, `@since`, `@return` Javadoc tags (#2967) --- .../jetbrains/dokka/javadoc/JavadocPageCreator.kt | 32 ++++++++++++++++++---- .../dokka/javadoc/pages/JavadocPageNodes.kt | 13 +++++++++ .../JavadocContentToTemplateMapTranslator.kt | 4 +++ 3 files changed, 44 insertions(+), 5 deletions(-) (limited to 'plugins/javadoc/src/main/kotlin/org') diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt index 80814103..616583c8 100644 --- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt +++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt @@ -7,10 +7,7 @@ import org.jetbrains.dokka.base.transformers.pages.comments.DocTagToContentConve import org.jetbrains.dokka.base.translators.documentables.firstSentenceBriefFromContentNodes import org.jetbrains.dokka.javadoc.pages.* import org.jetbrains.dokka.model.* -import org.jetbrains.dokka.model.doc.Description -import org.jetbrains.dokka.model.doc.Index -import org.jetbrains.dokka.model.doc.Param -import org.jetbrains.dokka.model.doc.TagWrapper +import org.jetbrains.dokka.model.doc.* import org.jetbrains.dokka.model.properties.PropertyContainer import org.jetbrains.dokka.model.properties.WithExtraProperties import org.jetbrains.dokka.pages.* @@ -68,9 +65,11 @@ open class JavadocPageCreator(context: DokkaContext) { it.name, signatureForNode(it, jvm), it.descriptionToContentNodes(jvm), - PropertyContainer.withAll(it.indexesInDocumentation()) + PropertyContainer.withAll(it.indexesInDocumentation()), ) }, + sinceTagContent = c.sinceToContentNodes(jvm), + authorTagContent = c.authorsToContentNodes(jvm), documentables = listOf(c), children = children, extra = extra + c.indexesInDocumentation() @@ -165,6 +164,8 @@ open class JavadocPageCreator(context: DokkaContext) { ) } }, + returnTagContent = returnToContentNodes(jvm), + sinceTagContent = sinceToContentNodes(jvm), extra = extra + indexesInDocumentation() ) } @@ -177,6 +178,9 @@ open class JavadocPageCreator(context: DokkaContext) { private inline fun Documentable.findNodeInDocumentation(sourceSetData: DokkaSourceSet?): T? = documentation[sourceSetData]?.firstChildOfTypeOrNull() + private inline fun Documentable.findAllNodesInDocumentation(sourceSetData: DokkaSourceSet?): List = + documentation[sourceSetData]?.childrenOfType() ?: emptyList() + private fun Documentable.descriptionToContentNodes(sourceSet: DokkaSourceSet? = highestJvmSourceSet) = contentNodesFromType(sourceSet) @@ -192,6 +196,15 @@ open class JavadocPageCreator(context: DokkaContext) { ) }.orEmpty() + private inline fun Documentable.allContentNodesFromType(sourceSet: DokkaSourceSet?) = + findAllNodesInDocumentation(sourceSet).map { + DocTagToContentConverter().buildContent( + it.root, + DCI(setOf(dri), JavadocContentKind.OverviewSummary), + sourceSets.toSet() + ) + } + fun List.nodeForJvm(jvm: DokkaSourceSet): ContentNode = firstOrNull { jvm.sourceSetID in it.sourceSets.sourceSetIDs } ?: throw IllegalStateException("No source set found for ${jvm.sourceSetID} ") @@ -228,5 +241,14 @@ open class JavadocPageCreator(context: DokkaContext) { } ) } + + private fun Documentable.authorsToContentNodes(sourceSet: DokkaSourceSet? = highestJvmSourceSet) = + allContentNodesFromType(sourceSet) + + private fun Documentable.sinceToContentNodes(sourceSet: DokkaSourceSet? = highestJvmSourceSet) = + allContentNodesFromType(sourceSet) + + private fun Documentable.returnToContentNodes(sourceSet: DokkaSourceSet? = highestJvmSourceSet) = + contentNodesFromType(sourceSet) } 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 cafc6c3e..8210b30a 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 @@ -149,6 +149,7 @@ data class JavadocPropertyNode( override val name: String, val signature: JavadocSignatureContentNode, override val brief: List, + override val extra: PropertyContainer = PropertyContainer.empty() ) : AnchorableJavadocNode(name, dri), WithJavadocExtra, WithBrief @@ -157,6 +158,10 @@ data class JavadocFunctionNode( override val brief: List, val description: List, val parameters: List, + + val returnTagContent: List, + val sinceTagContent: List>, + override val name: String, override val dri: DRI, override val extra: PropertyContainer = PropertyContainer.empty() @@ -182,6 +187,10 @@ class JavadocClasslikePageNode( val classlikes: List, val properties: List, override val brief: List, + + val sinceTagContent: List>, + val authorTagContent: List>, + override val documentables: List = emptyList(), override val children: List = emptyList(), override val embeddedResources: List = listOf(), @@ -215,6 +224,8 @@ class JavadocClasslikePageNode( classlikes, properties, brief, + sinceTagContent, + authorTagContent, documentables, children, embeddedResources, @@ -240,6 +251,8 @@ class JavadocClasslikePageNode( classlikes, properties, brief, + sinceTagContent, + authorTagContent, documentables, children, embeddedResources, 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 45fa3f2e..6a590bc7 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 @@ -122,6 +122,8 @@ internal class JavadocContentToTemplateMapTranslator( "description" to htmlForContentNodes(node.description,contextNode), "parameters" to node.parameters.map { templateMapForParameterNode(it) }, "inlineParameters" to node.parameters.joinToString { renderInlineParameter(it) }, + "returnTagContent" to htmlForContentNodes(node.returnTagContent, contextNode), + "sinceTagContent" to node.sinceTagContent.map { htmlForContentNodes(it, contextNode) }, "anchorLink" to node.getAnchor(), "signature" to templateMapForSignatureNode(node.signature), "name" to node.name @@ -137,6 +139,8 @@ internal class JavadocContentToTemplateMapTranslator( "properties" to node.properties.map { templateMapForPropertyNode(it) }, "classlikes" to node.classlikes.map { templateMapForNestedClasslikeNode(it) }, "implementedInterfaces" to templateMapForImplementedInterfaces(node).sorted(), + "sinceTagContent" to node.sinceTagContent.map { htmlForContentNodes(it, contextNode) }, + "authorTagContent" to node.authorTagContent.map { htmlForContentNodes(it, contextNode) }, "kind" to node.kind, "packageName" to node.packageName, "name" to node.name -- cgit