pgsql: Doc: add comments about PreventInTransactionBlock/IsInTransactio

Doc: add comments about PreventInTransactionBlock/IsInTransactionBlock.

Add a little to the header comments for these functions to make it
clearer what guarantees about commit behavior are provided to callers.
(See commit f92944137 for context.)

Although this is only a comment change, it's really documentation
aimed at authors of extensions, so it seems appropriate to back-patch.

Yugo Nagata and Tom Lane, per further discussion of bug #17434.

Discussion: https://postgr.es/m/17434-d9f7a064ce2a88a3@postgresql.org

Branch
------
REL_11_STABLE

Details
-------
https://git.postgresql.org/pg/commitdiff/fec80da849f3374c2931cc3bf593edca15041ece

Modified Files
--------------
src/backend/access/transam/xact.c | 8 ++++++++
1 file changed, 8 insertions(+)