From 7353593c0e1990d7c4b1cd67e7a6af5d47f56da0 Mon Sep 17 00:00:00 2001 From: Peter Palaga Date: Sun, 11 Feb 2024 16:19:09 +0100 Subject: [PATCH] Store since JavaDoc tag in the configuration metadata, so that Quarkiverse projects can render it in their documentation if they like --- .../generate_doc/ConfigDocItemFinder.java | 5 +++- .../processor/generate_doc/ConfigDocKey.java | 20 ++++++++++++- .../processor/generate_doc/JavaDocParser.java | 29 ++++++++++++++++--- .../generate_doc/MavenConfigDocBuilder.java | 7 ++--- .../JavaDocConfigDescriptionParserTest.java | 10 +++++++ 5 files changed, 60 insertions(+), 11 deletions(-) diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java index f5e3720291c58..a06ba2bad84fd 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java @@ -390,7 +390,8 @@ private List recursivelyFindConfigItems(Element element, String r configDocKey.setConfigPhase(configPhase); configDocKey.setDefaultValue(defaultValue); configDocKey.setDocMapKey(configDocMapKey); - configDocKey.setConfigDoc(javaDocParser.parseConfigDescription(rawJavaDoc)); + javaDocParser.parseConfigDescription(rawJavaDoc, configDocKey::setConfigDoc, configDocKey::setSince); + configDocKey.setEnvironmentVariable(DocGeneratorUtil.toEnvVarName(name)); configDocKey.setAcceptedValues(acceptedValues); configDocKey.setJavaDocSiteLink(getJavaDocSiteLink(type)); ConfigDocItem configDocItem = new ConfigDocItem(); @@ -628,6 +629,8 @@ private List decorateGroupItems( additionalKeys.addAll(additionalNames.stream().map(k -> k + configDocKey.getKey()).collect(toList())); configDocKey.setAdditionalKeys(additionalKeys); configDocKey.setKey(parentName + configDocKey.getKey()); + configDocKey.setEnvironmentVariable( + DocGeneratorUtil.toEnvVarName(parentName) + configDocKey.getEnvironmentVariable()); decoratedItems.add(configDocItem); } else { ConfigDocSection section = configDocItem.getConfigDocSection(); diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocKey.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocKey.java index a853a0f92939e..f4044599f8441 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocKey.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocKey.java @@ -27,6 +27,8 @@ final public class ConfigDocKey implements ConfigDocElement, Comparable ref = new AtomicReference<>(); + parseConfigDescription(javadocComment, ref::set, s -> { + }); + return ref.get(); + } + + public void parseConfigDescription( + String javadocComment, + Consumer javadocTextConsumer, + Consumer sinceConsumer) { + if (javadocComment == null || javadocComment.trim().isEmpty()) { - return Constants.EMPTY; + javadocTextConsumer.accept(Constants.EMPTY); + return; } // the parser expects all the lines to start with "* " @@ -90,10 +105,16 @@ public String parseConfigDescription(String javadocComment) { Javadoc javadoc = StaticJavaParser.parseJavadoc(javadocComment); if (isAsciidoc(javadoc)) { - return handleEolInAsciidoc(javadoc); + javadocTextConsumer.accept(handleEolInAsciidoc(javadoc)); + } else { + javadocTextConsumer.accept(htmlJavadocToAsciidoc(javadoc.getDescription())); } - - return htmlJavadocToAsciidoc(javadoc.getDescription()); + javadoc.getBlockTags().stream() + .filter(t -> t.getType() == Type.SINCE) + .map(JavadocBlockTag::getContent) + .map(JavadocDescription::toText) + .findFirst() + .ifPresent(sinceConsumer::accept); } public SectionHolder parseConfigSection(String javadocComment, int sectionLevel) { diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/MavenConfigDocBuilder.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/MavenConfigDocBuilder.java index 16d3c31a23205..a5b1fcf98cc0e 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/MavenConfigDocBuilder.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/MavenConfigDocBuilder.java @@ -79,11 +79,8 @@ public void addParam(String type, String name, String defaultValue, boolean requ configDocKey.setAdditionalKeys(List.of(name)); configDocKey.setConfigPhase(ConfigPhase.RUN_TIME); configDocKey.setDefaultValue(defaultValue == null ? Constants.EMPTY : defaultValue); - if (description != null && !description.isBlank()) { - configDocKey.setConfigDoc(javaDocParser.parseConfigDescription(description)); - } else { - configDocKey.setConfigDoc(EMPTY); - } + javaDocParser.parseConfigDescription(description, configDocKey::setConfigDoc, configDocKey::setSince); + configDocKey.setEnvironmentVariable(DocGeneratorUtil.toEnvVarName(name)); configDocKey.setOptional(!required); final ConfigDocItem configDocItem = new ConfigDocItem(); configDocItem.setConfigDocKey(configDocKey); diff --git a/core/processor/src/test/java/io/quarkus/annotation/processor/generate_doc/JavaDocConfigDescriptionParserTest.java b/core/processor/src/test/java/io/quarkus/annotation/processor/generate_doc/JavaDocConfigDescriptionParserTest.java index f23705f230e63..60d4200fe52a3 100644 --- a/core/processor/src/test/java/io/quarkus/annotation/processor/generate_doc/JavaDocConfigDescriptionParserTest.java +++ b/core/processor/src/test/java/io/quarkus/annotation/processor/generate_doc/JavaDocConfigDescriptionParserTest.java @@ -3,6 +3,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import java.util.Collections; +import java.util.concurrent.atomic.AtomicReference; import org.asciidoctor.Asciidoctor.Factory; import org.junit.jupiter.api.BeforeEach; @@ -252,6 +253,15 @@ public void parseJavaDocWithCodeBlock() { // parser.parseConfigDescription("Example:\n\n
{@code\nfoo\nbar\n}
")); } + @Test + public void since() { + AtomicReference javadoc = new AtomicReference<>(); + AtomicReference since = new AtomicReference<>(); + parser.parseConfigDescription("Javadoc text\n\n@since 1.2.3", javadoc::set, since::set); + assertEquals("Javadoc text", javadoc.get()); + assertEquals("1.2.3", since.get()); + } + @Test public void asciidoc() { String asciidoc = "== My Asciidoc\n" +