Re: mxid_age() and age(xid) appear undocumented

On Fri, Nov 17, 2023 at 01:39:46PM -0500, Bruce Momjian wrote:
> On Mon, Nov 13, 2023 at 05:32:24PM -0800, Andres Freund wrote:
> > Hi,
> >
> > On 2023-11-13 17:00:43 -0800, Peter Geoghegan wrote:
> > > On Mon, Nov 13, 2023 at 4:43 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> > > > I looked into this and all the 4-byte xid functions are marked as
> > > > deprecated for the 8-byte variants. I don't think documenting 4-byte
> > > > mxid_age() and age(xid) makes sense anymore, and I don't see their value
> > > > enough to create 8-byte versions, so I just added C comments that they
> > > > were undocumented, in the attached patch.
> > >
> > > I'm sympathetic to the goal of making 4 byte XIDs an on-disk
> > > implementation detail that is all but completely hidden from users.
> > > However, there are practical problems with taking that to its logical
> > > extreme. At least right now.
> > >
> > > These functions are in fact documented -- albeit only partially. There
> > > are references to both in "Routine Vacuuming". Moreover, those
> > > references are rather useful; they're the basis of many
> > > monitoring/alerting queries. If anything, I'd recommend adding more
> > > documentation for these two functions.
> >
> > +1
>
> Seems people still like these functions, so here is a patch to properly
> document them. :-)

Patch applied back to PG 16.

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.