docs: display correct default value for primitives instead of an empt…

…y string .Also ignore CongitRoot and ConfigGroup static fields
quarkusio · Aug 30, 2019 · fe53a63 · fe53a63
1 parent c057dbf
commit fe53a63
Show file tree

Hide file tree

Showing 19 changed files with 141 additions and 269 deletions.
diff --git a/core/creator/src/main/java/io/quarkus/creator/phase/generateconfig/GenerateConfigPhase.java b/core/creator/src/main/java/io/quarkus/creator/phase/generateconfig/GenerateConfigPhase.java
@@ -13,8 +13,6 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
 
 import org.eclipse.microprofile.config.Config;
 import org.jboss.logging.Logger;
@@ -167,7 +165,7 @@ private void doProcess(CurateOutcome appState) throws AppCreatorException {
                     }
 
                     sb.append("\n#\n");
-                    sb.append(formatDocs(i.getDocs()));
+                    sb.append(i.getDocs());
                     sb.append("\n#\n#");
                     sb.append(i.getPropertyName() + "=" + i.getDefaultValue());
                     sb.append("\n");
@@ -193,69 +191,6 @@ private void doProcess(CurateOutcome appState) throws AppCreatorException {
         }
     }
 
-    private String formatDocs(String docs) {
-
-        if (docs == null) {
-            return "";
-        }
-        StringBuilder builder = new StringBuilder();
-
-        boolean lastEmpty = false;
-        boolean first = true;
-
-        for (String line : docs.replace("<p>", "\n").split("\n")) {
-            //process line by line
-            String trimmed = line.trim();
-            //if the lines are empty we only include a single empty line at most, and add a # character
-            if (trimmed.isEmpty()) {
-                if (!lastEmpty && !first) {
-                    lastEmpty = true;
-                    builder.append("\n#");
-                }
-                continue;
-            }
-            //add the newlines
-            lastEmpty = false;
-            if (first) {
-                first = false;
-            } else {
-                builder.append("\n");
-            }
-            //replace some special characters, others are taken care of by regex below
-            builder.append("# " + trimmed.replace("\n", "\n#")
-                    .replace("<ul>", "")
-                    .replace("</ul>", "")
-                    .replace("<li>", " - ")
-                    .replace("</li>", ""));
-        }
-
-        String ret = builder.toString();
-        //replace @code
-        ret = Pattern.compile("\\{@code (.*?)\\}").matcher(ret).replaceAll("'$1'");
-        //replace @link with a reference to the field name
-        Matcher matcher = Pattern.compile("\\{@link #(.*?)\\}").matcher(ret);
-        while (matcher.find()) {
-            ret = ret.replace(matcher.group(0), "'" + configify(matcher.group(1)) + "'");
-        }
-
-        return ret;
-    }
-
-    private String configify(String group) {
-        //replace uppercase characters with a - followed by lowercase
-        StringBuilder ret = new StringBuilder();
-        for (int i = 0; i < group.length(); ++i) {
-            char c = group.charAt(i);
-            if (Character.isUpperCase(c)) {
-                ret.append("-");
-                ret.append(Character.toLowerCase(c));
-            } else {
-                ret.append(c);
-            }
-        }
-        return ret.toString();
-    }
-
     @Override
     public String getConfigPropertyName() {
         return "augment";

diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java b/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java
@@ -14,6 +14,7 @@ public class Constants {
     public static final String NO_DEFAULT = "<<no default>>";
     public static final String HYPHENATED_ELEMENT_NAME = "<<hyphenated element name>>";
 
+    public static final Pattern JAVA_DOC_SEE_PATTERN = Pattern.compile("@see\\s+(.+)\\s*");
     public static final Pattern JAVA_DOC_CODE_PATTERN = Pattern.compile("\\{@code (.*?)\\}");
     public static final Pattern JAVA_DOC_LINK_PATTERN = Pattern.compile("\\{@link #(.*?)\\}");
     public static final Pattern CONFIG_ROOT_PATTERN = Pattern.compile("^(\\w+)Config(uration)?");

diff --git a/...processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java b/...processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java
@@ -685,7 +685,75 @@ private String getRequiredJavadoc(Element e) {
             processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Unable to find javadoc for config item " + e, e);
             return "";
         }
-        return docComment.trim();
+
+        return formatDocs(docComment.trim());
+    }
+
+    /**
+     * TODO - properly parse JavaDoc
+     */
+    private String formatDocs(String docs) {
+        if (docs == null) {
+            return "";
+        }
+
+        StringBuilder builder = new StringBuilder();
+        boolean lastEmpty = false;
+        boolean first = true;
+        for (String line : docs.replace("<p>", "\n").split("\n")) {
+            //process line by line
+            String trimmed = line.trim();
+            //if the lines are empty we only include a single empty line at most, and add a # character
+            if (trimmed.isEmpty()) {
+                if (!lastEmpty && !first) {
+                    lastEmpty = true;
+                    builder.append("\n");
+                }
+                continue;
+            }
+            //add the newlines
+            lastEmpty = false;
+            if (first) {
+                first = false;
+            } else {
+                builder.append("\n");
+            }
+            //replace some special characters, others are taken care of by regex below
+            builder.append(trimmed.replace("\n", "\n")
+                    .replace("<ul>", "")
+                    .replace("</ul>", "")
+                    .replace("<li>", " - ")
+                    .replace("</li>", ""));
+        }
+
+        String ret = builder.toString();
+        //replace @code
+        ret = Constants.JAVA_DOC_CODE_PATTERN.matcher(ret).replaceAll("`$1`");
+
+        //replace @see
+        ret = Constants.JAVA_DOC_SEE_PATTERN.matcher(ret).replaceAll("see `$1`");
+
+        //replace @link with a reference to the field name
+        Matcher matcher = Constants.JAVA_DOC_LINK_PATTERN.matcher(ret);
+        while (matcher.find()) {
+            ret = ret.replace(matcher.group(0), "`" + configify(matcher.group(1)) + "`");
+        }
+        return ret;
+    }
+
+    private String configify(String group) {
+        //replace uppercase characters with a - followed by lowercase
+        StringBuilder ret = new StringBuilder();
+        for (int i = 0; i < group.length(); ++i) {
+            char c = group.charAt(i);
+            if (Character.isUpperCase(c)) {
+                ret.append("-");
+                ret.append(Character.toLowerCase(c));
+            } else {
+                ret.append(c);
+            }
+        }
+        return ret.toString();
     }
 
     private static boolean hasParameterAnnotated(ExecutableElement ex, String annotationName) {

diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigItem.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigItem.java
@@ -1,8 +1,20 @@
 package io.quarkus.annotation.processor.generate_doc;
 
+import java.util.HashMap;
+import java.util.Map;
 import java.util.Objects;
 
 public class ConfigItem implements Comparable<ConfigItem> {
+    private static final Map<String, String> PRIMITIVE_DEFAULT_VALUES = new HashMap<>();
+
+    static {
+        PRIMITIVE_DEFAULT_VALUES.put("int", "0");
+        PRIMITIVE_DEFAULT_VALUES.put("long", "0l");
+        PRIMITIVE_DEFAULT_VALUES.put("float", "0f");
+        PRIMITIVE_DEFAULT_VALUES.put("double", "0d");
+        PRIMITIVE_DEFAULT_VALUES.put("boolean", "false");
+    }
+
     private final String type;
     private final String javaDocKey;
     private final String propertyName;
@@ -66,7 +78,11 @@ public String getPropertyName() {
     }
 
     public String getDefaultValue() {
-        return defaultValue;
+        if (!defaultValue.isEmpty()) {
+            return defaultValue;
+        }
+
+        return PRIMITIVE_DEFAULT_VALUES.containsKey(type) ? PRIMITIVE_DEFAULT_VALUES.get(type) : "";
     }
 
     public ConfigVisibility getVisibility() {

diff --git a/.../java/io/quarkus/annotation/processor/generate_doc/GenerateExtensionConfigurationDoc.java b/.../java/io/quarkus/annotation/processor/generate_doc/GenerateExtensionConfigurationDoc.java
@@ -10,19 +10,15 @@
 import java.util.TreeSet;
 import java.util.regex.Matcher;
 
-import javax.lang.model.element.AnnotationMirror;
-import javax.lang.model.element.AnnotationValue;
-import javax.lang.model.element.Element;
-import javax.lang.model.element.ExecutableElement;
-import javax.lang.model.element.PackageElement;
-import javax.lang.model.element.TypeElement;
+import javax.lang.model.element.*;
 import javax.lang.model.type.DeclaredType;
 import javax.lang.model.type.TypeMirror;
 
 import io.quarkus.annotation.processor.Constants;
 import io.quarkus.annotation.processor.StringUtil;
 
 public class GenerateExtensionConfigurationDoc {
+    public static final String STATIC_MODIFIER = "static";
     private final Set<ConfigRootInfo> configRoots = new HashSet<>();
     private final Map<String, TypeElement> configGroups = new HashMap<>();
 
@@ -95,7 +91,7 @@ private String generateConfigsInDescriptorListFormat(Set<ConfigItem> configItems
             sb.append("\n`");
             sb.append(configItem.getPropertyName());
             sb.append("`:: ");
-            sb.append(formatDocs(javaDocProperties.getProperty(configItem.getJavaDocKey())));
+            sb.append(javaDocProperties.getProperty(configItem.getJavaDocKey()));
             sb.append("\n\n");
 
             sb.append("type: `");
@@ -136,7 +132,7 @@ private String generateConfigsInTableFormat(Set<ConfigItem> configItems, Propert
             sb.append("\n|");
             sb.append(configItem.getPropertyName());
             sb.append("\n|");
-            sb.append(formatDocs(javaDocProperties.getProperty(configItem.getJavaDocKey())));
+            sb.append(javaDocProperties.getProperty(configItem.getJavaDocKey()));
             if (configItem.getType().equals(Duration.class.getName())) {
                 sb.append("\n_See duration note below_");
                 hasDurationType = true;
@@ -176,10 +172,23 @@ private void recordConfigItems(Set<ConfigItem> configItems, Element element, Str
                 continue;
             }
 
-            final List<? extends AnnotationMirror> annotationMirrors = enclosedElement.getAnnotationMirrors();
-            String fieldName = enclosedElement.getSimpleName().toString();
+            boolean isStaticField = enclosedElement
+                    .getModifiers()
+                    .stream()
+                    .anyMatch(Modifier.STATIC::equals);
+
+            if (isStaticField) {
+                continue;
+            }
+
             String name = "";
             String defaultValue = Constants.NO_DEFAULT;
+            TypeMirror typeMirror = enclosedElement.asType();
+            String type = typeMirror.toString();
+            Element configGroup = configGroups.get(type);
+            boolean isConfigGroup = configGroup != null;
+            String fieldName = enclosedElement.getSimpleName().toString();
+            final List<? extends AnnotationMirror> annotationMirrors = enclosedElement.getAnnotationMirrors();
 
             for (AnnotationMirror annotationMirror : annotationMirrors) {
                 String annotationName = annotationMirror.getAnnotationType().toString();
@@ -217,11 +226,7 @@ private void recordConfigItems(Set<ConfigItem> configItems, Element element, Str
                 defaultValue = "";
             }
 
-            TypeMirror typeMirror = enclosedElement.asType();
-            String type = typeMirror.toString();
-
-            Element configGroup = configGroups.get(type);
-            if (configGroup != null) {
+            if (isConfigGroup) {
                 recordConfigItems(configItems, configGroup, name, visibility);
             } else {
                 TypeElement clazz = (TypeElement) element;
@@ -259,69 +264,6 @@ private String getKnownGenericType(DeclaredType declaredType) {
         return Constants.OPTIONAL_NUMBER_TYPES.get(declaredType.toString());
     }
 
-    private String formatDocs(String docs) {
-        if (docs == null) {
-            return "";
-        }
-
-        StringBuilder builder = new StringBuilder();
-
-        boolean lastEmpty = false;
-        boolean first = true;
-
-        for (String line : docs.replace("<p>", "\n").split("\n")) {
-            //process line by line
-            String trimmed = line.trim();
-            //if the lines are empty we only include a single empty line at most, and add a # character
-            if (trimmed.isEmpty()) {
-                if (!lastEmpty && !first) {
-                    lastEmpty = true;
-                    builder.append("\n");
-                }
-                continue;
-            }
-            //add the newlines
-            lastEmpty = false;
-            if (first) {
-                first = false;
-            } else {
-                builder.append("\n");
-            }
-            //replace some special characters, others are taken care of by regex below
-            builder.append(trimmed.replace("\n", "\n")
-                    .replace("<ul>", "")
-                    .replace("</ul>", "")
-                    .replace("<li>", " - ")
-                    .replace("</li>", ""));
-        }
-
-        String ret = builder.toString();
-        //replace @code
-        ret = Constants.JAVA_DOC_CODE_PATTERN.matcher(ret).replaceAll("`$1`");
-        //replace @link with a reference to the field name
-        Matcher matcher = Constants.JAVA_DOC_LINK_PATTERN.matcher(ret);
-        while (matcher.find()) {
-            ret = ret.replace(matcher.group(0), "`" + configify(matcher.group(1)) + "`");
-        }
-
-        return ret;
-    }
-
-    private String configify(String group) {
-        //replace uppercase characters with a - followed by lowercase
-        StringBuilder ret = new StringBuilder();
-        for (int i = 0; i < group.length(); ++i) {
-            char c = group.charAt(i);
-            if (Character.isUpperCase(c)) {
-                ret.append("-");
-                ret.append(Character.toLowerCase(c));
-            } else {
-                ret.append(c);
-            }
-        }
-        return ret.toString();
-    }
-
     @Override
     public String toString() {
         return "GenerateExtensionConfigurationDoc{" +

diff --git a/docs/src/main/asciidoc/generated/quarkus-agroal.adoc b/docs/src/main/asciidoc/generated/quarkus-agroal.adoc
@@ -35,7 +35,7 @@ type: `java.time.Duration`. _See duration note below_; default value: `2M`. The
 
 `quarkus.datasource."<named-data-sources>".enable-metrics`:: Enable datasource metrics collection.
 
-type: `boolean`; The configuration is overridable at runtime. 
+type: `boolean`; default value: `false`. The configuration is overridable at runtime. 
 
 
 `quarkus.datasource."<named-data-sources>".idle-removal-interval`:: The interval at which we try to remove idle connections.
@@ -100,7 +100,7 @@ type: `java.time.Duration`. _See duration note below_; default value: `2M`. The
 
 `quarkus.datasource.enable-metrics`:: Enable datasource metrics collection.
 
-type: `boolean`; The configuration is overridable at runtime. 
+type: `boolean`; default value: `false`. The configuration is overridable at runtime. 
 
 
 `quarkus.datasource.idle-removal-interval`:: The interval at which we try to remove idle connections.

diff --git a/docs/src/main/asciidoc/generated/quarkus-arc.adoc b/docs/src/main/asciidoc/generated/quarkus-arc.adoc
@@ -1,9 +1,4 @@
 
-`quarkus.arc.allowed_remove_unused_beans_values`:: 
-
-type: `java.lang.String`; The configuration is visible at build time only. 
-
-
 `quarkus.arc.auto-inject-fields`:: If set to true `@Inject` is automatically added to all non-static fields that are annotated with
 one of the annotations defined by {@link AutoInjectAnnotationBuildItem}.
 
@@ -29,7 +24,7 @@ set out above)
 If set to fwk, then all unused beans will be removed, except the unused beans whose classes are declared
 in the application code
 
-@see UnremovableBeanBuildItem
+see `UnremovableBeanBuildItem`
 
 type: `java.lang.String`; default value: `all`. The configuration is visible at build time only.