JEP 413: Add support for `@snippet` tag in Javadoc #4392

yuriioliinyk4 · 2025-12-15T13:22:53Z

Impl for #3005

Useful links:
https://bugs.openjdk.org/browse/JDK-8201533
https://blogs.oracle.com/javamagazine/java-javadoc-snippet/
https://docs.oracle.com/en/java/javase/21/javadoc/snippets.html
https://belief-driven-design.com/better-code-snippets-in-javadoc-b27f5
https://docs.oracle.com/en/java/javase/18/docs/specs/javadoc/doc-comment-spec.html

yuriioliinyk4 · 2025-12-22T01:31:50Z

dokka-subprojects/plugin-base/src/test/kotlin/parsers/javadoc/SnippetTest.kt

+                            children = listOf(
+                                Text(
+                                    """
+                                    |/*


In this test and the test below, WholeFileSnippet.java is used from resources, which contain copyright. The output of the test is whole file content including the copyright, which is expected. I’m concerned about whether this is okay, since the copyright header may be updated by a script in the future, which could break those tests. Should I change something here, or is it better to leave it as is?

yuriioliinyk4 · 2025-12-22T01:48:27Z

...i/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/doctag/SnippetToHtmlConverter.kt

+        }
+
+        val substring = attributes["substring"]?.htmlEscape()
+        val regex = attributes["regex"]?.htmlEscape()?.toRegex()


htmlEscape is needed to apply here to match literal symbols such as [&, <, >, "], because htmlEscape function is applied to the raw line before applying any markup. But < and > can be used in regex constructs, for instance lookbehind. Should we adjust the logic to handle this, or leave it as is, given that such cases are quite rare and unlikely to occur?

Mentioned function:
public fun String.htmlEscape(): String = replace("&", "&").replace("<", "<").replace(">", ">").replace("\"", """)

Do you really need htmlEscape here? It seems unnecessary, since the result is result.replace(regex) { match -> match.value.wrapInTag() } that is, the escaped value is not used in the returned value.

htmlEscape is needed to match literal symbol such as [&, <, >, "], because htmlEscape function is applied to the raw line before applying any markup.

Without htmlEscape on regex following examples wont work:
// @replace regex='".*"' replacement="..."
or
// @replace regex='"(.*)"' replacement='"I said, $1"'

because " in regex pattern wont be matched, since " in the line were changed to the "

vmishenev

👍

vmishenev · 2025-12-23T13:00:45Z

...-psi/src/main/kotlin/org/jetbrains/dokka/analysis/java/DefaultPsiToDocumentableTranslator.kt


            val psiFiles = sourceRoots.parallelMap { sourceRoot ->
-                sourceRoot.absoluteFile.walkTopDown().mapNotNull {
+                sourceRoot.absoluteFile.walkTopDown().filter { !it.path.contains("/snippet-files") }.mapNotNull {


minor: if sourceRoot contains "snippet-files/", the whole source root will be filter out. Can you fix it?
nitpick: filterNot is better for readability.

see 61f298c

dokka-subprojects/analysis-java-psi/api/analysis-java-psi.api

vmishenev · 2025-12-23T14:20:01Z

...i/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/doctag/SnippetToHtmlConverter.kt

+        snippet: PsiSnippetDocTag
+    ): String {
+        val value = snippet.valueElement ?: run {
+            logger.error("@snippet: unable to resolve snippet")


logger.warn is more appropriate here. logger.error is intended for more fatal conditions. See the KDoc for logger.error.

Also, could you add some information about the snippet, for example, its location? (and in the messages below)

see 85d2ecc

...i/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/doctag/SnippetToHtmlConverter.kt

vmishenev · 2025-12-23T14:52:07Z

...i/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/doctag/SnippetToHtmlConverter.kt

+        }
+
+        if (parsedSnippet.isBlank()) {
+            logger.error("@snippet: unable to resolve snippet")


nitpick:

logger.error("@snippet: unable to resolve snippet") SNIPPET_NOT_RESOLVED

looks like a code duplication. Maybe it’s better to extract it into a function.

...i/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/doctag/SnippetToHtmlConverter.kt

vmishenev · 2025-12-23T19:17:31Z

...i/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/doctag/SnippetToHtmlConverter.kt

+        }
+
+        val substring = attributes["substring"]?.htmlEscape()
+        val regex = attributes["regex"]?.htmlEscape()?.toRegex()


Do you really need htmlEscape here? It seems unnecessary, since the result is result.replace(regex) { match -> match.value.wrapInTag() } that is, the escaped value is not used in the returned value.

dokka-subprojects/plugin-base/src/test/kotlin/parsers/javadoc/SnippetTest.kt

Copilot

Pull request overview

This PR implements support for the @snippet Javadoc tag introduced in JEP 413 (Java 18). The snippet tag provides a modern alternative to @code and <pre> blocks, with better support for generics, annotations, external files, regions, and markup features like highlighting, replacing, and linking.

Key changes include:

Implementation of snippet parsing with support for inline snippets, external files from snippet-files, and files from the samples configuration path
Support for snippet regions using @start/@end markers
Support for markup tags (@highlight, @replace, @link) within snippets
Updates to parser signatures to pass DokkaSourceSet through the call chain to enable snippet path resolution

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
SnippetToHtmlConverter.kt	New file implementing the core snippet parsing and conversion logic with support for all JEP 413 features
PsiElementToHtmlConverter.kt	Integrates snippet converter into the Javadoc parsing pipeline
HtmlToDocTagConverter.kt	Adds `lang` attribute handling for `<pre>` tags to support language-specific code blocks
PsiDocTagParser.kt	Updated to pass DokkaContext and DokkaSourceSet through the parsing chain
JavadocParser.kt, JavaDocCommentParser.kt, DocCommentParser.kt	Updated signatures to accept and propagate DokkaSourceSet parameter
DokkaPsiParser.kt	Updated to pass sourceSet to documentation parsing methods
DefaultPsiToDocumentableTranslator.kt	Added filtering to exclude `snippet-files` directory from analysis
KotlinDocCommentParser.kt, DescriptorKotlinDocCommentParser.kt, KDocProvider.kt	Updated to propagate sourceSet through documentation parsing
DefaultSymbolToDocumentableTranslator.kt	Updated to pass sourceSet to Javadoc parsing
SyntheticElementDocumentationProvider.kt	Updated to accept and use sourceSet parameter
JavaAnalysisPlugin.kt	Refactored to pass DokkaContext to PsiDocTagParser at creation time
JavadocParserTest.kt	Package renamed from `parsers` to `parsers.javadoc` and minor test updates
SnippetTest.kt	Comprehensive test suite covering all snippet features and edge cases
Test resources	Sample snippet files for testing external snippet functionality
analysis-java-psi.api	Public API updates reflecting signature changes

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

...i/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/doctag/SnippetToHtmlConverter.kt

dokka-subprojects/plugin-base/src/test/resources/parsers/javadoc/snippets/ExternalSnippets.java

...-psi/src/main/kotlin/org/jetbrains/dokka/analysis/java/DefaultPsiToDocumentableTranslator.kt

...i/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/doctag/SnippetToHtmlConverter.kt

…ation and add unit test

yuriioliinyk4 added 14 commits December 15, 2025 01:42

feat: add support for inline snippets

5b32469

feat: add sourceSet parameter to DocCommentParser.parse function

4be5b6e

fix: don't generate documentation for files in /snippet-files

8ae9ba8

feat: introduce SamplePsiFilesProvider and its symbols implementation

cae7ce8

feat: add SnippetToHtmlConverter

47d267f

feat: add lang attribute support for snippets

31ddb90

test: add basic unit tests for snippets

8679062

feat: add and use custom getSnippetBodyLines method

7bbfb4e

refactor: change resolving logic of external snippets

13b3c21

fix: filter out blank markupTags and change ordering of markupTags

993a537

refactor: specify type for snippetToHtmlConverter property

94e1aaf

fix: use htmlEscape for substring and regex attributes

59966a9

fix: improve snippet handling by checking type before conversion

c4268e2

test: enhance unit tests for snippets

b1e32a4

yuriioliinyk4 marked this pull request as ready for review December 22, 2025 01:21

yuriioliinyk4 commented Dec 22, 2025

View reviewed changes

vmishenev requested review from vmishenev and whyoleg December 22, 2025 10:50

vmishenev reviewed Dec 23, 2025

View reviewed changes

vmishenev requested a review from Copilot December 25, 2025 07:59

Copilot started reviewing on behalf of vmishenev December 25, 2025 07:59 View session

Copilot AI reviewed Dec 25, 2025

View reviewed changes

yuriioliinyk4 added 8 commits December 25, 2025 23:12

test: enhance unit test for regex-based replacement in snippets

8266d69

fix: use onEnter() to exclude files insnippet-files from document…

61f298c

…ation and add unit test

fix: make SnippetToHtmlConverter interface internal

c8ea1b2

docs: enhance KDoc in SnippetToHtmlConverter.kt

fa3ab9d

style: place a companion object at the end of its class declaration

15a8891

perf: create Regex for splitting markup tags once

a945adf

fix: use readLines() instead of readText().split("\n")

636bb18

fix: invalid java syntax in resource file for SnippetTest

4dc3c51

refactor: improve logging in DefaultSnippetToHtmlConverter

85d2ecc

JEP 413: Add support for @snippet tag in Javadoc #4392

Are you sure you want to change the base?

JEP 413: Add support for @snippet tag in Javadoc #4392

Conversation

yuriioliinyk4 commented Dec 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vmishenev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JEP 413: Add support for `@snippet` tag in Javadoc #4392

JEP 413: Add support for `@snippet` tag in Javadoc #4392