Skip to content

Render custom tag briefs for enum entries and constructor #4265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Render custom tag briefs for enum entries and constructor #4265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
024109f
Render content for custom tag briefs for enum entries and constructors
strangesource Sep 17, 2025
ba79e81
Minimal unit test
strangesource Sep 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .../src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -519,6 +519,7 @@ public open class DefaultPageCreator(
ds.forEach {
+buildSignature(it)
contentForBrief(it)
contentForCustomTagsBrief(it)
}
}
}
Expand Down Expand Up @@ -552,6 +553,7 @@ public open class DefaultPageCreator(
ds.forEach {
+buildSignature(it)
contentForBrief(it)
contentForCustomTagsBrief(it)
}
}
}
Expand Down
189 changes: 189 additions & 0 deletions dokka-subprojects/plugin-base/src/test/kotlin/content/CustomTagContentProviderTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
/*
* Copyright 2014-2025 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/

package content

import matchers.content.assertNode
import matchers.content.check
import matchers.content.group
import matchers.content.header
import matchers.content.link
import matchers.content.platformHinted
import matchers.content.skipAllNotMatching
import matchers.content.table
import org.jetbrains.dokka.DokkaConfiguration
import org.jetbrains.dokka.base.DokkaBase
import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
import org.jetbrains.dokka.base.transformers.pages.tags.CustomTagContentProvider
import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder
import org.jetbrains.dokka.model.doc.CustomTagWrapper
import org.jetbrains.dokka.pages.ContentKind
import org.jetbrains.dokka.pages.ContentPage
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.Extension
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import kotlin.test.Test
import kotlin.test.assertEquals

class CustomTagContentProviderTest : BaseAbstractTest() {
Copy link
Collaborator

@whyoleg whyoleg Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you also mind adding a test for class documentation and some function documentation with custom tags, so that we have all cases covered in one test?


val configuration = dokkaConfiguration {
suppressObviousFunctions = false
sourceSets {
sourceSet {
sourceRoots = listOf("src/main/kotlin")
}
}
}

@Test
fun `custom tag content provider brief is present for constructors`(){
testInline(
"""
|/src/main/kotlin/com/example/foo.kt
|package com.example
|
|class Foo {
|/**
| * @customTag custom tag for constructor
| */
| constructor()
|}
""".trimIndent(),
configuration,
pluginOverrides = listOf(TestPluginWithCustomTagContentProvider())
) {
renderingStage = { rootPageNode, _ ->
val page = rootPageNode.children
.flatMap { it.children }
.filterIsInstance<ContentPage>()
.single { it.name == "Foo" }

page.content.assertNode {
Copy link
Collaborator

@whyoleg whyoleg Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, the test is correct, but it could be done a bit more cleanly. Let's create an additional Style object, add it via CustomTagContentProvider:

// new style
object TestCustomStyle: Style

class TestCustomTagContentProvider : CustomTagContentProvider {
    override fun isApplicable(customTag: CustomTagWrapper): Boolean {
        return customTag.name == "customTag"
    }

    override fun PageContentBuilder.DocumentableContentBuilder.contentForBrief(
        sourceSet: DokkaConfiguration.DokkaSourceSet,
        customTag: CustomTagWrapper
    ) {
        // add style
        comment(customTag.children.single(), styles = mainStyles + setOf(TestCustomStyle))
    }
}

And in that case, it's possible to find it and do an assertion rather easily:

val customTagContents = page.content.withDescendants().filter {
    it.style.contains(TestCustomStyle)
}.toList()

assertEquals(1, customTagContents.size)
customTagContents.single().assertNode {
    group {
        +"custom tag for constructor"
    }
}

skipAllNotMatching()
group {
group {
group {
header { +"Constructors" }
table {
group {
link { +"Foo" }
platformHinted {
group {
skipAllNotMatching()
}
group {
check {
assertEquals(dci.kind, ContentKind.BriefComment)
}
skipAllNotMatching()
}
group {
group {
+"custom tag for constructor"
}
}
skipAllNotMatching()
}
skipAllNotMatching()
}
}
skipAllNotMatching()
}
}
skipAllNotMatching()
}
}
}
}
}

@Test
fun `custom tag content provider brief is present in Entries table for enums`() {
testInline(
"""
|/src/main/kotlin/com/example/foo.kt
|package com.example
|
|enum class Foo {
|/**
| * @customTag custom tag for a
| */
| A
|}
""".trimIndent(),
configuration,
pluginOverrides = listOf(TestPluginWithCustomTagContentProvider())
) {
renderingStage = { rootPageNode, _ ->
val page = rootPageNode.children
.flatMap { it.children }
.filterIsInstance<ContentPage>()
.single { it.name == "Foo" }

page.content.assertNode {
skipAllNotMatching()
group {
group {
group {
header { +"Entries" }
table {
group {
link { +"A" }
platformHinted {
group {
skipAllNotMatching()
}
group {
check {
assertEquals(dci.kind, ContentKind.BriefComment)
}
skipAllNotMatching()
}
group {
group {
+"custom tag for a"
}
}
skipAllNotMatching()
}
skipAllNotMatching()
}
}
skipAllNotMatching()
}
}
skipAllNotMatching()
}
}
}
}
}
}

class TestPluginWithCustomTagContentProvider : DokkaPlugin() {
@Suppress("unused") // This delegated property has a desired side effect.
val customCodeContentProvider: Extension<CustomTagContentProvider, *, *> by extending {
plugin<DokkaBase>().customTagContentProvider providing {
TestCustomTagContentProvider()
}
}

@DokkaPluginApiPreview
override fun pluginApiPreviewAcknowledgement() = PluginApiPreviewAcknowledgement
}

class TestCustomTagContentProvider : CustomTagContentProvider {
override fun isApplicable(customTag: CustomTagWrapper): Boolean {
return customTag.name == "customTag"
}

override fun PageContentBuilder.DocumentableContentBuilder.contentForBrief(
sourceSet: DokkaConfiguration.DokkaSourceSet,
customTag: CustomTagWrapper
) {
comment(customTag.children.single())
}
}
Loading