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_r363101760
##########
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's legal. IIRC, when we introduced the generator we actually had an
option that was mirroring another one. One could also argue that logically, if
code-structure must not have semantics, duplication of code must be allowed.
However, it seems unlikely that 2 options are being created for which they
1. share a key
2. have an _exactly_ matching description (supposedly written in isolation
from each other)
3. are semantically so aligned that the key/description are still meaningful
4. yet are semantically so different that the accidental configuration can
cause problems.
Overall I think this is mostly a theoretical issue due to us usually
providing a component context via the key; to take your example, all
`RocksDBOptions` have `rocksdb` in their key, with the inverse rightfully being
the case for the `CheckpointingOptions`.
Note that in any case the behavior in this regard isn't different between
`master` and this PR.
----------------------------------------------------------------
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
