On Sat, Jan 3, 2026 at 11:30 PM Chao Li <[email protected]> wrote: > On Jan 2, 2026, at 10:54, Robert Treat <[email protected]> wrote: > Hi Robert, > > Thanks you very much for your review. > > > On Thu, Dec 18, 2025 at 2:22 AM Chao Li <[email protected]> wrote: > Hi Hacker, <snip> > 2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]” missed “[]" > with “COLUMN”, which is misleading, because “COLUMN” is actually optional. > > Seems technically correct and potentially useful, and I see you > handled this for the DROP COLUMN variant as well, so I could see a +1 > on this one. > > Thanks for confirming. > > > 3. For all “alter column” sub-commands, "ALTER [ COLUMN ]” are omitted, which > is also confusing, because none of other sub-commands omit their prefix part. > > > Hmm... I'm curious what you find confusing about this. Is the > confusion in trying to find or understand the information presented, > or confusing as to why it isn't all documented the same way? The > downside of your "fix" is that this introduces a lot of extra text > that is more or less noise, especially for folks trying to skim the > documents looking for very specific command references. And while I > agree that we aren't 100% consistent on this within the ALTER TABLE > subcommands, we use this same mixed pattern of omission on other pages > (see ALTER TYPE for instance). If we were to insist on making this > consistent here, I think we'd probably need to look at other pages as > well and evaluate or update them too. I'm not sure that would be an > improvement though. > > > The confusion came from my own first-time reading of the documentation. Since > the page is quite long, when I was reading the action descriptions and wanted > to confirm the exact sub-command syntax, I often had to scroll back up to the > syntax section. That led me to think it might be helpful to include the full > sub-command form directly with the action descriptions. > > That said, I understand your concern. The change did make the text longer and > added noise. In v2, I’ve therefore reverted that broader change. As you > pointed out, if we were to pursue this kind of consistency, it would need to > be handled across other similar pages as well, which would be better done as > a dedicated and more carefully scoped patch. > > So, v2’s scope is significantly reduced, only a fix for my original point 2 > is retained. >
Makes sense to me and seems like an improvement, so +1. Robert Treat https://xzilla.net
