Add support for `@author`, `@since`, `@return` Javadoc tags (#2967)

3 files changed, 44 insertions, 5 deletions

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 <reified T : TagWrapper> Documentable.findNodeInDocumentation(sourceSetData: DokkaSourceSet?): T? =
         documentation[sourceSetData]?.firstChildOfTypeOrNull<T>()
 
+    private inline fun <reified T : TagWrapper> Documentable.findAllNodesInDocumentation(sourceSetData: DokkaSourceSet?): List<T> =
+        documentation[sourceSetData]?.childrenOfType<T>() ?: emptyList()
+
     private fun Documentable.descriptionToContentNodes(sourceSet: DokkaSourceSet? = highestJvmSourceSet) =
         contentNodesFromType<Description>(sourceSet)
 
@@ -192,6 +196,15 @@ open class JavadocPageCreator(context: DokkaContext) {
             )
         }.orEmpty()
 
+    private inline fun <reified T : TagWrapper> Documentable.allContentNodesFromType(sourceSet: DokkaSourceSet?) =
+        findAllNodesInDocumentation<T>(sourceSet).map {
+            DocTagToContentConverter().buildContent(
+                it.root,
+                DCI(setOf(dri), JavadocContentKind.OverviewSummary),
+                sourceSets.toSet()
+            )
+        }
+
     fun List<ContentNode>.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<Author>(sourceSet)
+
+    private fun Documentable.sinceToContentNodes(sourceSet: DokkaSourceSet? = highestJvmSourceSet) =
+        allContentNodesFromType<Since>(sourceSet)
+
+    private fun Documentable.returnToContentNodes(sourceSet: DokkaSourceSet? = highestJvmSourceSet) =
+        contentNodesFromType<Return>(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<ContentNode>,
+
     override val extra: PropertyContainer<DProperty> = PropertyContainer.empty()
 ) : AnchorableJavadocNode(name, dri), WithJavadocExtra<DProperty>, WithBrief
 
@@ -157,6 +158,10 @@ data class JavadocFunctionNode(
     override val brief: List<ContentNode>,
     val description: List<ContentNode>,
     val parameters: List<JavadocParameterNode>,
+
+    val returnTagContent: List<ContentNode>,
+    val sinceTagContent: List<List<ContentNode>>,
+
     override val name: String,
     override val dri: DRI,
     override val extra: PropertyContainer<DFunction> = PropertyContainer.empty()
@@ -182,6 +187,10 @@ class JavadocClasslikePageNode(
     val classlikes: List<JavadocClasslikePageNode>,
     val properties: List<JavadocPropertyNode>,
     override val brief: List<ContentNode>,
+
+    val sinceTagContent: List<List<ContentNode>>,
+    val authorTagContent: List<List<ContentNode>>,
+
     override val documentables: List<Documentable> = emptyList(),
     override val children: List<PageNode> = emptyList(),
     override val embeddedResources: List<String> = 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