[FLINK-40256][docs] Include sub-package config options in the configuration reference - #28842
Open
spuru9 wants to merge 1 commit into
Open
[FLINK-40256][docs] Include sub-package config options in the configuration reference#28842spuru9 wants to merge 1 commit into
spuru9 wants to merge 1 commit into
Conversation
…ration reference ConfigurationOptionLocator discovers ConfigOptions from a hard-coded list of packages and reads each with Files.newDirectoryStream, which does not recurse into sub-packages. Options outside that list are dropped from the generated configuration reference without any error, and ConfigOptionsDocsCompletenessITCase cannot detect it because it derives its expectations from the same list. All seven state.backend.rocksdb.manual-compaction.* options were affected: they carry @Documentation.Section(EXPERT_ROCKSDB) but live in org.apache.flink.state.rocksdb.sstmerge, a sub-package of a searched package, so the feature shipped in 1.20 had no documented configuration. Add a location for the sub-package and regenerate the affected tables. RocksDBManualCompactionOptions needs a stability annotation because becoming discoverable also subjects it to ConfigOptionsDocGenerator#verifyClassAnnotation; @PublicEvolving matches RocksDBOptions and RocksDBConfigurableOptions in the same module. Two option descriptions were missing a space between concatenated sentences, which is now user-visible, so fix those too. Add ConfigurationOptionLocatorTest to prevent recurrence: it scans the source tree and fails when a @Documentation.Section option sits in a package the locator does not search. Repo-wide it needs no exclusions. Generated-by: Claude Code (claude-opus-5)
Collaborator
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is the purpose of the change
ConfigurationOptionLocatorreads each package in its hard-codedLOCATIONSlist withFiles.newDirectoryStream, which does not recurse. Option classes in a sub-package are silently dropped from the configuration reference, andConfigOptionsDocsCompletenessITCasecannot catch this because it derives its expectations from the same list.All seven
state.backend.rocksdb.manual-compaction.*options are affected: they carry@Documentation.Section(EXPERT_ROCKSDB)but live inorg.apache.flink.state.rocksdb.sstmerge, so the manual compaction feature shipped in 1.20 has no documented configuration.Brief change log
OptionsClassLocationfororg.apache.flink.state.rocksdb.sstmergeand regenerate:expert_rocksdb_section.html(4 → 11 rows) plus the newrocksdb_manual_compaction_configuration.html. No other table changes.RocksDBManualCompactionOptionswith@PublicEvolving. Becoming discoverable also subjects it toConfigOptionsDocGenerator#verifyClassAnnotation, which fails the docs build without a stability level. MatchesRocksDBOptionsin the same module.ConfigurationOptionLocatorTest, which fails when a@Documentation.Sectionoption sits in an unsearched package.The scan stays non-recursive: around 30 connector and format option classes sit outside
LOCATIONSon purpose, documented by hand on their own pages.Verifying this change
ConfigurationOptionLocatorTestreports exactly one violation before the fix and none after, so it needs no exclusion list.ConfigOptionsDocsCompletenessITCaseis green either way, which is why the gap went unnoticed.mvn -pl flink-docs verifypasses: 21 unit tests, 3 ITCases.Does this pull request potentially affect one of the following parts:
@Public(Evolving): yes,RocksDBManualCompactionOptionsgains@PublicEvolvingas required by the docs generator. No option key, default value or type changes.Documentation
Was generative AI tooling used to co-author this PR?
Generated-by: Claude Code (claude-opus-5)