Add basic support of @author, @SInCE, @return tags for methods and cl…

…asses for javadoc (Kotlin#1770)
irina-turova · Apr 17, 2023 · 3ddeb4e · 3ddeb4e
1 parent 21afcb4
commit 3ddeb4e
Show file tree

Hide file tree

Showing 9 changed files with 236 additions and 24 deletions.
diff --git a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt
@@ -168,6 +168,15 @@ class JavadocParser(
                 )
             )
 
+            JavadocTag.SINCE -> Since(
+                wrapTagIfNecessary(
+                    convertJavadocElements(
+                        tag.contentElementsWithSiblingIfNeeded(),
+                        context = resolutionContext
+                    )
+                )
+            )
+
             else -> emptyTagWrapper(tag, docComment)
         }
     }

diff --git a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocTag.kt b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocTag.kt
@@ -1,7 +1,7 @@
 package org.jetbrains.dokka.base.translators.psi.parsers
 
 internal enum class JavadocTag {
-    PARAM, THROWS, RETURN, AUTHOR, SEE, DEPRECATED, EXCEPTION, HIDE,
+    PARAM, THROWS, RETURN, AUTHOR, SEE, DEPRECATED, EXCEPTION, HIDE, SINCE,
 
     /**
      * Artificial tag created to handle tag-less section

diff --git a/plugins/javadoc/api/javadoc.api b/plugins/javadoc/api/javadoc.api
@@ -177,11 +177,12 @@ public final class org/jetbrains/dokka/javadoc/pages/JavaContentGroupBuilder {
 	public final fun getSourceSets ()Ljava/util/Set;
 }
 
-public final class org/jetbrains/dokka/javadoc/pages/JavadocClasslikePageNode : org/jetbrains/dokka/javadoc/pages/JavadocPageNode, org/jetbrains/dokka/javadoc/pages/NavigableJavadocNode, org/jetbrains/dokka/javadoc/pages/WithBrief, org/jetbrains/dokka/javadoc/pages/WithJavadocExtra, org/jetbrains/dokka/javadoc/pages/WithNavigable, org/jetbrains/dokka/pages/ClasslikePage {
-	public fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/javadoc/pages/JavadocContentNode;Ljava/util/Set;Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)V
-	public synthetic fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/javadoc/pages/JavadocContentNode;Ljava/util/Set;Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+public final class org/jetbrains/dokka/javadoc/pages/JavadocClasslikePageNode : org/jetbrains/dokka/javadoc/pages/JavadocPageNode, org/jetbrains/dokka/javadoc/pages/NavigableJavadocNode, org/jetbrains/dokka/javadoc/pages/WithBrief, org/jetbrains/dokka/javadoc/pages/WithCommonTags, org/jetbrains/dokka/javadoc/pages/WithJavadocExtra, org/jetbrains/dokka/javadoc/pages/WithNavigable, org/jetbrains/dokka/pages/ClasslikePage {
+	public fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/javadoc/pages/JavadocContentNode;Ljava/util/Set;Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)V
+	public synthetic fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/javadoc/pages/JavadocContentNode;Ljava/util/Set;Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun getAllNavigables ()Ljava/util/List;
 	public final fun getAnchorables ()Ljava/util/List;
+	public fun getAuthors ()Ljava/util/List;
 	public fun getBrief ()Ljava/util/List;
 	public fun getChildren ()Ljava/util/List;
 	public final fun getClasslikes ()Ljava/util/List;
@@ -203,6 +204,7 @@ public final class org/jetbrains/dokka/javadoc/pages/JavadocClasslikePageNode :
 	public final fun getPackageName ()Ljava/lang/String;
 	public final fun getProperties ()Ljava/util/List;
 	public final fun getSignature ()Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;
+	public fun getSince ()Ljava/util/List;
 	public fun modified (Ljava/lang/String;Ljava/util/List;)Lorg/jetbrains/dokka/pages/PageNode;
 	public fun modified (Ljava/lang/String;Lorg/jetbrains/dokka/pages/ContentNode;Ljava/util/Set;Ljava/util/List;Ljava/util/List;)Lorg/jetbrains/dokka/pages/ContentPage;
 	public synthetic fun withNewExtras (Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Ljava/lang/Object;
@@ -292,26 +294,32 @@ public final class org/jetbrains/dokka/javadoc/pages/JavadocEntryNode : org/jetb
 	public synthetic fun withNewExtras (Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Lorg/jetbrains/dokka/model/Documentable;
 }
 
-public final class org/jetbrains/dokka/javadoc/pages/JavadocFunctionNode : org/jetbrains/dokka/javadoc/pages/AnchorableJavadocNode, org/jetbrains/dokka/javadoc/pages/WithBrief, org/jetbrains/dokka/javadoc/pages/WithJavadocExtra {
-	public fun <init> (Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)V
-	public synthetic fun <init> (Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+public final class org/jetbrains/dokka/javadoc/pages/JavadocFunctionNode : org/jetbrains/dokka/javadoc/pages/AnchorableJavadocNode, org/jetbrains/dokka/javadoc/pages/WithBrief, org/jetbrains/dokka/javadoc/pages/WithCommonTags, org/jetbrains/dokka/javadoc/pages/WithExecutableTags, org/jetbrains/dokka/javadoc/pages/WithJavadocExtra {
+	public fun <init> (Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)V
+	public synthetic fun <init> (Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;
+	public final fun component10 ()Lorg/jetbrains/dokka/model/properties/PropertyContainer;
 	public final fun component2 ()Ljava/util/List;
 	public final fun component3 ()Ljava/util/List;
 	public final fun component4 ()Ljava/util/List;
-	public final fun component5 ()Ljava/lang/String;
-	public final fun component6 ()Lorg/jetbrains/dokka/links/DRI;
-	public final fun component7 ()Lorg/jetbrains/dokka/model/properties/PropertyContainer;
-	public final fun copy (Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Lorg/jetbrains/dokka/javadoc/pages/JavadocFunctionNode;
-	public static synthetic fun copy$default (Lorg/jetbrains/dokka/javadoc/pages/JavadocFunctionNode;Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ILjava/lang/Object;)Lorg/jetbrains/dokka/javadoc/pages/JavadocFunctionNode;
+	public final fun component5 ()Ljava/util/List;
+	public final fun component6 ()Ljava/util/List;
+	public final fun component7 ()Ljava/util/List;
+	public final fun component8 ()Ljava/lang/String;
+	public final fun component9 ()Lorg/jetbrains/dokka/links/DRI;
+	public final fun copy (Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Lorg/jetbrains/dokka/javadoc/pages/JavadocFunctionNode;
+	public static synthetic fun copy$default (Lorg/jetbrains/dokka/javadoc/pages/JavadocFunctionNode;Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/util/List;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ILjava/lang/Object;)Lorg/jetbrains/dokka/javadoc/pages/JavadocFunctionNode;
 	public fun equals (Ljava/lang/Object;)Z
+	public fun getAuthors ()Ljava/util/List;
 	public fun getBrief ()Ljava/util/List;
 	public final fun getDescription ()Ljava/util/List;
 	public fun getDri ()Lorg/jetbrains/dokka/links/DRI;
 	public fun getExtra ()Lorg/jetbrains/dokka/model/properties/PropertyContainer;
 	public fun getName ()Ljava/lang/String;
 	public final fun getParameters ()Ljava/util/List;
+	public fun getReturn ()Ljava/util/List;
 	public final fun getSignature ()Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;
+	public fun getSince ()Ljava/util/List;
 	public fun hashCode ()I
 	public final fun isInherited ()Z
 	public fun toString ()Ljava/lang/String;
@@ -622,6 +630,15 @@ public abstract interface class org/jetbrains/dokka/javadoc/pages/WithBrief {
 	public abstract fun getBrief ()Ljava/util/List;
 }
 
+public abstract interface class org/jetbrains/dokka/javadoc/pages/WithCommonTags {
+	public abstract fun getAuthors ()Ljava/util/List;
+	public abstract fun getSince ()Ljava/util/List;
+}
+
+public abstract interface class org/jetbrains/dokka/javadoc/pages/WithExecutableTags {
+	public abstract fun getReturn ()Ljava/util/List;
+}
+
 public abstract interface class org/jetbrains/dokka/javadoc/pages/WithJavadocExtra : org/jetbrains/dokka/model/properties/WithExtraProperties {
 	public abstract fun withNewExtras (Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Lorg/jetbrains/dokka/model/Documentable;
 }

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
@@ -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()),
                     )
                 },
+                authors = c.authorsToContentNodes(jvm),
+                since = c.sinceToContentNodes(jvm),
                 documentables = listOf(c),
                 children = children,
                 extra = extra + c.indexesInDocumentation()
@@ -165,6 +164,9 @@ open class JavadocPageCreator(context: DokkaContext) {
                     )
                 }
             },
+            authors = authorsToContentNodes(jvm),
+            since = sinceToContentNodes(jvm),
+            `return` = returnToContentNodes(jvm),
             extra = extra + indexesInDocumentation()
         )
     }
@@ -177,6 +179,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 +197,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 +242,14 @@ open class JavadocPageCreator(context: DokkaContext) {
             }
         )
     }
+
+    private fun Documentable.authorsToContentNodes(sourceSet: DokkaSourceSet? = highestJvmSourceSet) =
+        allContentNodesFromType<Author>(sourceSet)
+
+    private fun Documentable.sinceToContentNodes(sourceSet: DokkaSourceSet? = highestJvmSourceSet) =
+        contentNodesFromType<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
@@ -30,6 +30,15 @@ interface WithBrief {
     val brief: List<ContentNode>
 }
 
+interface WithCommonTags {
+    val authors: List<List<ContentNode>>
+    val since: List<ContentNode>
+}
+
+interface WithExecutableTags {
+    val `return`: List<ContentNode>
+}
+
 class JavadocModulePageNode(
     override val name: String,
     override val content: JavadocContentNode,
@@ -149,6 +158,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,10 +167,16 @@ data class JavadocFunctionNode(
     override val brief: List<ContentNode>,
     val description: List<ContentNode>,
     val parameters: List<JavadocParameterNode>,
+
+    override val authors: List<List<ContentNode>>,
+    override val since: List<ContentNode>,
+
+    override val `return`: List<ContentNode>,
+
     override val name: String,
     override val dri: DRI,
     override val extra: PropertyContainer<DFunction> = PropertyContainer.empty()
-) : AnchorableJavadocNode(name, dri), WithJavadocExtra<DFunction>, WithBrief {
+) : AnchorableJavadocNode(name, dri), WithJavadocExtra<DFunction>, WithBrief, WithCommonTags, WithExecutableTags {
     val isInherited: Boolean
         get() {
             val extra = extra[InheritedMember]
@@ -182,11 +198,15 @@ class JavadocClasslikePageNode(
     val classlikes: List<JavadocClasslikePageNode>,
     val properties: List<JavadocPropertyNode>,
     override val brief: List<ContentNode>,
+
+    override val authors: List<List<ContentNode>>,
+    override val since: List<ContentNode>,
+
     override val documentables: List<Documentable> = emptyList(),
     override val children: List<PageNode> = emptyList(),
     override val embeddedResources: List<String> = listOf(),
     override val extra: PropertyContainer<DClasslike> = PropertyContainer.empty(),
-) : JavadocPageNode, WithJavadocExtra<DClasslike>, NavigableJavadocNode, WithNavigable, WithBrief, ClasslikePage {
+) : JavadocPageNode, WithJavadocExtra<DClasslike>, NavigableJavadocNode, WithNavigable, WithBrief, WithCommonTags, ClasslikePage {
 
     override fun getAllNavigables(): List<NavigableJavadocNode> =
         methods + entries + classlikes.map { it.getAllNavigables() }.flatten() + this
@@ -215,6 +235,8 @@ class JavadocClasslikePageNode(
         classlikes,
         properties,
         brief,
+        authors,
+        since,
         documentables,
         children,
         embeddedResources,
@@ -240,6 +262,8 @@ class JavadocClasslikePageNode(
             classlikes,
             properties,
             brief,
+            authors,
+            since,
             documentables,
             children,
             embeddedResources,

diff --git a/...main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt b/...main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt
@@ -122,6 +122,9 @@ internal class JavadocContentToTemplateMapTranslator(
             "description" to htmlForContentNodes(node.description,contextNode),
             "parameters" to node.parameters.map { templateMapForParameterNode(it) },
             "inlineParameters" to node.parameters.joinToString { renderInlineParameter(it) },
+            "authors" to node.authors.map { htmlForContentNodes(it, contextNode) },
+            "since" to htmlForContentNodes(node.since, contextNode),
+            "return" to htmlForContentNodes(node.`return`, contextNode),
             "anchorLink" to node.getAnchor(),
             "signature" to templateMapForSignatureNode(node.signature),
             "name" to node.name
@@ -137,6 +140,8 @@ internal class JavadocContentToTemplateMapTranslator(
                 "properties" to node.properties.map { templateMapForPropertyNode(it) },
                 "classlikes" to node.classlikes.map { templateMapForNestedClasslikeNode(it) },
                 "implementedInterfaces" to templateMapForImplementedInterfaces(node).sorted(),
+                "authors" to node.authors.map { htmlForContentNodes(it, contextNode) },
+                "since" to htmlForContentNodes(node.since, contextNode),
                 "kind" to node.kind,
                 "packageName" to node.packageName,
                 "name" to node.name

diff --git a/plugins/javadoc/src/main/resources/static_res/stylesheet.css b/plugins/javadoc/src/main/resources/static_res/stylesheet.css
@@ -629,8 +629,8 @@ h1.hidden {
 }
 .deprecatedLabel, .descfrmTypeLabel, .implementationLabel, .memberNameLabel, .memberNameLink,
 .moduleLabelInPackage, .moduleLabelInType, .overrideSpecifyLabel, .packageLabelInType,
-.packageHierarchyLabel, .paramLabel, .returnLabel, .seeLabel, .simpleTagLabel,
-.throwsLabel, .typeNameLabel, .typeNameLink, .searchTagLink {
+.packageHierarchyLabel, .authorLabel, .paramLabel, .returnLabel, .seeLabel, .simpleTagLabel,
+.throwsLabel, .sinceLabel, .typeNameLabel, .typeNameLink, .searchTagLink {
     font-weight:bold;
 }
 .deprecationComment, .emphasizedPhrase, .interfaceName {