You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by xt...@apache.org on 2022/06/10 02:07:30 UTC
[flink] branch master updated: [FLINK-27920][doc] Documented enums constant support ExcludeFromDocumentation annotation
This is an automated email from the ASF dual-hosted git repository.
xtsong pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/master by this push:
new 608e40ac42b [FLINK-27920][doc] Documented enums constant support ExcludeFromDocumentation annotation
608e40ac42b is described below
commit 608e40ac42bacda2aacc6be57d2072ece7f0cf31
Author: Weijie Guo <re...@163.com>
AuthorDate: Wed Jun 8 18:34:14 2022 +0800
[FLINK-27920][doc] Documented enums constant support ExcludeFromDocumentation annotation
This closes #19888
---
.../configuration/ConfigOptionsDocGenerator.java | 25 +++++-
.../ConfigOptionsDocGeneratorTest.java | 89 ++++++++++++++++++++++
.../metrics/influxdb/InfluxdbReporterOptions.java | 2 +-
3 files changed, 112 insertions(+), 4 deletions(-)
diff --git a/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java b/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
index 4fcde8cee08..5b557cd105f 100644
--- a/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
+++ b/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
@@ -30,6 +30,7 @@ import org.apache.flink.configuration.description.Formatter;
import org.apache.flink.configuration.description.HtmlFormatter;
import org.apache.flink.configuration.description.InlineElement;
import org.apache.flink.configuration.description.TextElement;
+import org.apache.flink.util.ExceptionUtils;
import org.apache.flink.util.TimeUtils;
import org.apache.flink.util.function.ThrowingConsumer;
@@ -57,8 +58,10 @@ import java.util.HashSet;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
+import java.util.Objects;
import java.util.Optional;
import java.util.Set;
+import java.util.concurrent.atomic.AtomicReference;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
@@ -523,16 +526,32 @@ public class ConfigOptionsDocGenerator {
if (!clazz.isEnum()) {
return null;
}
-
+ AtomicReference<IllegalAccessException> exception = new AtomicReference<>(null);
InlineElement[] optionDescriptions =
- Arrays.stream(clazz.getEnumConstants())
+ Arrays.stream(clazz.getDeclaredFields())
+ .filter(field -> field.isEnumConstant() && shouldBeDocumented(field))
+ .map(
+ field -> {
+ try {
+ return field.get(null);
+ } catch (IllegalAccessException e) {
+ exception.set(
+ ExceptionUtils.firstOrSuppressed(
+ e, exception.get()));
+ }
+ return null;
+ })
+ .filter(Objects::nonNull)
.map(ConfigOptionsDocGenerator::formatEnumOption)
.map(
elements ->
TextElement.wrap(
elements.stream().toArray(InlineElement[]::new)))
.toArray(InlineElement[]::new);
-
+ if (exception.get() != null) {
+ throw new RuntimeException(
+ "config option should have public access right.", exception.get());
+ }
return Description.builder().text("Possible values:").list(optionDescriptions).build();
}
diff --git a/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java b/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
index e621921043e..3709b412fae 100644
--- a/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
+++ b/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
@@ -592,6 +592,95 @@ class ConfigOptionsDocGeneratorTest {
assertThat(htmlTable).isEqualTo(expectedTable);
}
+ private enum TestEnumWithExclusion {
+ VALUE_1,
+ @Documentation.ExcludeFromDocumentation
+ VALUE_2,
+ VALUE_3
+ }
+
+ private enum DescribedTestEnumWithExclusion implements DescribedEnum {
+ A(text("First letter of the alphabet")),
+ B(text("Second letter of the alphabet")),
+ @Documentation.ExcludeFromDocumentation
+ C(text("Third letter of the alphabet"));
+
+ private final InlineElement description;
+
+ DescribedTestEnumWithExclusion(InlineElement description) {
+ this.description = description;
+ }
+
+ @Override
+ public InlineElement getDescription() {
+ return description;
+ }
+ }
+
+ static class TestConfigGroupWithEnumConstantExclusion {
+
+ public static ConfigOption<TestEnumWithExclusion> enumWithExclusion =
+ ConfigOptions.key("exclude.enum")
+ .enumType(TestEnumWithExclusion.class)
+ .defaultValue(TestEnumWithExclusion.VALUE_1)
+ .withDescription("Description");
+
+ public static ConfigOption<List<TestEnumWithExclusion>> enumListWithExclusion =
+ ConfigOptions.key("exclude.enum.list")
+ .enumType(TestEnumWithExclusion.class)
+ .asList()
+ .defaultValues(TestEnumWithExclusion.VALUE_1, TestEnumWithExclusion.VALUE_3)
+ .withDescription("Description");
+
+ public static ConfigOption<DescribedTestEnumWithExclusion> enumDescribedWithExclusion =
+ ConfigOptions.key("exclude.enum.desc")
+ .enumType(DescribedTestEnumWithExclusion.class)
+ .noDefaultValue()
+ .withDescription("Description");
+ }
+
+ @Test
+ void testConfigGroupWithEnumConstantExclusion() {
+ final String expectedTable =
+ "<table class=\"configuration table table-bordered\">\n"
+ + " <thead>\n"
+ + " <tr>\n"
+ + " <th class=\"text-left\" style=\"width: 20%\">Key</th>\n"
+ + " <th class=\"text-left\" style=\"width: 15%\">Default</th>\n"
+ + " <th class=\"text-left\" style=\"width: 10%\">Type</th>\n"
+ + " <th class=\"text-left\" style=\"width: 55%\">Description</th>\n"
+ + " </tr>\n"
+ + " </thead>\n"
+ + " <tbody>\n"
+ + " <tr>\n"
+ + " <td><h5>exclude.enum</h5></td>\n"
+ + " <td style=\"word-wrap: break-word;\">VALUE_1</td>\n"
+ + " <td><p>Enum</p></td>\n"
+ + " <td>Description<br /><br />Possible values:<ul><li>\"VALUE_1\"</li><li>\"VALUE_3\"</li></ul></td>\n"
+ + " </tr>\n"
+ + " <tr>\n"
+ + " <td><h5>exclude.enum.desc</h5></td>\n"
+ + " <td style=\"word-wrap: break-word;\">(none)</td>\n"
+ + " <td><p>Enum</p></td>\n"
+ + " <td>Description<br /><br />Possible values:<ul><li>\"A\": First letter of the alphabet</li><li>\"B\": Second letter of the alphabet</li></ul></td>\n"
+ + " </tr>\n"
+ + " <tr>\n"
+ + " <td><h5>exclude.enum.list</h5></td>\n"
+ + " <td style=\"word-wrap: break-word;\">VALUE_1;<wbr>VALUE_3</td>\n"
+ + " <td><p>List<Enum></p></td>\n"
+ + " <td>Description<br /><br />Possible values:<ul><li>\"VALUE_1\"</li><li>\"VALUE_3\"</li></ul></td>\n"
+ + " </tr>\n"
+ + " </tbody>\n"
+ + "</table>\n";
+ final String htmlTable =
+ ConfigOptionsDocGenerator.generateTablesForClass(
+ TestConfigGroupWithEnumConstantExclusion.class)
+ .get(0)
+ .f1;
+
+ assertThat(htmlTable).isEqualTo(expectedTable);
+ }
+
@ConfigGroups(groups = {@ConfigGroup(name = "firstGroup", keyPrefix = "first")})
static class EmptyConfigOptions {}
diff --git a/flink-metrics/flink-metrics-influxdb/src/main/java/org/apache/flink/metrics/influxdb/InfluxdbReporterOptions.java b/flink-metrics/flink-metrics-influxdb/src/main/java/org/apache/flink/metrics/influxdb/InfluxdbReporterOptions.java
index 51f4bfd9eb6..7edc050cace 100644
--- a/flink-metrics/flink-metrics-influxdb/src/main/java/org/apache/flink/metrics/influxdb/InfluxdbReporterOptions.java
+++ b/flink-metrics/flink-metrics-influxdb/src/main/java/org/apache/flink/metrics/influxdb/InfluxdbReporterOptions.java
@@ -126,7 +126,7 @@ public class InfluxdbReporterOptions {
}
/** Supported URL schemes for the {@link InfluxdbReporter}. */
- enum Scheme {
+ public enum Scheme {
HTTP("http"),
HTTPS("https");