You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by "Roman Khachatryan (Jira)" <ji...@apache.org> on 2026/08/03 08:34:00 UTC

[jira] [Assigned] (FLINK-40256) Docs: config options in sub-packages are silently missing from the configuration reference

     [ https://issues.apache.org/jira/browse/FLINK-40256?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Roman Khachatryan reassigned FLINK-40256:
-----------------------------------------

    Assignee: Purushottam Sinha

> 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
>            Assignee: Purushottam Sinha
>            Priority: Minor
>              Labels: pull-request-available
>
> 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)