From bab878dc10dedc4e3bc1e4dbbcd000b6c5c7516b Mon Sep 17 00:00:00 2001
From: Esteban Zimanyi <estebanzimanyi@gmail.com>
Date: Wed, 15 Jul 2026 07:55:36 +0200
Subject: [PATCH] Scan @param[out] / may-be-NULL Doxygen from the source, not
 the headers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `may be NULL` and `@param[out]` Doxygen tags are a property of the
MEOS C source (meos/src/**/*.c), but merge_nullable / merge_outparams
scanned HEADERS_DIR.parent. On the provision-meos build-libmeos path
HEADERS_DIR is the INSTALLED headers (the generated meos_export.h, with
no sibling src/), so the scan finds 0 out-params — the codegens then
cannot fold single out-param wrappers (ttext_value_at_timestamptz,
textset_value_n, set_as_hexwkb, ...), and every binding whose
hand-written surface calls the folded form fails to compile.

Scan the tags from the source checkout (MDB_SRC_ROOT/meos), the same
root the @sqlfn / @ingroup maps already use, falling back to the header
tree's parent when the headers are themselves a source checkout.
---
 run.py | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/run.py b/run.py
index 43d711c..3779eee 100644
--- a/run.py
+++ b/run.py
@@ -85,10 +85,19 @@ def main():
     idl, sh = infer_shapes(idl)
     print(f"      inferred shape: {sh['arrayReturn']} array returns, "
           f"{sh['outputArrays']} output arrays", file=sys.stderr)
-    idl, nn = merge_nullable(idl, HEADERS_DIR.parent)
+    # The `may be NULL` / `@param[out]` Doxygen tags live in the MEOS C *source*
+    # (meos/src/**/*.c), not the parsed header tree. On the build-libmeos path
+    # HEADERS_DIR is the INSTALLED headers (generated meos_export.h, no src/), so
+    # scan from the source checkout (MDB_SRC_ROOT/meos) — the same root the
+    # @sqlfn/@ingroup maps use — and fall back to the header tree's parent when
+    # the headers are themselves a source checkout (no MDB_SRC_ROOT).
+    _src_root = (Path(os.environ["MDB_SRC_ROOT"]) / "meos"
+                 if os.environ.get("MDB_SRC_ROOT") else HEADERS_DIR.parent)
+    _doxy_root = _src_root if (_src_root / "src").is_dir() else HEADERS_DIR.parent
+    idl, nn = merge_nullable(idl, _doxy_root)
     print(f"      nullable params from Doxygen `may be NULL`: {nn}",
           file=sys.stderr)
-    idl, no, out_drift = merge_outparams(idl, HEADERS_DIR.parent)
+    idl, no, out_drift = merge_outparams(idl, _doxy_root)
     print(f"      out params from Doxygen `@param[out]`: {no}", file=sys.stderr)
     if out_drift:
         print(f"      ⚠ {len(out_drift)} @param[out] tag(s) disagree with the C signature "