zentol commented on a change in pull request #10748: [FLINK-15458][conf][docs]
Add support for whitelisting ambiguous options
URL: https://github.com/apache/flink/pull/10748#discussion_r362788785
##########
File path:
flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocsCompletenessITCase.java
##########
@@ -61,50 +64,103 @@
private static final Formatter htmlFormatter = new HtmlFormatter();
+ // options for which we allow distinct definitions
+ // this allows reporters to define their own options that are
technically only key suffixes
+ private static final Set<String> WELL_DEFINED_WHITELIST = new
HashSet<>(Arrays.asList(
+ ));
+
@Test
public void testCommonSectionCompleteness() throws IOException,
ClassNotFoundException {
- Map<String, DocumentedOption> documentedOptions =
parseDocumentedCommonOptions();
- Map<String, ExistingOption> existingOptions =
findExistingOptions(
+ Map<String, List<DocumentedOption>> documentedOptions =
parseDocumentedCommonOptions();
+ Map<String, List<ExistingOption>> existingOptions =
findExistingOptions(
optionWithMetaInfo ->
optionWithMetaInfo.field.getAnnotation(Documentation.CommonOption.class) !=
null);
+ assertDocumentedOptionsAreWellDefined(documentedOptions);
+ assertExistingOptionsAreWellDefined(existingOptions);
+
compareDocumentedAndExistingOptions(documentedOptions,
existingOptions);
}
@Test
public void testFullReferenceCompleteness() throws IOException,
ClassNotFoundException {
- Map<String, DocumentedOption> documentedOptions =
parseDocumentedOptions();
- Map<String, ExistingOption> existingOptions =
findExistingOptions(ignored -> true);
+ Map<String, List<DocumentedOption>> documentedOptions =
parseDocumentedOptions();
+ Map<String, List<ExistingOption>> existingOptions =
findExistingOptions(ignored -> true);
+
+ assertDocumentedOptionsAreWellDefined(documentedOptions);
+ assertExistingOptionsAreWellDefined(existingOptions);
compareDocumentedAndExistingOptions(documentedOptions,
existingOptions);
}
- private static void compareDocumentedAndExistingOptions(Map<String,
DocumentedOption> documentedOptions, Map<String, ExistingOption>
existingOptions) {
+ private static void assertDocumentedOptionsAreWellDefined(Map<String,
List<DocumentedOption>> documentedOptions) {
+ assertOptionsAreWellDefined(documentedOptions, (option1,
option2) -> {
+ // found a ConfigOption pair with the same key
that aren't equal
+ // we fail here outright as this is not a
documentation-completeness problem
+ if
(!option1.defaultValue.equals(option2.defaultValue)) {
+ throw new AssertionError("Documentation
contains distinct defaults for " +
+ option1.key + " in " +
option1.containingFile + " and " + option2.containingFile + '.');
+ } else {
+ throw new AssertionError("Documentation
contains distinct descriptions for " +
+ option1.key + " in " +
option1.containingFile + " and " + option2.containingFile + '.');
+ }
+ });
+ }
+
+ private static void assertExistingOptionsAreWellDefined(Map<String,
List<ExistingOption>> existingOptions) {
+ assertOptionsAreWellDefined(existingOptions, (option1, option2)
-> {
+ // found a ConfigOption pair with the same key
that aren't equal
+ // we fail here outright as this is not a
documentation-completeness problem
+ if
(!option1.defaultValue.equals(option2.defaultValue)) {
+ throw new AssertionError("Ambiguous
option " + option1.key + " due to distinct default values (" +
option1.defaultValue + " vs " + option2.defaultValue + ").");
+ } else {
+ throw new AssertionError("Ambiguous
option " + option1.key + " due to distinct descriptions.");
+ }
+ });
+ }
+
+ private static <O> void assertOptionsAreWellDefined(Map<String,
List<O>> allOptions, BiFunction<O, O, AssertionError> duplicateHandler) {
+ allOptions.entrySet().stream()
+ .filter(entry ->
!WELL_DEFINED_WHITELIST.contains(entry.getKey()))
+ .map(Map.Entry::getValue)
+ .forEach(options -> options.stream().reduce((option1,
option2) -> {
+ if (option1.equals(option2)) {
Review comment:
That would violate our definition of begin well-defined; from the javadocs:
`no 2 options exist for the same key with different descriptions/default
values`
The organization into separate classes that we have is only for developer
convenience and readability only; it does not (and must not) have any semantics
attached to it. Hence the containing class doesn't matter.
The reason for this is simplicity; we don't have to worry about
* options clashing in their default value, which is difficult to document in
a good way and can lead to subtle issues when de-duplicating options
* options clashing in their description, which is also difficult to document
and usually leads to stale documentation at one place
* options clashing in their type, which may result in a component being
unusable when used in conjunction with another
* users not being able to configure distinct values per option
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
