Skip to content

Carry Doxygen @param[out] through the catalog as shape.outParams#37

Merged
estebanzimanyi merged 1 commit into
MobilityDB:masterfrom
estebanzimanyi:feat/outparam-doxygen-flag
Jul 9, 2026
Merged

Carry Doxygen @param[out] through the catalog as shape.outParams#37
estebanzimanyi merged 1 commit into
MobilityDB:masterfrom
estebanzimanyi:feat/outparam-doxygen-flag

Conversation

@estebanzimanyi

Copy link
Copy Markdown
Member

Extract the OUT direction of each parameter from the MEOS C Doxygen @param[out] tag and expose it as shape.outParams — the sibling of shape.nullable. This is the single, explicit source-of-truth for which arguments a function writes to, so every binding can fold an out-param (allocate the buffer, pass it, read the value back) from one catalog signal instead of a per-binding guess: JMEOS's hardcoded result/size_out parameter-name whitelist, or a type/position heuristic that misfires on in-place mutators (meos_array_destroy, skiplist_free, *_compute_bbox).

The Doxygen tags are manually maintained, so the flag is emitted only when the tag agrees with the C signature — the parameter must be a non-const pointer. A tag on a by-value parameter (@param[out] count int), on a const pointer, or whose name is absent from the signature (the header declares size while the .c doc says size_out) is a documentation discrepancy: it is dropped and reported, never trusted. That cross-check is what keeps a stray annotation from corrupting a binding signature.

On the current sources this validates 438 out-params into shape.outParams and reports 40 discrepancies for cleanup at the MEOS source.

parser/outparam.py mirrors parser/nullable.py; run.py runs the pass right after merge_nullable and prints the count + the discrepancy list. The field is additive — no existing consumer changes.

Extract the OUT direction of each parameter from the MEOS C Doxygen `@param[out]`
tag — the source-of-truth for which arguments a function writes to rather than
reads. It feeds `shape.outParams`, the sibling of `shape.nullable`, so every
binding folds an out-param (allocate the buffer, pass it, read the value back)
from one explicit signal instead of a per-binding guess (a hardcoded parameter
name whitelist, or a type/position heuristic that misfires on in-place mutators).

The tags are manually maintained, so the flag is emitted only when the tag AGREES
with the C signature — the parameter must be a non-const pointer. A tag on a
by-value or const parameter, or one whose name is absent from the signature, is a
documentation discrepancy: it is dropped and reported, never trusted. On the
current sources this validates 438 out-params and reports 40 discrepancies to
clean at the source.
@estebanzimanyi estebanzimanyi merged commit 4fdeca3 into MobilityDB:master Jul 9, 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