And it's very inconsistent. For example, some functions use <optional> tags for optional parameters, others use square brackets, and some use <literal>VARIADIC</literal> to indicate variadic parameters, others use ellipses (sometimes in <optional> tags or brackets).
Having just written a couple of those functions, I wasn't able to find any guidance on how to document them with regards to <optional> vs [], etc. Having such a thing would be helpful.
While we're throwing out ideas, does it make sense to have function parameters and return values be things that can accept COMMENTs? Like so:
COMMENT ON FUNCTION function_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] ARGUMENT argname IS '....'; COMMENT ON FUNCTION function_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] RETURN VALUE IS '....';
I don't think this is a great idea, but if we're going to auto-generate documentation then we've got to store the metadata somewhere, and pg_proc.dat is already lacking relevant details.