Date: Fri, 28 Feb 2025 14:42:11 -0600
From: Nathan Bossart <nathandbossart@gmail.com>
To: John Naylor <johncnaylorls@gmail.com>
Cc: Masahiko Sawada <sawada.mshk@gmail.com>,
	Bruce Momjian <bruce@momjian.us>, Jeff Davis <pgsql@j-davis.com>,
	Corey Huinker <corey.huinker@gmail.com>,
	jian he <jian.universality@gmail.com>,
	Matthias van de Meent <boekewurm+postgres@gmail.com>,
	Tom Lane <tgl@sss.pgh.pa.us>, Magnus Hagander <magnus@hagander.net>,
	Stephen Frost <sfrost@snowman.net>,
	Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>,
	Peter Smith <smithpb2250@gmail.com>,
	PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>,
	alvherre@alvh.no-ip.org
Subject: Re: vacuumdb changes for stats import/export
Message-ID: <Z8Ifozh3FkvfBIzU@nathan>
References: <Z5O1bpcwDrMgyrYy@nathan>
 <CAD21AoCqsXK5B2Z9szw6H4ZFPTrs0zJWp_Ga0HeHF-137VC3ig@mail.gmail.com>
 <Z6KKHX9PZkB19lAK@nathan>
 <CANWCAZZf_jNn2i+6-JfQt_j909DBk-U6Dg0M7iArZPLgdXCAmw@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CANWCAZZf_jNn2i+6-JfQt_j909DBk-U6Dg0M7iArZPLgdXCAmw@mail.gmail.com>
Archived-At: <https://www.postgresql.org/message-id/Z8Ifozh3FkvfBIzU%40nathan>
Precedence: bulk

On Thu, Feb 27, 2025 at 04:36:04PM +0700, John Naylor wrote:
> On Wed, Feb 5, 2025 at 4:44 AM Nathan Bossart <nathandbossart@gmail.com> wrote:
>> [v2]
> 
> I started looking just at 0001, and it seems like a fairly
> straightforward rearrangement.

Thanks for taking a look.

> I found this comment quite hard to read:
> 
> + * 'found_objs' should be a fully qualified list of objects to process, as
> + * returned by a previous call to vacuum_one_database().  If *found_objs is
> + * NULL, it is set to the results of the catalog query discussed below.  If
> + * found_objs is NULL, the results of the catalog query are not returned.
> + *
> + * If *found_objs is NULL, this function performs a catalog query to retrieve
> + * the list of tables to process.  When 'objects' is NULL, all tables in the
> 
> I had to read it several times before I noticed the difference between
> "* found_objs" and "*found_objs". Maybe some extra spacing and breaks
> would help, or other reorganization.

Yeah, it's pretty atrocious.  I think the main problem is that the
interface is just too complicated, so I'll take a step back and see if I
can make it more understandable to humans.  In the meantime, here's an
attempt at adjusting the comment:

 * found_objs is a double pointer to a fully qualified list of objects to
 * process, as returned by a previous call to vacuum_one_database().  If
 * *found_objs (the once-dereferenced double pointer) is NULL, it is set to the
 * results of the catalog query discussed below.  If found_objs (the double
 * pointer) is NULL, the results of the catalog query are not returned.
 *
 * If *found_objs (the once-dereferenced double pointer) is NULL, this function
 * performs a catalog query to retrieve the list of tables to process.  When
 * "objects" is NULL, all tables in the database are processed.  Otherwise, the
 * catalog query performs a lookup for the objects listed in "objects".

-- 
nathan