This is an automated email from the ASF dual-hosted git repository.
trohrmann pushed a commit to branch release-1.5
in repository https://gitbox.apache.org/repos/asf/flink.git
commit 1efe5b90adf1dbc8ef4d036f918d4b59124a4f50
Author: Till Rohrmann <trohrm...@apache.org>
AuthorDate: Fri Nov 16 17:47:45 2018 +0100
[FLINK-10880] Add Documentation.ExcludeFromDocumentation to exclude
ConfigOptions from documentation
The annotation Documentation.ExcludeFromDocumentation can be used to
annotate ConfigOptions
with in order to not include them in the documentation.
---
.../flink/annotation/docs/Documentation.java | 13 +++++++
.../configuration/ConfigOptionsDocGenerator.java | 11 +++++-
.../ConfigOptionsDocGeneratorTest.java | 40 ++++++++++++++++++++++
3 files changed, 63 insertions(+), 1 deletion(-)
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 4e424c7..d5e1268 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
@@ -40,6 +40,19 @@ public final class Documentation {
String 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 b73a40e..a9cebd6 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
@@ -148,7 +148,7 @@ public class ConfigOptionsDocGenerator {
List<OptionWithMetaInfo> 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));
}
}
@@ -159,6 +159,15 @@ public class ConfigOptionsDocGenerator {
}
}
+ 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 4176c5d..7306e4d 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
@@ -215,4 +215,44 @@ public class ConfigOptionsDocGeneratorTest {
assertEquals(expectedTable, htmlTable);
}
+ static class TestConfigGroupWithExclusion {
+ public static ConfigOption<Integer> firstOption = ConfigOptions
+ .key("first.option.a")
+ .defaultValue(2)
+ .withDescription("This is example description for the
first option.");
+
+ @Documentation.ExcludeFromDocumentation
+ public static ConfigOption<String> 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 =
+ "<table class=\"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: 65%\">Description</th>\n" +
+ " </tr>\n" +
+ " </thead>\n" +
+ " <tbody>\n" +
+ " <tr>\n" +
+ "
<td><h5>first.option.a</h5></td>\n" +
+ " <td style=\"word-wrap:
break-word;\">2</td>\n" +
+ " <td>This is example description
for the first option.</td>\n" +
+ " </tr>\n" +
+ " </tbody>\n" +
+ "</table>\n";
+ final String htmlTable =
ConfigOptionsDocGenerator.generateTablesForClass(TestConfigGroupWithExclusion.class).get(0).f1;
+
+ assertEquals(expectedTable, htmlTable);
+ }
}
