Skip to content

Commit

Permalink
Add support for @author, @since, @return Javadoc tags (#2967)
Browse files Browse the repository at this point in the history
  • Loading branch information
@irina-turova @eunwoo-park-nhn
irina-turova authored and eunwoo-park-nhn committed Jul 5, 2023
1 parent 4802085 commit 8ee84ac
Show file tree
Hide file tree
Showing 9 changed files with 210 additions and 20 deletions.
9 changes: 9 additions & 0 deletions plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt
View file
Expand Up @@ -168,6 +168,15 @@ class JavadocParser(
)
)

JavadocTag.SINCE -> Since(
wrapTagIfNecessary(
convertJavadocElements(
tag.contentElementsWithSiblingIfNeeded(),
context = resolutionContext
)
)
)

else -> emptyTagWrapper(tag, docComment)
}
}
Expand Down
2 changes: 1 addition & 1 deletion plugins/base/src/main/kotlin/translators/psi/parsers/JavadocTag.kt
View file
@@ -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
Expand Down
24 changes: 15 additions & 9 deletions plugins/javadoc/api/javadoc.api
View file
Expand Up @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand Down
32 changes: 27 additions & 5 deletions plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
View file
Expand Up @@ -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.*
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -165,6 +164,8 @@ open class JavadocPageCreator(context: DokkaContext) {
)
}
},
returnTagContent = returnToContentNodes(jvm),
sinceTagContent = sinceToContentNodes(jvm),
extra = extra + indexesInDocumentation()
)
}
Expand All @@ -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)

Expand All @@ -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} ")
Expand Down Expand Up @@ -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)
}

13 changes: 13 additions & 0 deletions plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
View file
Expand Up @@ -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

Expand All @@ -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()
Expand All @@ -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(),
Expand Down Expand Up @@ -215,6 +224,8 @@ class JavadocClasslikePageNode(
classlikes,
properties,
brief,
sinceTagContent,
authorTagContent,
documentables,
children,
embeddedResources,
Expand All @@ -240,6 +251,8 @@ class JavadocClasslikePageNode(
classlikes,
properties,
brief,
sinceTagContent,
authorTagContent,
documentables,
children,
embeddedResources,
Expand Down
4 changes: 4 additions & 0 deletions ...main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt
View file
Expand Up @@ -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
Expand All @@ -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
Expand Down
10 changes: 8 additions & 2 deletions plugins/javadoc/src/main/resources/static_res/stylesheet.css
View file
Expand Up @@ -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;
Expand Down Expand Up @@ -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 {
Expand Down
38 changes: 35 additions & 3 deletions plugins/javadoc/src/main/resources/views/class.korte
View file
Expand Up @@ -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>
Expand Down Expand Up @@ -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 %}
Expand Down

0 comments on commit 8ee84ac

Please sign in to comment.