Render since JavaDoc tag in the configuration documentation

ppalaga · Dec 22, 2023 · c00bb4c · c00bb4c
1 parent 50a9264
commit c00bb4c
Show file tree

Hide file tree

Showing 6 changed files with 52 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,7 @@ 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.setAcceptedValues(acceptedValues);
                 configDocKey.setJavaDocSiteLink(getJavaDocSiteLink(type));
                 ConfigDocItem configDocItem = new ConfigDocItem();

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,7 @@ 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;
 
     public ConfigDocKey() {
     }
@@ -193,6 +194,14 @@ public void setEnum(boolean anEnum) {
         isEnum = anEnum;
     }
 
+    public String getSince() {
+        return since;
+    }
+
+    public void setSince(String since) {
+        this.since = since;
+    }
+
     @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,7 @@ 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.setOptional(!required);
             final ConfigDocItem configDocItem = new ConfigDocItem();
             configDocItem.setConfigDocKey(configDocKey);

diff --git a/.../src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java b/.../src/main/java/io/quarkus/annotation/processor/generate_doc/SummaryTableDocFormatter.java
@@ -117,8 +117,13 @@ public void format(Writer writer, ConfigDocKey configDocKey) throws IOException
 
         StringBuilder keys = new StringBuilder();
         keys.append(
-                String.format("%s [[%s]]`link:#%s[%s]`\n\n", configDocKey.getConfigPhase().getIllustration(), anchor, anchor,
+                String.format("%s [[%s]]`link:#%s[%s]`", configDocKey.getConfigPhase().getIllustration(), anchor, anchor,
                         key));
+        if (configDocKey.getSince() != null) {
+            keys.append(" (since ").append(configDocKey.getSince()).append(")");
+        }
+        keys.append("\n\n");
+
         for (String additionalKey : configDocKey.getAdditionalKeys()) {
             if (!additionalKey.equals(key)) {
                 keys.append(String.format("`link:#%s[%s]`\n\n", anchor, additionalKey));

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" +