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

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. :-)

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

Only you can decide what is important to you.