Store since JavaDoc tag in the configuration metadata, so that

Quarkiverse projects can render it in their documentation if they like
ppalaga · Feb 11, 2024 · 7353593 · 7353593
1 parent d9cd57a
commit 7353593
Show file tree

Hide file tree

Showing 5 changed files with 60 additions and 11 deletions.
diff --git a/...essor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java b/...essor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java
@@ -390,7 +390,8 @@ private List<ConfigDocItem> 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<ConfigDocItem> 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
@@ -27,6 +27,8 @@ final public class ConfigDocKey implements ConfigDocElement, Comparable<ConfigDo
     // if a key is "quarkus.kubernetes.part-of", then the value of this would be "kubernetes"
     private String topLevelGrouping;
     private boolean isEnum;
+    private String since;
+    private String environmentVariable;
 
     public ConfigDocKey() {
     }
@@ -130,7 +132,7 @@ public boolean isWithinAMap() {
         return withinAMap;
     }
 
-    String computeTypeSimpleName() {
+    public String computeTypeSimpleName() {
         String unwrappedType = DocGeneratorUtil.unbox(type);
 
         Matcher matcher = Constants.CLASS_NAME_PATTERN.matcher(unwrappedType);
@@ -193,6 +195,22 @@ public void setEnum(boolean anEnum) {
         isEnum = anEnum;
     }
 
+    public String getSince() {
+        return since;
+    }
+
+    public void setSince(String since) {
+        this.since = since;
+    }
+
+    public String getEnvironmentVariable() {
+        return environmentVariable;
+    }
+
+    public void setEnvironmentVariable(String environmentVariable) {
+        this.environmentVariable = environmentVariable;
+    }
+
     @Override
     public void accept(Writer writer, DocFormatter docFormatter) throws IOException {
         docFormatter.format(writer, this);

diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/JavaDocParser.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/JavaDocParser.java
@@ -2,6 +2,8 @@
 
 import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.hyphenate;
 
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;
@@ -13,6 +15,7 @@
 import com.github.javaparser.StaticJavaParser;
 import com.github.javaparser.javadoc.Javadoc;
 import com.github.javaparser.javadoc.JavadocBlockTag;
+import com.github.javaparser.javadoc.JavadocBlockTag.Type;
 import com.github.javaparser.javadoc.description.JavadocDescription;
 import com.github.javaparser.javadoc.description.JavadocDescriptionElement;
 import com.github.javaparser.javadoc.description.JavadocInlineTag;
@@ -80,8 +83,20 @@ public JavaDocParser() {
     }
 
     public String parseConfigDescription(String javadocComment) {
+        final AtomicReference<String> ref = new AtomicReference<>();
+        parseConfigDescription(javadocComment, ref::set, s -> {
+        });
+        return ref.get();
+    }
+
+    public void parseConfigDescription(
+            String javadocComment,
+            Consumer<String> javadocTextConsumer,
+            Consumer<String> 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/...sor/src/main/java/io/quarkus/annotation/processor/generate_doc/MavenConfigDocBuilder.java b/...sor/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/...java/io/quarkus/annotation/processor/generate_doc/JavaDocConfigDescriptionParserTest.java b/...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<pre>{@code\nfoo\nbar\n}</pre>"));
     }
 
+    @Test
+    public void since() {
+        AtomicReference<String> javadoc = new AtomicReference<>();
+        AtomicReference<String> 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" +