Re: Corrected documentation of data type for the logical replication message formats. - Mailing list pgsql-hackers

vignesh C <vignesh21@gmail.com> writes:
[ v6-0001-Included-the-actual-datatype-used-in-logical-repl.patch ]

I see what you want to do here, but the way you did it seems quite
detrimental to the readability of the field descriptions.
Parenthesized interjections should be used sparingly.

I'm inclined to think that the equivalent data type is part of the
field data type specification, and thus that we ought to put it in
the data type part of each entry.  So we'd have something like

<varlistentry>
<term>
        Int64 (XLogRecPtr)
</term>
<listitem>
<para>
                The final LSN of the transaction.
</para>
</listitem>
</varlistentry>

instead of what you did here.  Parentheses might not be the best
punctuation to use, given the existing convention about parenthesized
specific values, but we could probably settle on some other markup.
Or just ignore the ambiguity.

Another idea is to add the data type info at the ends of items
instead of cramming it into the sentences, thus:

                The final LSN of the transaction.  (XLogRecPtr)

I don't find that better personally, but maybe others will
think differently.

            regards, tom lane