Horton

Re: Fix wrong reference in pg_overexplain's doc

Chao Li <li.evan.chao@gmail.com>

View thread
From: Chao Li <li.evan.chao@gmail.com>
To: Fujii Masao <masao.fujii@gmail.com>
Cc: Shixin Wang <wang-shi-xin@outlook.com>, Julien Tachoires <julien@tachoires.me>, "pgsql-hackers@lists.postgresql.org" <pgsql-hackers@lists.postgresql.org>
Date: 2025-12-23T23:53:26Z
Lists: pgsql-hackers

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. doc: Use proper tags in pg_overexplain documentation.

  2. doc: Fix incorrect reference in pg_overexplain documentation.


> On Dec 23, 2025, at 16:41, Fujii Masao <masao.fujii@gmail.com> wrote:
> 
> On Tue, Dec 23, 2025 at 10:25 AM Shixin Wang <wang-shi-xin@outlook.com> wrote:
>> 
>> Hi  Fujii-san
>> 
>>> It would be more appropriate to use
>>> <filename>, <structname>, and <command> instead.
>> 
>> ```
>> -   following fields. See <literal>PlannedStmt</literal> in
>> -   <literal>nodes/plannodes.h</literal> for additional detail.
>> +   following fields. See <structname>PlannedStmt</structname> in
>> +   <filename>nodes/plannodes.h</filename> for additional detail.
>> ```
>> 
>> Switching to <filename> here makes sense. While looking through the SGML files,
> 
> Thanks for the review!
> 
> 
>> I noticed that the way header file paths are written is a bit inconsistent across the documentation.
>> 
>> In many places we use full paths including src/include, for example in fdw_handler.sgml and create_type.sgml:
>> 
>> ```
>>     in <filename>src/include/nodes/plannodes.h</filename>, and the comments for
>>     <type>ExecRowMark</type> in <filename>src/include/nodes/execnodes.h</filename> for
>> ```
>> 
>> But in a few files, such as pgoverexplain.sgml (this patch), spi.sgml,
>> and xfunc.sgml, the paths are written without the src/include/ prefix.
> 
> Yes, and you can see similar inconsistencies elsewhere as well. For example,
> paths to C source files are written inconsistently: they usually start with
> src/backend or contrib, but some entries don't follow that convention.
> 
> 
>> I’m fine with the change as-is; just wanted to ask whether you’d like to use
>> this patch to address that inconsistency, or keep the existing style in this file.
> 
> At the moment, I don't plan to update the patch to address those
> inconsistencies...
> 

The patch itself looks good to me. Following Shixin’s comment, I do see the inconsistencies of full path and relative path of .h files are referenced, if you don’t plan to address the inconvenience,  I may file a patch for that.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/