Purushottam Sinha created FLINK-40256: -----------------------------------------
Summary: Docs: config options in sub-packages are silently missing
from the configuration reference
Key: FLINK-40256
URL: https://issues.apache.org/jira/browse/FLINK-40256
Project: Flink
Issue Type: Bug
Components: Documentation
Reporter: Purushottam Sinha
Problem
ConfigurationOptionLocator discovers ConfigOptions from a hard-coded list of
packages and does not recurse into sub-packages, so annotated options outside
that list never reach the generated configuration reference. All seven
state.backend.rocksdb.manual-compaction.* options — a feature shipped in Flink
1.20 — are undocumented as a result.
Evidence
-
flink-docs/src/main/java/org/apache/flink/docs/util/ConfigurationOptionLocator.java:171
uses Files.newDirectoryStream, which reads one directory only.
- RocksDBManualCompactionOptions sits in
org.apache.flink.state.rocksdb.sstmerge; the parent package is listed, the
sub-package is not. Every option carries
@Documentation.Section(EXPERT_ROCKSDB), yet
docs/layouts/shortcodes/generated/expert_rocksdb_section.html contains none of
them.
- ConfigOptionsDocsCompletenessITCase:291 builds its expectations from the
same locator, so it passes either way.
Proposed fix
- Add an OptionsClassLocation for org.apache.flink.state.rocksdb.sstmerge and
regenerate the config docs.
- Add @PublicEvolving to RocksDBManualCompactionOptions, required by
ConfigOptionsDocGenerator.verifyClassAnnotation.
- Add a test asserting every @Documentation.Section option lives in a
searched package.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
