Horton

Thread

Commits

  1. doc: Add missing index entries and fix title formatting in pg_buffercache docs.

  2. doc: pg_buffercache documentation wordsmithing

  1. Minor Improvements to pg_buffercache documentation

    Fujii Masao <masao.fujii@oss.nttdata.com> — 2025-07-02T16:30:13Z

    Hi,

While reading commit 8eede2c7200 and the pg_buffercache docs,
I noticed a few minor issues:

- There are missing index entries for pg_buffercache_numa() and
   pg_buffercache_usage_counts(), even though other functions have them.
- The section titles for pg_buffercache_evict_relation and
   pg_buffercache_evict_all are missing parentheses, unlike the others.

The attached patch addresses these points by:

- Adding index entries for pg_buffercache_numa() and
   pg_buffercache_usage_counts().
- Making the function section titles consistent by including parentheses
   where they were missing.

Also, a quick note on pg_buffercache_numa_pages(): although there's
an index entry for pg_buffercache_pages(), I didn't add one for
pg_buffercache_numa_pages() because both functions are typically accessed
via views, not directly. Regarding those functions, it seems enough to
have index entries for the views. So, it might make more sense to remove
the existing index entry for pg_buffercache_pages() for consistency.

BTW, all current index entries point to the top of the pg_buffercache
docs. Would it be better if each entry pointed directly to its relevant
section using a zone attribute like this?

- <indexterm>
+ <indexterm zone="pgbuffercache-summary">
    <primary>pg_buffercache_summary</primary>
   </indexterm>

Thought?

Regards,

-- 
Fujii Masao
NTT DATA Japan Corporation

  2. Re: Minor Improvements to pg_buffercache documentation

    Michael Paquier <michael@paquier.xyz> — 2025-07-22T05:10:32Z

    On Thu, Jul 03, 2025 at 01:30:13AM +0900, Fujii Masao wrote:
> BTW, all current index entries point to the top of the pg_buffercache
> docs. Would it be better if each entry pointed directly to its relevant
> section using a zone attribute like this?
> 
> - <indexterm>
> + <indexterm zone="pgbuffercache-summary">
>    <primary>pg_buffercache_summary</primary>
>   </indexterm>

That would be smarter than the current statu-quo of the page,
especially if this page grows more in size in the future.

The other inconsistencies are good catches, by the way!
--
Michael

  3. Re: Minor Improvements to pg_buffercache documentation

    Fujii Masao <masao.fujii@gmail.com> — 2025-07-24T02:56:36Z

    On Tue, Jul 22, 2025 at 2:10 PM Michael Paquier <michael@paquier.xyz> wrote:
>
> On Thu, Jul 03, 2025 at 01:30:13AM +0900, Fujii Masao wrote:
> > BTW, all current index entries point to the top of the pg_buffercache
> > docs. Would it be better if each entry pointed directly to its relevant
> > section using a zone attribute like this?
> >
> > - <indexterm>
> > + <indexterm zone="pgbuffercache-summary">
> >    <primary>pg_buffercache_summary</primary>
> >   </indexterm>
>
> That would be smarter than the current statu-quo of the page,
> especially if this page grows more in size in the future.

The summary descriptions for each function and view are currently
at the top of the docs. If we update the index entries to point directly
to the relevant sections instead of the top, it might also make sense
to move those summaries into their respective sections.
I’ll consider this later.


> The other inconsistencies are good catches, by the way!

Thanks for the review! I've pushed the patch.

Regards,

-- 
Fujii Masao