WIP docs patch about composite-type behavior

Started by Tom Laneover 9 years ago1 messagesdocs
Jump to latest
#1Tom Lane
tgl@sss.pgh.pa.us

There have been a couple of recent threads bemoaning our lack of clarity
about how references to composite values work, eg
/messages/by-id/20161029121906.15993.79158@wrigleys.postgresql.org
/messages/by-id/CAGwx4BnDQZyJJpzom-UU15wh7s3DQE=ChEdEDQ2+rd5S7S2UNA@mail.gmail.com
(same instigator but distinct threads)

I suggested that we ought to try to consolidate information about this
in one place, and attached is a WIP patch to that end. Some notes:

* I'm not completely sold on either the new section's title or its
location; but I cannot find a better location.

* Some of the text is borrowed from section 36.4.3 "SQL Functions on
Composite Types", which should probably now be shortened in favor of
linking to this section, but I didn't do that yet. There may be more
places that should get merged in.

* I noticed that there is noplace in Part II that describes RETURNING
clauses as such; there's some material in 7.8.2 "Data-Modifying Statements
in WITH", but that really is assuming that you know what RETURNING does
already, and in any case it fails to explain the clause's use in
standalone statements. This seems like an, um, oversight.

Comments, objections, better ideas? Should this get back-patched?

regards, tom lane

Attachments:

better-composite-types-docs.patchtext/x-diff; charset=us-ascii; name=better-composite-types-docs.patchDownload+230-31