Doc: update libpq's documentation for PQfn().

Mention specifically that you can't call aggregates, window functions,
or procedures this way (the inability to call SRFs was already
mentioned).

Also, the claim that PQfn doesn't support NULL arguments or results
has been a lie since we invented protocol 3.0.  Not sure why this
text was never updated for that, but do it now.

Discussion: https://postgr.es/m/2039442.1615317309@sss.pgh.pa.us

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 174a6b7f37bc41f052517fc50387aeb4519437ed..875950b83c0e2c0c97753a603025e2ce6066611e 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -5760,15 +5760,32 @@ typedef struct
 
   
    PQfn always returns a valid
-   PGresult pointer. The result status should be
+   PGresult pointer, with
+   status PGRES_COMMAND_OK for success
+   or PGRES_FATAL_ERROR if some problem was encountered.
+   The result status should be
    checked before the result is used.   The caller is responsible for
    freeing  the  PGresult  with
     when it is no longer needed.
   
 
   
-   Note that it is not possible to handle null arguments, null results,
-   nor set-valued results when using this interface.
+   To pass a NULL argument to the function, set
+   the len field of that parameter structure
+   to -1; the isint
+   and u fields are then irrelevant.
+  
+
+  
+   If the function returns NULL, *result_len is set
+   to -1, and *result_buf is not
+   modified.
+  
+
+  
+   Note that it is not possible to handle set-valued results when using
+   this interface.  Also, the function must be a plain function, not an
+   aggregate, window function, or procedure.