Docs-gen: more documented types, don't expose "Java types" (#8705)

projectnessie · Jun 6, 2024 · 1ca45e1 · 1ca45e1
1 parent 3397ded
commit 1ca45e1
Show file tree

Hide file tree

Showing 4 changed files with 75 additions and 30 deletions.
diff --git a/...ator/doclet/src/main/java/org/projectnessie/nessie/docgen/SmallRyeConfigPropertyInfo.java b/...ator/doclet/src/main/java/org/projectnessie/nessie/docgen/SmallRyeConfigPropertyInfo.java
@@ -22,6 +22,10 @@
 import io.smallrye.config.ConfigMappingInterface.MayBeOptionalProperty;
 import io.smallrye.config.ConfigMappingInterface.PrimitiveProperty;
 import io.smallrye.config.ConfigMappingInterface.Property;
+import java.net.URI;
+import java.nio.file.Path;
+import java.time.Duration;
+import java.time.Instant;
 import java.util.Arrays;
 import java.util.Optional;
 import java.util.OptionalDouble;
@@ -114,6 +118,10 @@ public static String simplifiedTypeName(Property property) {
             .map(Enum::name)
             .collect(Collectors.joining(", "));
       }
+      if (property.hasConvertWith()) {
+        // A smallrye-config converter always takes a string.
+        return "string";
+      }
       if (rawType == OptionalInt.class) {
         return "int";
       }
@@ -123,6 +131,9 @@ public static String simplifiedTypeName(Property property) {
       if (rawType == OptionalDouble.class) {
         return "double";
       }
+      if (rawType == Boolean.class) {
+        return "boolean";
+      }
       if (rawType == Byte.class) {
         return "byte";
       }
@@ -144,10 +155,27 @@ public static String simplifiedTypeName(Property property) {
       if (rawType == Character.class) {
         return "char";
       }
+      if (rawType == String.class) {
+        return "string";
+      }
+      if (rawType == Duration.class) {
+        return "duration";
+      }
+      if (rawType == Instant.class) {
+        return "instant";
+      }
+      if (rawType == URI.class) {
+        return "uri";
+      }
+      if (rawType == Path.class) {
+        return "path";
+      }
       return rawType.getSimpleName();
     }
     if (property.isGroup()) {
-      return property.asGroup().getGroupType().getInterfaceType().getSimpleName();
+      // Represents a type that consists of multiple fields/properties, which are documented
+      // underneath this property.
+      return "";
     }
     throw new UnsupportedOperationException("Don't know how to handle " + property);
   }

diff --git a/...s/doc-generator/doclet/src/main/java/org/projectnessie/nessie/docgen/SmallryeConfigs.java b/...s/doc-generator/doclet/src/main/java/org/projectnessie/nessie/docgen/SmallryeConfigs.java
@@ -60,6 +60,9 @@ public SmallRyeConfigMappingInfo getConfigMappingInfo(Class<?> type) {
       info = new SmallRyeConfigMappingInfo("");
       configMappingByType.put(typeName, info);
       TypeElement elem = env.getElementUtils().getTypeElement(typeName);
+      if (elem == null) {
+        throw new NullPointerException("Type " + typeName + " not found");
+      }
       elem.accept(visitor(), null);
     }
     return info;

diff --git a/tools/doc-generator/doclet/src/test/java/org/projectnessie/nessie/docgen/TestDocGenTool.java b/tools/doc-generator/doclet/src/test/java/org/projectnessie/nessie/docgen/TestDocGenTool.java
@@ -92,9 +92,9 @@ public void docGenTool(@TempDir Path dir) throws Exception {
                 + "\n"
                 + "| Property | Default Value | Type | Description |\n"
                 + "|----------|---------------|------|-------------|\n"
-                + "| `my.prefix.some-weird-name` | `some-default` | `String` | Something that configures something.  |\n"
-                + "| `my.prefix.some-duration` |  | `Duration` | A duration of something.  |\n"
-                + "| `my.prefix.nested` |  | `OtherMapped` |  |\n"
+                + "| `my.prefix.some-weird-name` | `some-default` | `string` | Something that configures something.  |\n"
+                + "| `my.prefix.some-duration` |  | `duration` | A duration of something.  |\n"
+                + "| `my.prefix.nested` |  | `` |  |\n"
                 + "| `my.prefix.nested.other-int` |  | `int` |  |\n"
                 + "| `my.prefix.nested.boxed-double` |  | `double` | <br><br>_Deprecated_  |\n"
                 + "| `my.prefix.some-int-thing` |  | `int` | Something int-ish.  |\n");
@@ -106,16 +106,20 @@ public void docGenTool(@TempDir Path dir) throws Exception {
                 + "\n"
                 + "| Property | Default Value | Type | Description |\n"
                 + "|----------|---------------|------|-------------|\n"
-                + "| `my.types.string` |  | `String` |  |\n"
-                + "| `my.types.optional-string` |  | `String` |  |\n"
-                + "| `my.types.duration` |  | `Duration` |  |\n"
-                + "| `my.types.optional-duration` |  | `Duration` |  |\n"
-                + "| `my.types.path` |  | `Path` |  |\n"
-                + "| `my.types.optional-path` |  | `Path` |  |\n"
-                + "| `my.types.string-list` |  | `list of String` |  |\n"
-                + "| `my.types.string-string-map.`_`<stringkey>`_ |  | `String` |  |\n"
-                + "| `my.types.string-duration-map.`_`<key2>`_ |  | `Duration` |  |\n"
-                + "| `my.types.string-path-map.`_`<name>`_ |  | `Path` |  |\n"
+                + "| `my.types.string` |  | `string` |  |\n"
+                + "| `my.types.optional-string` |  | `string` |  |\n"
+                + "| `my.types.duration` |  | `duration` |  |\n"
+                + "| `my.types.optional-duration` |  | `duration` |  |\n"
+                + "| `my.types.path` |  | `path` |  |\n"
+                + "| `my.types.optional-path` |  | `path` |  |\n"
+                + "| `my.types.uri` |  | `uri` |  |\n"
+                + "| `my.types.optional-uri` |  | `uri` |  |\n"
+                + "| `my.types.instant` |  | `instant` |  |\n"
+                + "| `my.types.optional-instant` |  | `instant` |  |\n"
+                + "| `my.types.string-list` |  | `list of string` |  |\n"
+                + "| `my.types.string-string-map.`_`<stringkey>`_ |  | `string` |  |\n"
+                + "| `my.types.string-duration-map.`_`<key2>`_ |  | `duration` |  |\n"
+                + "| `my.types.string-path-map.`_`<name>`_ |  | `path` |  |\n"
                 + "| `my.types.optional-int` |  | `int` |  |\n"
                 + "| `my.types.optional-long` |  | `long` |  |\n"
                 + "| `my.types.optional-double` |  | `double` |  |\n"
@@ -127,36 +131,36 @@ public void docGenTool(@TempDir Path dir) throws Exception {
                 + "| `my.types.long-prim` |  | `long` |  |\n"
                 + "| `my.types.double-prim` |  | `double` |  |\n"
                 + "| `my.types.float-prim` |  | `float` |  |\n"
-                + "| `my.types.bool-boxed` |  | `Boolean` |  |\n"
+                + "| `my.types.bool-boxed` |  | `boolean` |  |\n"
                 + "| `my.types.bool-prim` |  | `boolean` |  |\n"
                 + "| `my.types.enum-thing` |  | `ONE, TWO, THREE` |  |\n"
                 + "| `my.types.optional-enum` |  | `ONE, TWO, THREE` |  |\n"
                 + "| `my.types.list-of-enum` |  | `list of ONE, TWO, THREE` |  |\n"
                 + "| `my.types.map-to-enum.`_`<name>`_ |  | `ONE, TWO, THREE` |  |\n"
-                + "| `my.types.optional-bool` |  | `Boolean` |  |\n"
-                + "| `my.types.mapped-a` |  | `MappedA` | My `MappedA`.  |\n"
-                + "| `my.types.mapped-a.some-weird-name` | `some-default` | `String` | Something that configures something.  |\n"
-                + "| `my.types.mapped-a.some-duration` |  | `Duration` | A duration of something.  |\n"
-                + "| `my.types.mapped-a.nested` |  | `OtherMapped` |  |\n"
+                + "| `my.types.optional-bool` |  | `boolean` |  |\n"
+                + "| `my.types.mapped-a` |  | `` | My `MappedA`.  |\n"
+                + "| `my.types.mapped-a.some-weird-name` | `some-default` | `string` | Something that configures something.  |\n"
+                + "| `my.types.mapped-a.some-duration` |  | `duration` | A duration of something.  |\n"
+                + "| `my.types.mapped-a.nested` |  | `` |  |\n"
                 + "| `my.types.mapped-a.nested.other-int` |  | `int` |  |\n"
                 + "| `my.types.mapped-a.nested.boxed-double` |  | `double` | <br><br>_Deprecated_  |\n"
                 + "| `my.types.mapped-a.some-int-thing` |  | `int` | Something int-ish.  |\n"
-                + "| `my.types.optional-mapped-a` |  | `MappedA` | Optional `MappedA`.  |\n"
-                + "| `my.types.optional-mapped-a.some-weird-name` | `some-default` | `String` | Something that configures something.  |\n"
-                + "| `my.types.optional-mapped-a.some-duration` |  | `Duration` | A duration of something.  |\n"
-                + "| `my.types.optional-mapped-a.nested` |  | `OtherMapped` |  |\n"
+                + "| `my.types.optional-mapped-a` |  | `` | Optional `MappedA`.  |\n"
+                + "| `my.types.optional-mapped-a.some-weird-name` | `some-default` | `string` | Something that configures something.  |\n"
+                + "| `my.types.optional-mapped-a.some-duration` |  | `duration` | A duration of something.  |\n"
+                + "| `my.types.optional-mapped-a.nested` |  | `` |  |\n"
                 + "| `my.types.optional-mapped-a.nested.other-int` |  | `int` |  |\n"
                 + "| `my.types.optional-mapped-a.nested.boxed-double` |  | `double` | <br><br>_Deprecated_  |\n"
                 + "| `my.types.optional-mapped-a.some-int-thing` |  | `int` | Something int-ish.  |\n"
-                + "| `my.types.map-string-mapped-a.`_`<mappy>`_ |  | `MappedA` | Map of string to `MappedA`.  |\n"
-                + "| `my.types.map-string-mapped-a.`_`<mappy>`_`.some-weird-name` | `some-default` | `String` | Something that configures something.  |\n"
-                + "| `my.types.map-string-mapped-a.`_`<mappy>`_`.some-duration` |  | `Duration` | A duration of something.  |\n"
-                + "| `my.types.map-string-mapped-a.`_`<mappy>`_`.nested` |  | `OtherMapped` |  |\n"
+                + "| `my.types.map-string-mapped-a.`_`<mappy>`_ |  | `` | Map of string to `MappedA`.  |\n"
+                + "| `my.types.map-string-mapped-a.`_`<mappy>`_`.some-weird-name` | `some-default` | `string` | Something that configures something.  |\n"
+                + "| `my.types.map-string-mapped-a.`_`<mappy>`_`.some-duration` |  | `duration` | A duration of something.  |\n"
+                + "| `my.types.map-string-mapped-a.`_`<mappy>`_`.nested` |  | `` |  |\n"
                 + "| `my.types.map-string-mapped-a.`_`<mappy>`_`.nested.other-int` |  | `int` |  |\n"
                 + "| `my.types.map-string-mapped-a.`_`<mappy>`_`.nested.boxed-double` |  | `double` | <br><br>_Deprecated_  |\n"
                 + "| `my.types.map-string-mapped-a.`_`<mappy>`_`.some-int-thing` |  | `int` | Something int-ish.  |\n"
-                + "| `my.types.some-duration` |  | `Duration` | A duration of something.  |\n"
-                + "| `my.types.config-option-foo` |  | `String` | Something that configures something.  |\n"
+                + "| `my.types.some-duration` |  | `duration` | A duration of something.  |\n"
+                + "| `my.types.config-option-foo` |  | `string` | Something that configures something.  |\n"
                 + "| `my.types.some-int-thing` |  | `int` | Something int-ish.  |\n");
     soft.assertThat(fileExtremelyNested)
         .isRegularFile()

diff --git a/tools/doc-generator/doclet/src/test/java/tests/smallrye/AllTypes.java b/tools/doc-generator/doclet/src/test/java/tests/smallrye/AllTypes.java
@@ -16,8 +16,10 @@
 package tests.smallrye;
 
 import io.smallrye.config.ConfigMapping;
+import java.net.URI;
 import java.nio.file.Path;
 import java.time.Duration;
+import java.time.Instant;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -41,6 +43,14 @@ public interface AllTypes extends IntOne {
 
   Optional<Path> optionalPath();
 
+  URI uri();
+
+  Optional<URI> optionalUri();
+
+  Instant instant();
+
+  Optional<Instant> optionalInstant();
+
   List<String> stringList();
 
   @ConfigPropertyName("stringkey")