Chapter "8.8 Geometric Types" of documentation could contain more details

Started by PG Bug reporting formalmost 2 years ago4 messagesdocs
Jump to latest
#1PG Bug reporting form
noreply@postgresql.org

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/datatype-geometric.html
Description:

Hi, I am writing to suggest a couple of clarifications to "8.8. Geometric
Types" documentation chapter.

1. Documentation does not specify what precision is used when persisting
point coordinates. There are hints that it's 8 bytes per coordinate, but
neither can be taken for sure. Table "8.20. Geometric Types" says that a
point takes 16 bytes, which strongly suggests it's 8 bytes per coordinate,
but on the other hand, it could be less if a point definition also includes
some unspecified metadata. Section "8.8.1. Points" says "Values of type
point are specified […] where x and y are the respective coordinates, as
floating-point numbers.", however it is unclear what exact type of
floating-point numbers is meant.

My suggestion is to clearly describe which floating-point datatype is used
for point coordinates.

2. Documentation only partly clarifies what are the benefits of using
polygon datatype instead of path datatype. Section "8.8.6. Polygons" says
that "the essential difference is that a polygon is considered to include
the area within it, while a path is not", which clarifies that they are
meant to serve different purposes, but nothing more. Table "8.20. Geometric
Types" says that a polygon with n vertices takes 24 bytes more than a path
with n vertices, but that's all. Only chapter "9.11. Geometric Functions and
Operators" really helps in understanding that some functions and operators
are available to polygons but not to paths.

My suggestion is to:
a) point out that different operations can be performed on polygons and
closed paths
b) clarify what information is stored with a polygon that is not stored with
a closed path (these 24 bytes)
c) if there are some operations that perform better on polygons than on
closed paths, clarify that as well

#2Tom Lane
tgl@sss.pgh.pa.us
In reply to: PG Bug reporting form (#1)
Re: Chapter "8.8 Geometric Types" of documentation could contain more details

PG Doc comments form <noreply@postgresql.org> writes:

Hi, I am writing to suggest a couple of clarifications to "8.8. Geometric
Types" documentation chapter.

Fair points. I am not really eager to say explicitly here that the
set of available functions varies for the different types: that seems
pretty self-evident. But your other ideas are good.

I also noted while looking at this that table 8.20 is flat out wrong
about the storage size of "line" values: they are 24 bytes each not
32. (This can be confirmed from pg_type.typlen or by looking at
struct LINE in the source code.)

How about the attached?

regards, tom lane

Attachments:

geometric-types-doc-improvement.patchtext/x-diff; charset=us-ascii; name=geometric-types-doc-improvement.patchDownload+14-1
#3Sebastian Skałacki
skalee@gmail.com
In reply to: Tom Lane (#2)
Re: Chapter "8.8 Geometric Types" of documentation could contain more details

Looks great to me, thanks!

śr., 3 lip 2024 o 21:45 Tom Lane <tgl@sss.pgh.pa.us> napisał(a):

PG Doc comments form <noreply@postgresql.org> writes:

Hi, I am writing to suggest a couple of clarifications to "8.8. Geometric
Types" documentation chapter.

Fair points. I am not really eager to say explicitly here that the
set of available functions varies for the different types: that seems
pretty self-evident. But your other ideas are good.

I also noted while looking at this that table 8.20 is flat out wrong
about the storage size of "line" values: they are 24 bytes each not
32. (This can be confirmed from pg_type.typlen or by looking at
struct LINE in the source code.)

How about the attached?

regards, tom lane

--
Regards,
Sebastian Skałacki

#4Tom Lane
tgl@sss.pgh.pa.us
In reply to: Sebastian Skałacki (#3)
Re: Chapter "8.8 Geometric Types" of documentation could contain more details

=?UTF-8?Q?Sebastian_Ska=C5=82acki?= <skalee@gmail.com> writes:

Looks great to me, thanks!

Pushed, thanks.

regards, tom lane