lucasfang opened a new issue, #466: URL: https://github.com/apache/paimon-cpp/issues/466
## Search before asking - [x] I searched in the [issues](https://github.com/apache/paimon-cpp/issues) and found nothing similar. ## Paimon-cpp version master at a397d344c554a8f5fb588189189e47acef47e0f0 ## Minimal reproduce step Three groups of drift, each verifiable with the command shown. **Statements the code contradicts.** `grep -rn '"compaction.file-size"' src/ include/` prints nothing, yet `docs/source/user_guide/compaction.rst` documents `compaction.file-size` twice as a configurable option; the threshold is derived, not configurable, as `CoreOptions::GetCompactionFileSize()` returns `GetTargetFileSize() / 10 * 7`. `grep -n PARQUET_ENABLE_DICTIONARY src/paimon/format/parquet/parquet_format_defs.h` prints `parquet.enable.dictionary`, but the same page writes `parquet.enable-dictionary`; #257 wrote the doc and #263 renamed the option without updating it. `grep -n CURRENT_VERSION src/paimon/core/table/sink/commit_message_serializer.cpp` prints 13, but `primary_key_global_index.rst` says commit message v12; #247 raised the version without updating the doc. `write.rst` says object-store paths require REST catalog commit mode, but `src/paimon/core/table/table.cpp` also accepts `CommitContextBuilder::WithCatalog()`, and the two modes are documented as mutually exclus ive in `include/paimon/commit_context.h`. **Lists that lag the code.** `grep -n "^option(PAIMON_ENABLE" CMakeLists.txt` lists 13 switches while the Optional Components list in `building.rst` names 10, omitting `PAIMON_ENABLE_MOSAIC`, `PAIMON_ENABLE_VORTEX` and `PAIMON_ENABLE_NETWORK_TESTS` even though `format_table.rst` already refers to the first two. `grep -rhoE "add_paimon_lib\(paimon_[a-z0-9_]+" --include=CMakeLists.txt src/paimon/ | sort -u` lists 17 targets while `build_system.rst` names 12, omitting `paimon_vortex_file_format_shared`, `paimon_mosaic_file_format_shared`, `paimon_full_text_index_shared` and `paimon_global_index_shared`. `grep -rn "IDENTIFIER\[\]" src/paimon/format/` registers 7 file formats while README says "built-in ORC, Parquet, and Avro" and `basic_concepts.rst` says "optional Lance and Mosaic", omitting Vortex added in #376 and contradicting `data_types.rst`, which already documents it. README also says "Commit: append table commit support for simple append-only tables", but `write.rst` states b oth table types are supported and ten primary-key integration tests, `test/inte/pk_compaction_inte_test.cpp` among them, commit through `FileStoreCommit`. **Coverage gaps.** `grep -rn "NewScan\|NewRead\|NewWrite\|NewCommit" docs/source/ README.md` prints nothing, although #434 added those four `Table` entry points and `examples/read_write_demo.cpp` already calls them; `paimon::Table` is also absent from `api/catalog.rst`, which documents only `Catalog` and `Identifier` out of the four exported classes in `include/paimon/catalog/`. `system_tables.rst` mentions 4 suffixes while the registry in `src/paimon/core/table/system/system_table.cpp` holds 11 table-level ones and `global_system_tables.h` adds 4 under `sys`. `docs/code-style.md` omits the `check-yaml` and `sphinx-lint` hooks that `.pre-commit-config.yaml` defines, omits the `misc-*` and `clang-diagnostic-*` groups that `.clang-tidy` enables, and presents `bugprone-*` as a wildcard although it is enumerated one check at a time. ## What doesn't meet your expectations? A reader following the docs configures options that do not exist and gets no effect: setting `compaction.file-size` is silently ignored because the real knob is `target-file-size`, and `parquet.enable-dictionary` never matches the `parquet.enable.dictionary` the writer reads. A reader planning an upgrade trusts the stated commit message v12 and misjudges wire compatibility with a writer that emits v13. A reader assessing capability underestimates the library, concluding that primary-key tables cannot be committed and that Vortex and Mosaic do not exist, and cannot find the build switches or plugin targets for the components that are there. A reader looking for the table-first operator entry points added in #434 finds nothing and keeps using the context-first calls, and a reader wanting the full system-table surface has to read the registry in the source. ## Anything else? The drift is detectable mechanically, which is how these were found: diff each commit's `--stat` for source changes without a matching `docs/` change, then compare the option-like literals in `docs/source/` against the string literals in `src/` and `include/`, enumerate `PAIMON_EXPORT` classes against the doxygen targets in `api/*.rst`, enumerate `add_paimon_lib` targets against `build_system.rst`, and resolve every `:ref:` and `:doc:`. That last check passes today, and all 89 doxygen targets resolve, so nothing in the docs is currently broken at build time; the drift is in the content. Two gaps are left out of the fix because they need new prose rather than corrections, and are better tracked separately: the realtime module has 16 exported types across `include/paimon/realtime/` with no user guide page and no API page, and roughly thirty further exported classes, among them `CredentialProvider`, `FullTextSearch`, `VectorSearch`, `ScoredGlobalIndexResult` and `PrefetchMetrics`, are explained at length in the user guide but have no API reference page. ## Are you willing to submit a PR? - [x] I'm willing to submit a PR! -- 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. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
