Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.98.2) (envelope-from ) id 1xEYc2-00000001A2j-2sEE for pgsql-docs@arkaria.postgresql.org; Wed, 07 Oct 2026 20:51:42 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.98.2) (envelope-from ) id 1xEYc1-00000008ZCh-2LtQ for pgsql-docs@arkaria.postgresql.org; Wed, 07 Oct 2026 20:51:41 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.98.2) (envelope-from ) id 1xEYc1-00000008ZCZ-0Xkh for pgsql-docs@lists.postgresql.org; Wed, 07 Oct 2026 20:51:41 +0000 Received: from mail-wm1-x335.google.com ([2a00:1450:4864:20::335]) by makus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.98.2) (envelope-from ) id 1xEYby-00000000sYN-3rmx for pgsql-docs@lists.postgresql.org; Wed, 07 Oct 2026 20:51:39 +0000 Received: by mail-wm1-x335.google.com with SMTP id 5b1f17b1804b1-4a022fee0caso23011415e9.1 for ; Wed, 07 Oct 2026 13:51:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cybertec.at; s=google; t=1791406297; x=1792011097; darn=lists.postgresql.org; h=mime-version:user-agent:content-transfer-encoding:content-type :references:in-reply-to:date:to:from:subject:message-id:from:to:cc :subject:date:message-id:reply-to:content-type; bh=h6CuRpt9tZJW5vzPbjoRr+BPiyfsvKm/ZLiPrNWcWaY=; b=f0nftu1en8Vw+Uhxe0/wAt+msgd/idPOEQS07wB6o5JDGdM9kXggE/fWUI+jDXOQTI 4EXdrgqsy04fZNfavwGkYWyLb3b1/mjR4ZDY36nsmLdJny8BkW865HcyXEhTgw+aRCzE Z2dYkmI0dZSdUiUXVWFvADOI3D4FvDeyKQhjJ+CVGtGHF5h7jPCGOXV6TFkD4VX/SJM1 9FS4wFGNWYrK3qIMQJnZ4bbjoV4hlHRaK3AKDcvBrnXqhcxVzzx3Ekjf5dzRW21GqcZQ rB9Y+2RyVidGze9HaO74w5NVJRCoHJt+mR7IxGiem3KK/N/T19BACiG3WWIHMUhCE1+N OmUQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1791406297; x=1792011097; h=mime-version:user-agent:content-transfer-encoding:content-type :references:in-reply-to:date:to:from:subject:message-id:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=h6CuRpt9tZJW5vzPbjoRr+BPiyfsvKm/ZLiPrNWcWaY=; b=alY8YqUTAhOU6rbp18AQQkiHoqZzFsTxA486bP6KqY3m+XQ2zlQCIA7KV5OayfNWO+ p0y2UO2Omtjd4OsATR/geJVQvHF/6GQHwmS/hzD+l12vMrD87qq/Wl8MOznZObqi1PVL YOm8QmrrfSyNpm6E5y9ET4+fGVQiOQFj3UIT21820xMDyIbVt/Rk4yRD5o/gw6JUilwj /etChvK3T/rgxnwOy5HOS/bxAJ6h9Eb8TEdAhVmISp3YSr96jNkZ3Ndc13LfyD6J7c35 tzSehYn966NtaejKL5Yx2vh6vcrfCmTSfeeNJR2ubG8KheYWGYVJVBnl1TjUOPo5UfBi 4AuA== X-Forwarded-Encrypted: i=1; AKwUvBz4yM/CR8t/60ScQKz9nbMV3lv2XcBG3gJu56mgRt/qO4xLPdAD1rk/Qr2gRBYwHqWwZTpm2eYTYWwl@lists.postgresql.org X-Gm-Message-State: AFuF++mUmvka/xfXhVTpeHNEV2EhpPz6/HlzbrMfemLxpj6qePAMnGkO QCyYmFLzFO9N6PTv/rEGxQ/xn6DGleedMM7J/7ysxmBT6v9N1zzRDeNmnvN5Oyk2R9wgTlkwCkO wQ0jIzFM= X-Gm-Gg: AYBFou3Nk5xV6D/sf8ITDbX/DVHGDr16GH7rMJoknFKSkGoIlA4H0NfqdxIxzGvx/Az vxla+CgcsJIlDZ6OnnHRWbXjhjj++aKKRfzf1nRBGYRhU/77pOx6MPyABdgWaO9J30cVOcBTxW9 ZFcRCvtQVr6slt+qXvLlLcObAF3MgQzA/CGV9nAoLVLeJP+qCE4cmnaj7L5ckWp3YG4V7uRMmRT UGbKKS13iZc6VbRhfGHYmFdxcHixR8OAsFLWev6bmkcEqknzhhERZwElTa7dU9d1uyhOvHMAzAg BHzSiLBDVh15tjiAyesTaosMpjm6D0gr395Nzy4hWNLjzJuo2A4wxbppUVhXhlpNlG2x4z85b8d pT57hIRCv6o9RebYow2VOtFsxTOpRQcZZvTtc8mRC4QJs9U8Rt0NpklQik6giF+I/YaZlBUyK+h b1B3yC0UmE20l0hnfbA4qb1gc5T80gLvcEeTdzX+teQoPqftBICERXjfqLacHZza4WBxSgEBrOu WcDDOsgFIY9MFWlsN6K0e25yueJOoA= X-Received: by 2002:a05:600c:548b:b0:4a1:71ab:63ba with SMTP id 5b1f17b1804b1-4a18045f729mr59385445e9.29.1791406297558; Wed, 07 Oct 2026 13:51:37 -0700 (PDT) Received: from laurenz.albe-K4N0CV00F97414D ([2001:871:270:b677:677f:591c:a18a:2956]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4a1843b5f28sm18459835e9.12.2026.10.07.13.51.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 07 Oct 2026 13:51:36 -0700 (PDT) Message-ID: <0c0971a9fcc6a775caf1d77a241f6ebfeeb8ab84.camel@cybertec.at> Subject: Re: documentation on comment From: Laurenz Albe To: michal.palenik@oma.sk, pgsql-docs@lists.postgresql.org Date: Wed, 07 Oct 2026 22:51:35 +0200 In-Reply-To: <179137223040.1061050.427125467499257106@wrigleys.postgresql.org> References: <179137223040.1061050.427125467499257106@wrigleys.postgresql.org> Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable User-Agent: Evolution 3.60.2 (3.60.2-2.fc44) MIME-Version: 1.0 List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk On Wed, 2026-10-07 at 11:23 +0000, PG Doc comments form wrote: > Page: https://www.postgresql.org/docs/18/sql-altertable.html >=20 > after spending some time searching for how to do comments, maybe some > documentation could be made clearer: >=20 > links from 'create table', 'alter table' to > https://www.postgresql.org/docs/current/sql-comment.html (maybe in the 's= ee > also' section). >=20 > and in 'comment' part, mention that comments on columns can be seen with = \d+ > and comments on tables with \dt+ (\dv+ on views) > so from 'Comments can be viewed using psql's \d family of commands.' to > something like 'Comments can be viewed using psql's \d family of commands= . > To see comments on columns, use \d+ table_name command, for comment on th= e > table itself, use \dt+ table_name command'. Cross references are a good thing. But we should be careful not to repeat everything everywhere. I pretended to be clueless and both looked in the index (where the COMMENT command is referenced) and used the search for "table comment", which also took me right to the COMMENT command. So that is pretty straightforward to find. As you mention, that page points you to psql's \d commands. Searching for "comment" on that page, I quickly found the \dd metacommand (TIL!), which shown comments on some types of objects. Also, it points you to the \d commands for the respective object types to see comments on those. There I quickly found that \d+ will show the description. So I think that it is easy enough to find the information. On the other hand, there is always room for improvement. You suggest to specifically mention \d+ and \dt+ in the COMMENT documentation. I can understand that wish, since it were comments on those objects that you were looking for. But it feels undesirable to me to only mention some object types and not the others. How would you feel about something like Comments can be viewed using psql's \d family of commands, in particular \dd and the + suffix for the \d commands. Yours, Laurenz Albe