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

Kotlin · May 31, 2023 · f457506 · f457506
1 parent 0cad056
commit f457506
Show file tree

Hide file tree

Showing 9 changed files with 210 additions and 20 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
@@ -178,10 +178,11 @@ public final class org/jetbrains/dokka/javadoc/pages/JavaContentGroupBuilder {
 }
 
 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 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 final fun getAuthorTagContent ()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 final fun getSinceTagContent ()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;
@@ -293,25 +295,29 @@ public final class org/jetbrains/dokka/javadoc/pages/JavadocEntryNode : org/jetb
 }
 
 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 fun <init> (Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;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/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 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/lang/String;
+	public final fun component8 ()Lorg/jetbrains/dokka/links/DRI;
+	public final fun component9 ()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/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/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 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 final fun getReturnTagContent ()Ljava/util/List;
 	public final fun getSignature ()Lorg/jetbrains/dokka/javadoc/pages/JavadocSignatureContentNode;
+	public final fun getSinceTagContent ()Ljava/util/List;
 	public fun hashCode ()I
 	public final fun isInherited ()Z
 	public fun toString ()Ljava/lang/String;

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()),
                     )
                 },
+                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
@@ -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/...main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt b/...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

diff --git a/plugins/javadoc/src/main/resources/static_res/stylesheet.css b/plugins/javadoc/src/main/resources/static_res/stylesheet.css
@@ -352,6 +352,12 @@ ul.blockList li.blockList h2 {
     font-size:14px;
     font-family:'DejaVu Serif', Georgia, "Times New Roman", Times, serif;
 }
+
+.contentContainer .description dl dt p, .contentContainer .details dl dt p, .serializedFormContainer dl dt p,
+.contentContainer .description dl dd p, .contentContainer .details dl dd p, .serializedFormContainer dl dd p {
+    margin:5px 0 10px 0px;
+}
+
 .serializedFormContainer dl.nameValue dt {
     margin-left:1px;
     font-size:1.1em;
@@ -629,8 +635,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 {

diff --git a/plugins/javadoc/src/main/resources/views/class.korte b/plugins/javadoc/src/main/resources/views/class.korte
@@ -38,6 +38,24 @@
 {% if signature.supertypes != null %}{{signature.supertypes|raw}}{% endif %}
                     </pre>
                     <div class="block">{{ classlikeDocumentation|raw }}</div>
+
+                    <dl>
+
+                    {% if sinceTagContent.size() != 0 %}
+                        <dt><span class="sinceLabel">Since:</span></dt>
+                        {% for since in sinceTagContent %}
+                            <dd>{{ since|raw }}</dd>
+                        {% endfor %}
+                    {% endif %}
+
+                    {% if authorTagContent.size() != 0 %}
+                        <dt><span class="authorLabel">Author:</span></dt>
+                        {% for author in authorTagContent %}
+                            <dd>{{ author|raw }}</dd>
+                        {% endfor %}
+                    {% endif %}
+
+                    </dl>
                 </li>
             </ul>
         </div>
@@ -271,17 +289,31 @@
                                         <h4>{{ method.name }}</h4>
                                         <pre class="methodSignature">{{ method.signature.annotations|raw }} {{ method.signature.modifiers|raw }} {{ method.signature.signatureWithoutModifiers|raw}}</pre>
                                         <div class="block">{{ method.description|raw }}</div>
-                                        {% if method.parameters.size != 0 && hasAnyDescription(method.parameters) %}
+
                                         <dl>
+
+                                        {% if method.parameters.size != 0 && hasAnyDescription(method.parameters) %}
                                             <dt><span class="paramLabel">Parameters:</span></dt>
                                             {% for parameter in method.parameters %}
                                             {% if parameter.description != "" %}
                                             <dd><code>{{ parameter.name }}</code> - {{ parameter.description|raw }}</dd>
                                             {% endif %}
                                             {% endfor %}
-                                        </dl>
                                         {% endif %}
-                                        <!-- TODO missing return annotation -->
+
+                                        {% if method.returnTagContent != "" %}
+                                            <dt><span class="returnLabel">Returns:</span></dt>
+                                            <dd>{{ method.returnTagContent|raw }}</dd>
+                                        {% endif %}
+
+                                        {% if method.sinceTagContent.size() != 0 %}
+                                            <dt><span class="sinceLabel">Since:</span></dt>
+                                            {% for since in method.sinceTagContent %}
+                                                <dd>{{ since|raw }}</dd>
+                                            {% endfor %}
+                                        {% endif %}
+
+                                        </dl>
                                     </li>
                                 </ul>
                                 {% endfor %}