Carry Doxygen @param[out] through the catalog as shape.outParams#37
Merged
estebanzimanyi merged 1 commit intoJul 9, 2026
Merged
Conversation
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.
This was referenced Jul 9, 2026
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
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.
Extract the OUT direction of each parameter from the MEOS C Doxygen
@param[out]tag and expose it asshape.outParams— the sibling ofshape.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 hardcodedresult/size_outparameter-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 aconstpointer, or whose name is absent from the signature (the header declaressizewhile the.cdoc sayssize_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.outParamsand reports 40 discrepancies for cleanup at the MEOS source.parser/outparam.pymirrorsparser/nullable.py;run.pyruns the pass right aftermerge_nullableand prints the count + the discrepancy list. The field is additive — no existing consumer changes.