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_r368000092
##########
File path:
flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocsCompletenessITCase.java
##########
@@ -139,22 +139,42 @@ private static void
compareDocumentedAndExistingOptions(Map<String, List<Documen
// first check that all existing options are properly documented
existingOptions.forEach((key, supposedStates) -> {
- List<DocumentedOption> documentedState =
documentedOptions.remove(key);
+ List<DocumentedOption> documentedState =
documentedOptions.get(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
+ final Iterator<DocumentedOption>
candidates = documentedState.iterator();
+
+ boolean matchingDefaultFound = false;
+ boolean matchingDescriptionFound =
false;
+ while (candidates.hasNext()) {
+ DocumentedOption candidate =
candidates.next();
+ if
(supposedState.defaultValue.equals(candidate.defaultValue)) {
+ matchingDefaultFound =
true;
+ }
+ if
(supposedState.description.equals(candidate.description)) {
+
matchingDescriptionFound = true;
+ }
+ if (matchingDefaultFound &&
matchingDescriptionFound) {
+ // option is properly
documented
+ candidates.remove();
+ break;
+ }
+ }
Review comment:
I'm not sure whether I completely understand this logic here. Can't it
happen that we have two options where one fulfills the default value and the
other fulfills the description? In this case we would remove the second option
and not report any problems even though both of them should cause a problem.
----------------------------------------------------------------
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
