public inbox for [email protected]
help / color / mirror / Atom feedAdding a Column documentation is misleading
4+ messages / 4 participants
[nested] [flat]
* Adding a Column documentation is misleading
@ 2019-11-06 03:24 PG Doc comments form <[email protected]>
2019-11-06 13:13 ` Re: Adding a Column documentation is misleading Alvaro Herrera <[email protected]>
2019-11-06 14:12 ` Re: Adding a Column documentation is misleading David G. Johnston <[email protected]>
0 siblings, 2 replies; 4+ messages in thread
From: PG Doc comments form @ 2019-11-06 03:24 UTC (permalink / raw)
To: [email protected]; +Cc: [email protected]
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/ddl-alter.html
Description:
In 5.6.1. Adding a Column, there is a kind of example 'ALTER TABLE products
ADD COLUMN description text;'
The words 'description' and 'text' are misleading -- as according to the
formal documentation of the SQL command
(https://www.postgresql.org/docs/12/sql-altertable.html), they should be
'column_name' and 'data_type'.
A similar problem exists for removing a column, and other actions.
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Adding a Column documentation is misleading
2019-11-06 03:24 Adding a Column documentation is misleading PG Doc comments form <[email protected]>
@ 2019-11-06 13:13 ` Alvaro Herrera <[email protected]>
2019-11-07 20:36 ` Re: Adding a Column documentation is misleading Gavin Flower <[email protected]>
1 sibling, 1 reply; 4+ messages in thread
From: Alvaro Herrera @ 2019-11-06 13:13 UTC (permalink / raw)
To: [email protected]; [email protected]
On 2019-Nov-06, PG Doc comments form wrote:
> Page: https://www.postgresql.org/docs/12/ddl-alter.html
> Description:
>
> In 5.6.1. Adding a Column, there is a kind of example 'ALTER TABLE products
> ADD COLUMN description text;'
>
> The words 'description' and 'text' are misleading -- as according to the
> formal documentation of the SQL command
> (https://www.postgresql.org/docs/12/sql-altertable.html), they should be
> 'column_name' and 'data_type'.
Well, it's an example, so "description" is the column name and "text" is
its data type. If you had a table called products, you could run that
command and it would work just fine (assuming you don't already have a
column called description, doh).
Maybe the example could be made clearer by using some other column name
and some other data type, so that they don't resemble english prose or
keywords. Maybe "alter table cities add column year_founded integer".
Do you want to propose something better than that?
> A similar problem exists for removing a column, and other actions.
Let's hear your proposed changes.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Adding a Column documentation is misleading
2019-11-06 03:24 Adding a Column documentation is misleading PG Doc comments form <[email protected]>
2019-11-06 13:13 ` Re: Adding a Column documentation is misleading Alvaro Herrera <[email protected]>
@ 2019-11-07 20:36 ` Gavin Flower <[email protected]>
0 siblings, 0 replies; 4+ messages in thread
From: Gavin Flower @ 2019-11-07 20:36 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; [email protected]
On 07/11/2019 02:13, Alvaro Herrera wrote:
> On 2019-Nov-06, PG Doc comments form wrote:
>
>> Page: https://www.postgresql.org/docs/12/ddl-alter.html
>> Description:
>>
>> In 5.6.1. Adding a Column, there is a kind of example 'ALTER TABLE products
>> ADD COLUMN description text;'
>>
>> The words 'description' and 'text' are misleading -- as according to the
>> formal documentation of the SQL command
>> (https://www.postgresql.org/docs/12/sql-altertable.html), they should be
>> 'column_name' and 'data_type'.
> Well, it's an example, so "description" is the column name and "text" is
> its data type. If you had a table called products, you could run that
> command and it would work just fine (assuming you don't already have a
> column called description, doh).
>
> Maybe the example could be made clearer by using some other column name
> and some other data type, so that they don't resemble english prose or
> keywords. Maybe "alter table cities add column year_founded integer".
> Do you want to propose something better than that?
>
>> A similar problem exists for removing a column, and other actions.
> Let's hear your proposed changes.
>
Now it's explained, it is obvious!
Sorry, for the noise.
Cheers,
Gavin
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Adding a Column documentation is misleading
2019-11-06 03:24 Adding a Column documentation is misleading PG Doc comments form <[email protected]>
@ 2019-11-06 14:12 ` David G. Johnston <[email protected]>
1 sibling, 0 replies; 4+ messages in thread
From: David G. Johnston @ 2019-11-06 14:12 UTC (permalink / raw)
To: [email protected] <[email protected]>; [email protected] <[email protected]>
On Tuesday, November 5, 2019, PG Doc comments form <[email protected]>
wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/ddl-alter.html
> Description:
>
> In 5.6.1. Adding a Column, there is a kind of example 'ALTER TABLE products
> ADD COLUMN description text;'
>
> The words 'description' and 'text' are misleading -- as according to the
> formal documentation of the SQL command
> (https://www.postgresql.org/docs/12/sql-altertable.html), they should be
> 'column_name' and 'data_type'.
>
> A similar problem exists for removing a column, and other actions.
>
Chapter 5 is tutorial-like and uses actual meaningful names instead of
syntax placeholders. I don’t really see a problem aside from maybe a
different example name could be chosen. Making it column_name isn’t an
improvement.
David J.
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2019-11-07 20:36 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-11-06 03:24 Adding a Column documentation is misleading PG Doc comments form <[email protected]>
2019-11-06 13:13 ` Alvaro Herrera <[email protected]>
2019-11-07 20:36 ` Gavin Flower <[email protected]>
2019-11-06 14:12 ` David G. Johnston <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox