Follow-ups surfaced while wiring the docs-repo manifest consumer (cipherstash/docs#46) against the manifest from #369. None are blocking — the affected functions are present and correctly classified — but the extracted return types, brief text, and operator entries have rough edges worth cleaning up in the Doxygen→Markdown/JSON pipeline (tasks/docs/generate/xml-to-markdown.py).
1. RETURNS SETOF <type> captures only SETOF
process_function reads the return type with re.search(r'RETURNS\s+([^\s]+)', argsstring), which grabs the first whitespace-delimited token. For set-returning functions that token is the SETOF keyword, not the type:
jsonb_path_query -> returns.type = "SETOF" (should be "SETOF public.jsonb_entry" or "public.jsonb_entry")
Fix: skip an optional leading SETOF, e.g. RETURNS\s+(?:SETOF\s+)?(\S+) (and decide whether to keep SETOF in the surfaced type).
2. Inline @param/type refs dropped from brief/description text
Doxygen turns an inline reference in prose into a <ref> child, and the extractor drops the ref's text, leaving a gap:
brief: "Query encrypted JSONB for sv elements matching ." (the `selector` ref vanished)
extract_description / extract_para_text should include <ref> text (and its tail) when flattening <para>.
3. Operators reach the manifest as pseudo-functions
Doxygen's operator-name remapping emits -> and a bare > (empty args) as function entries. They render poorly and are redundant with the domain matrix's operator column. The docs-repo generator currently filters non-identifier names as a workaround (cipherstash/docs#46); ideally the pipeline wouldn't surface them (or would model operators as a distinct kind).
Context
Root-cause pipeline fixes (body/comment stripping, schema-based private detection, version) landed in #369, which took the manifest from 984 → 1680 functions with a correct public/internal split. These three are the residual polish items.
Follow-ups surfaced while wiring the docs-repo manifest consumer (cipherstash/docs#46) against the manifest from #369. None are blocking — the affected functions are present and correctly classified — but the extracted return types, brief text, and operator entries have rough edges worth cleaning up in the Doxygen→Markdown/JSON pipeline (
tasks/docs/generate/xml-to-markdown.py).1.
RETURNS SETOF <type>captures onlySETOFprocess_functionreads the return type withre.search(r'RETURNS\s+([^\s]+)', argsstring), which grabs the first whitespace-delimited token. For set-returning functions that token is theSETOFkeyword, not the type:Fix: skip an optional leading
SETOF, e.g.RETURNS\s+(?:SETOF\s+)?(\S+)(and decide whether to keepSETOFin the surfaced type).2. Inline
@param/type refs dropped from brief/description textDoxygen turns an inline reference in prose into a
<ref>child, and the extractor drops the ref's text, leaving a gap:extract_description/extract_para_textshould include<ref>text (and its tail) when flattening<para>.3. Operators reach the manifest as pseudo-functions
Doxygen's operator-name remapping emits
->and a bare>(empty args) asfunctionentries. They render poorly and are redundant with the domain matrix's operator column. The docs-repo generator currently filters non-identifier names as a workaround (cipherstash/docs#46); ideally the pipeline wouldn't surface them (or would model operators as a distinct kind).Context
Root-cause pipeline fixes (body/comment stripping, schema-based private detection,
version) landed in #369, which took the manifest from 984 → 1680 functions with a correct public/internal split. These three are the residual polish items.