Derive the catalog api field from the doxygen @ingroup group#65
Merged
estebanzimanyi merged 1 commit intoJul 17, 2026
Merged
Conversation
The public/internal split of the catalog `api` field keys on the header a function is declared in (`_INTERNAL_FILES`), which over-includes: any function in a public header counts as public even with no documentation. Derive `api` from the doxygen `@ingroup` group instead: a function is public iff it carries a group that is not `meos_internal_*`; a function with no group, or a `meos_internal_*` group, is internal. The binding and network surface and the reference manual then derive from one human-authored signal and cannot drift. Because api now depends on the group, attach the `@ingroup` groups before the enrichment pass rather than after it (the file-based rule did not need the group, so it ran later). Update the enrich fixtures to carry a group, and add a test that a function with no group is internal.
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
1 participant
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.
The catalog
apifield splits public from internal by the header a function isdeclared in (
_INTERNAL_FILES = {meos_internal.h, meos_internal_geo.h}). Thatover-includes: any function in a public header counts as public even when it is
undocumented internal plumbing, which puts the public set near 4000.
This derives
apifrom the doxygen@ingroupgroup — the single human-authoredsignal that also drives the reference manual. A function is public iff it carries
a group that is not
meos_internal_*; a function with no group, or ameos_internal_*group, is internal. The binding and network surface and themanual then come from one tag and cannot drift.
Since
apinow depends on the group,run.pyattaches the@ingroupgroupsbefore the enrichment pass rather than after it (the file-based rule does not
read the group). The enrich fixtures carry a group, and a new test asserts that a
function with no group is internal.
On a catalog regenerated from current master the public set is 2842 (from ~4020),
with the documented functions public and the undocumented internal plumbing
internal; actionable coverage rises rather than regresses. The full test suite
passes (the
test_struct_layoutcases need libclang-resolved struct offsets andpass on the CI build).