Docs generator: do not print all enum constants for all enums (#4156)

For enums with more than 3 constants, we are now printing just the first 3, in order to avoid messing up the HTML table rendering. The full list of names is still viewable through an HTML tooltip.

The format also now includes the token `enum` before the list of enum names, for clarity.

Author: adutra

site/content/in-dev/unreleased/configuration/config-sections/smallrye-polaris_authentication.md

@@ -25,7 +25,7 @@ build:
 
 | Property | Default Value | Type | Description |
 |----------|---------------|------|-------------|
-| `polaris.authentication.type` | `internal` | `INTERNAL, EXTERNAL, MIXED` | The type of authentication to use.  |
+| `polaris.authentication.type` | `internal` | `enum (INTERNAL, EXTERNAL, MIXED)` | The type of authentication to use.  |
 | `polaris.authentication.authenticator.type` | `default` | `string` | The type of the identity provider. Must be a registered (`Authenticator`) identifier.  |
 | `polaris.authentication.token-service.type` | `default` | `string` | The type of the OAuth2 service. Must be a registered (`IcebergRestOAuth2ApiService`) identifier.  |
 | `polaris.authentication.token-broker.max-token-generation` | `PT1H` | `duration` | The maximum token duration.  |
@@ -34,7 +34,7 @@ build:
 | `polaris.authentication.token-broker.rsa-key-pair.private-key-file` |  | `path` | The path to the private key file.  |
 | `polaris.authentication.token-broker.symmetric-key.secret` |  | `string` | The secret to use for both signing and verifying signatures. Either this option of (`#file()`) must be provided.  |
 | `polaris.authentication.token-broker.symmetric-key.file` |  | `path` | The file to read the secret from. Either this option of (`#secret()`) must be provided.  |
-| `polaris.authentication.`_`<realm>`_`.type` | `internal` | `INTERNAL, EXTERNAL, MIXED` | The type of authentication to use.  |
+| `polaris.authentication.`_`<realm>`_`.type` | `internal` | `enum (INTERNAL, EXTERNAL, MIXED)` | The type of authentication to use.  |
 | `polaris.authentication.`_`<realm>`_`.authenticator.type` | `default` | `string` | The type of the identity provider. Must be a registered (`Authenticator`) identifier.  |
 | `polaris.authentication.`_`<realm>`_`.token-service.type` | `default` | `string` | The type of the OAuth2 service. Must be a registered (`IcebergRestOAuth2ApiService`) identifier.  |
 | `polaris.authentication.`_`<realm>`_`.token-broker.max-token-generation` | `PT1H` | `duration` | The maximum token duration.  |

site/content/in-dev/unreleased/configuration/config-sections/smallrye-polaris_authorization_opa.md

@@ -30,7 +30,7 @@ Beta Feature: OPA authorization is currently in Beta and is not a stable  releas
 | Property | Default Value | Type | Description |
 |----------|---------------|------|-------------|
 | `polaris.authorization.opa.policy-uri` |  | `uri` |  |
-| `polaris.authorization.opa.auth.type` | `none` | `NONE, BEARER` | Type of authentication  |
+| `polaris.authorization.opa.auth.type` | `none` | `enum (NONE, BEARER)` | Type of authentication  |
 | `polaris.authorization.opa.auth.bearer.static-token.value` |  | `string` | Static bearer token value  |
 | `polaris.authorization.opa.auth.bearer.file-based.path` |  | `path` | Path to file containing bearer token  |
 | `polaris.authorization.opa.auth.bearer.file-based.refresh-interval` |  | `duration` | How often to refresh file-based bearer tokens (defaults to 5 minutes if not specified)  |

tools/config-docs/generator/src/main/java/org/apache/polaris/docs/generator/MarkdownPropertyFormatter.java

@@ -33,6 +33,14 @@ public String propertySuffix() {
   }
 
   public String propertyType() {
+    String tooltip = propertyInfo.enumTooltipText();
+    if (tooltip != null) {
+      return "<span title=\""
+          + tooltip
+          + "\"><code>"
+          + propertyInfo.simplifiedTypeName()
+          + "</code></span>";
+    }
     return '`' + propertyInfo.simplifiedTypeName() + '`';
   }
 }

tools/config-docs/generator/src/main/java/org/apache/polaris/docs/generator/PropertyInfo.java

@@ -33,4 +33,8 @@ public interface PropertyInfo {
   DocCommentTree doc();
 
   Optional<Class<?>> groupType();
+
+  default String enumTooltipText() {
+    return null;
+  }
 }

tools/config-docs/generator/src/main/java/org/apache/polaris/docs/generator/SmallRyeConfigPropertyInfo.java

@@ -102,6 +102,11 @@ public String simplifiedTypeName() {
     return simplifiedTypeName(property);
   }
 
+  @Override
+  public String enumTooltipText() {
+    return enumTooltipText(property);
+  }
+
   public boolean isSettableType() {
     return isSettableType(property);
   }
@@ -172,10 +177,14 @@ public static String simplifiedTypeName(Property property) {
       var leaf = property.asLeaf();
       var rawType = leaf.getValueRawType();
       if (rawType.isEnum()) {
-        return Arrays.stream(rawType.getEnumConstants())
-            .map(Enum.class::cast)
-            .map(Enum::name)
-            .collect(Collectors.joining(", "));
+        Object[] constants = rawType.getEnumConstants();
+        String firstThree =
+            Arrays.stream(constants)
+                .limit(3)
+                .map(Enum.class::cast)
+                .map(Enum::name)
+                .collect(Collectors.joining(", "));
+        return "enum (" + firstThree + (constants.length > 3 ? ", ..." : "") + ")";
       }
       if (property.hasConvertWith()) {
         // A smallrye-config converter always takes a string.
@@ -239,6 +248,31 @@ public static String simplifiedTypeName(Property property) {
     throw new UnsupportedOperationException("Don't know how to handle " + property);
   }
 
+  public static String enumTooltipText(Property property) {
+    if (property.isOptional()) {
+      return enumTooltipText(property.asOptional().getNestedProperty());
+    }
+    if (property.isCollection()) {
+      return enumTooltipText(property.asCollection().getElement());
+    }
+    if (property.isMap()) {
+      return enumTooltipText(property.asMap().getValueProperty());
+    }
+    if (property.isLeaf()) {
+      var rawType = property.asLeaf().getValueRawType();
+      if (rawType.isEnum()) {
+        Object[] constants = rawType.getEnumConstants();
+        if (constants.length > 3) {
+          return Arrays.stream(constants)
+              .map(Enum.class::cast)
+              .map(Enum::name)
+              .collect(Collectors.joining(", "));
+        }
+      }
+    }
+    return null;
+  }
+
   @Override
   public DocCommentTree doc() {
     return doc;

tools/config-docs/generator/src/test/java/org/apache/polaris/docs/generator/TestDocGenTool.java

@@ -143,10 +143,13 @@ public void docGenTool(@TempDir Path dir) throws Exception {
                     | `my.types.float-prim` |  | `float` |  |
                     | `my.types.bool-boxed` |  | `boolean` |  |
                     | `my.types.bool-prim` |  | `boolean` |  |
-                    | `my.types.enum-thing` |  | `ONE, TWO, THREE` |  |
-                    | `my.types.optional-enum` |  | `ONE, TWO, THREE` |  |
-                    | `my.types.list-of-enum` |  | `list of ONE, TWO, THREE` |  |
-                    | `my.types.map-to-enum.`_`<name>`_ |  | `ONE, TWO, THREE` |  |
+                    | `my.types.enum-thing` |  | `enum (ONE, TWO, THREE)` |  |
+                    | `my.types.optional-enum` |  | `enum (ONE, TWO, THREE)` |  |
+                    | `my.types.list-of-enum` |  | `list of enum (ONE, TWO, THREE)` |  |
+                    | `my.types.map-to-enum.`_`<name>`_ |  | `enum (ONE, TWO, THREE)` |  |
+                    | `my.types.large-enum` |  | <span title="ONE, TWO, THREE, FOUR"><code>enum (ONE, TWO, THREE, ...)</code></span> |  |
+                    | `my.types.optional-large-enum` |  | <span title="ONE, TWO, THREE, FOUR"><code>enum (ONE, TWO, THREE, ...)</code></span> |  |
+                    | `my.types.list-of-large-enum` |  | <span title="ONE, TWO, THREE, FOUR"><code>list of enum (ONE, TWO, THREE, ...)</code></span> |  |
                     | `my.types.optional-bool` |  | `boolean` |  |
                     | `my.types.mapped-a.some-weird-name` | `some-default` | `string` | Something that configures something.  |
                     | `my.types.mapped-a.some-duration` |  | `duration` | A duration of something.  |

tools/config-docs/generator/src/test/java/tests/smallrye/AllTypes.java

@@ -97,6 +97,12 @@ public interface AllTypes extends InterfaceOne {
 
   Map<String, SomeEnum> mapToEnum();
 
+  LargeEnum largeEnum();
+
+  Optional<LargeEnum> optionalLargeEnum();
+
+  List<LargeEnum> listOfLargeEnum();
+
   Optional<Boolean> optionalBool();
 
   /** My {@code MappedA}. */

tools/config-docs/generator/src/test/java/tests/smallrye/LargeEnum.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright (C) 2024 Dremio
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tests.smallrye;
+
+public enum LargeEnum {
+  ONE,
+  TWO,
+  THREE,
+  FOUR
+}