diff --git a/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java b/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java index c193c4e055499..aed0d2975f490 100644 --- a/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java +++ b/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java @@ -59,6 +59,19 @@ public final class Documentation { int position() default Integer.MAX_VALUE; } + /** + * Annotation used on config option fields to exclude the config option from documentation. + */ + @Target(ElementType.FIELD) + @Retention(RetentionPolicy.RUNTIME) + @Internal + public @interface ExcludeFromDocumentation { + /** + * The optional reason why the config option is excluded from documentation. + */ + String value() default ""; + } + private Documentation(){ } } 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 d0f665a5051e4..36a2203b7e4f7 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 @@ -202,7 +202,7 @@ static List extractConfigOptions(Class clazz) { List configOptions = new ArrayList<>(8); Field[] fields = clazz.getFields(); for (Field field : fields) { - if (field.getType().equals(ConfigOption.class) && field.getAnnotation(Deprecated.class) == null) { + if (isConfigOption(field) && shouldBeDocumented(field)) { configOptions.add(new OptionWithMetaInfo((ConfigOption) field.get(null), field)); } } @@ -213,6 +213,15 @@ static List extractConfigOptions(Class clazz) { } } + private static boolean isConfigOption(Field field) { + return field.getType().equals(ConfigOption.class); + } + + private static boolean shouldBeDocumented(Field field) { + return field.getAnnotation(Deprecated.class) == null && + field.getAnnotation(Documentation.ExcludeFromDocumentation.class) == null; + } + /** * Transforms this configuration group into HTML formatted table. * Options are sorted alphabetically by key. 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 a0eade69d455f..c0fb7c99eda73 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 @@ -266,4 +266,45 @@ public void testCommonOptions() throws IOException, ClassNotFoundException { assertEquals(expected, output); } + + static class TestConfigGroupWithExclusion { + public static ConfigOption firstOption = ConfigOptions + .key("first.option.a") + .defaultValue(2) + .withDescription("This is example description for the first option."); + + @Documentation.ExcludeFromDocumentation + public static ConfigOption excludedOption = ConfigOptions + .key("excluded.option.a") + .noDefaultValue() + .withDescription("This should not be documented."); + } + + /** + * Tests that {@link ConfigOption} annotated with {@link Documentation.ExcludeFromDocumentation} + * are not documented. + */ + @Test + public void testConfigOptionExclusion() { + final String expectedTable = + "\n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + "
KeyDefaultDescription
first.option.a
2This is example description for the first option.
\n"; + final String htmlTable = ConfigOptionsDocGenerator.generateTablesForClass(TestConfigGroupWithExclusion.class).get(0).f1; + + assertEquals(expectedTable, htmlTable); + } }