On Tue, Mar 9, 2021 at 3:21 PM Tom Lane <tgl@xxxxxxxxxxxxx> wrote:
"David G. Johnston" <david.g.johnston@xxxxxxxxx> writes:
> The omission of the "OUT" parameter mode seems intentional since at present
> our procedures do not support OUT mode parameters.
Um, I just created one. I think this *used* to be true, and this bit of
the docs didn't get fixed. If I back-patch this, I'll have to research
when it changed.
Five months ago it seems.
The patch and email thread for that commit make me pause, though I cannot put into words why.
> Instead of "The difference" or "One difference" I would suggest: "However,
> a procedure does not return a value, so there is no return type
> declaration; though a procedure can declare INOUT (but not plain OUT)
> parameters."
Not sure if that's an improvement.
The "however" part is probably a wash; I just dislike seeing a count started and not having an ending and thus being left in a state of "what didn't they include that's important".
The part about commenting about OUT/INOUT parameters still working even though there is no return provide complete coverage of the differences/similarities between functions and procedures with respect to passing back data to the caller.
> Relocating the links to the description instead of usage is good. The
> additional procedure link after the examples seems redundant, particularly
> as the linked to location doesn't actually have more examples.
I was modeling that on the existing pattern in create_function.sgml,
which has similar verbiage in the EXAMPLES section. But I suppose
we could drop that if we have a link in the description section.
Yeah, it was an existing deficiency, but being a bit more invasive seems warranted, and as you say it is be located partly because it is much higher level content being pointed to (hence description, not usage/examples).
David J.
