[GitHub] [flink] tillrohrmann commented on a change in pull request #10748: [FLINK-15458][conf][docs] Add support for whitelisting ambiguous options

[GitBox <gi...@apache.org>]

tillrohrmann 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_r365309969
 
 

 ##########
 File path: flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocsCompletenessITCase.java
 ##########
 @@ -61,50 +64,105 @@
 
 	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(
+		"host",
+		"port"
+	));
+
 	@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)) {
+					// we allow multiple instances of ConfigOptions with the same key if they are identical
+					return option1;
+				} else {
+					throw duplicateHandler.apply(option1, option2);
+				}
+			}));
+	}
+
+	private static void compareDocumentedAndExistingOptions(Map<String, List<DocumentedOption>> documentedOptions, Map<String, List<ExistingOption>> existingOptions) {
 		final Collection<String> problems = new ArrayList<>(0);
 
 		// first check that all existing options are properly documented
-		existingOptions.forEach((key, supposedState) -> {
-			DocumentedOption documentedState = documentedOptions.remove(key);
-
-			// if nothing matches the docs for this option are up-to-date
-			if (documentedState == null) {
-				// option is not documented at all
-				problems.add("Option " + supposedState.key + " in " + supposedState.containingClass + " is not documented.");
-			} else if (!supposedState.defaultValue.equals(documentedState.defaultValue)) {
-				// default is outdated
-				problems.add("Documented default of " + supposedState.key + " in " + supposedState.containingClass +
-					" is outdated. Expected: " + supposedState.defaultValue + " Actual: " + documentedState.defaultValue);
-			} else if (!supposedState.description.equals(documentedState.description)) {
-				// description is outdated
-				problems.add("Documented description of " + supposedState.key + " in " + supposedState.containingClass +
-					" is outdated.");
+		existingOptions.forEach((key, supposedStates) -> {
+			List<DocumentedOption> documentedState = documentedOptions.remove(key);
+
+			for (ExistingOption supposedState : supposedStates) {
+				if (documentedState == null || documentedState.isEmpty()) {
+					// option is not documented at all
+					problems.add("Option " + supposedState.key + " in " + supposedState.containingClass + " is not documented.");
+				} else if (documentedState.stream().noneMatch(documentedOption -> supposedState.defaultValue.equals(documentedOption.defaultValue))) {
+					// default is outdated
+					problems.add("Documented default of " + supposedState.key + " in " + supposedState.containingClass +
+						" is outdated. Expected: " + supposedState.defaultValue);
+				} else if (documentedState.stream().noneMatch(documentedOption -> supposedState.description.equals(documentedOption.description))) {
+					// description is outdated
+					problems.add("Documented description of " + supposedState.key + " in " + supposedState.containingClass +
+						" is outdated.");
+				} else {
+					// the docs for this option are up-to-date
+				}
 
 Review comment:
   I think we won't fail if we have a `DocumentedOption` which has no corresponding `ExistingOption` since we are only looking whether there is a `DocumentedOption` for every `ExistingOption`.

----------------------------------------------------------------
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:
users@infra.apache.org


With regards,
Apache Git Services