Skip to content

Scan pgtypes sources for out-param Doxygen and step over preprocessor guards#75

Merged
estebanzimanyi merged 1 commit into
MobilityDB:masterfrom
estebanzimanyi:feat/scan-pgtypes-outparams
Jul 23, 2026
Merged

Scan pgtypes sources for out-param Doxygen and step over preprocessor guards#75
estebanzimanyi merged 1 commit into
MobilityDB:masterfrom
estebanzimanyi:feat/scan-pgtypes-outparams

Conversation

@estebanzimanyi

Copy link
Copy Markdown
Member

The vendored PostgreSQL base-type layer (json, date/interval, …) lives in the sibling pgtypes/ tree, outside meos/, and its base functions carry their @param[out] tags on the .c definitions there — for example json_array_elements in pgtypes/utils/jsonfuncs.c. Two things keep those out-params out of the catalog:

  • the out-param Doxygen scan in parser/outparam.py globs only meos/src + meos/include;
  • the function-definition regex does not step over the #if MEOS guard that separates a base function's doc block from its definition.

As a result shape.outParams is empty for the whole vendored-base surface, and every binding leaves those out-parameters as visible caller arguments instead of folding them.

This scans pgtypes/**/*.c alongside meos/, and skips a run of blank and preprocessor lines before the return-type line. The skip pattern is a line-based subset of doxygroup.py's _SKIP (which already scans pgtypes for @ingroup): the multi-line-comment alternative is deliberately omitted here because, combined with this module's whole-doc-block match, a DOTALL run inside the skip backtracks catastrophically — doxygroup can afford it because it runs a bounded two-step search.

Adds tests/test_outparam.py covering the plain meos/src case, the guarded pgtypes twin, the sibling-tree scan, and the non-const-pointer cross-check. Regenerating the catalog now marks e.g. json_array_elements → outParams: ['count']; the meos/src surface is unchanged (the skip matches zero lines when there is no guard).

… guards

The vendored PostgreSQL base-type layer (json, date/interval, …) lives in the
sibling pgtypes/ tree, outside meos/, and its base functions carry their
@param[out] tags on the .c definitions there — for example json_array_elements
in pgtypes/utils/jsonfuncs.c. Two things kept those out-params out of the
catalog: the out-param Doxygen scan globbed only meos/src + meos/include, and
the function-definition regex did not step over the #if MEOS guard that
separates a base function's doc block from its definition.

Scan pgtypes/**/*.c alongside meos/, and skip a run of blank and preprocessor
lines before the return-type line. The skip pattern is a line-based subset of
doxygroup.py's _SKIP: the multi-line-comment alternative is omitted here because,
combined with this module's whole-doc-block match, a DOTALL run inside the skip
would backtrack catastrophically (doxygroup runs a bounded two-step search).

Add tests/test_outparam.py covering the plain meos/src case, the guarded pgtypes
twin, the sibling-tree scan, and the non-const-pointer cross-check.
@estebanzimanyi
estebanzimanyi merged commit df7a138 into MobilityDB:master Jul 23, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant