GNU bug report logs - #58854
[WISH] Could *Help* buffers provide information about :type of defcustoms?

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 29 Oct 2022 02:24:13 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Oct 28 22:24:12 2022
Received: from localhost ([127.0.0.1]:34663 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1oobW8-0002NC-IU
	for submit <at> debbugs.gnu.org; Fri, 28 Oct 2022 22:24:12 -0400
Received: from lists.gnu.org ([209.51.188.17]:36046)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <yantar92@HIDDEN>) id 1oobW4-0002N1-2O
 for submit <at> debbugs.gnu.org; Fri, 28 Oct 2022 22:24:11 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <yantar92@HIDDEN>)
 id 1oobVz-0004fC-U9
 for bug-gnu-emacs@HIDDEN; Fri, 28 Oct 2022 22:24:04 -0400
Received: from mout01.posteo.de ([185.67.36.65])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <yantar92@HIDDEN>)
 id 1oobVx-0006Pm-Oy
 for bug-gnu-emacs@HIDDEN; Fri, 28 Oct 2022 22:24:03 -0400
Received: from submission (posteo.de [185.67.36.169]) 
 by mout01.posteo.de (Postfix) with ESMTPS id C2BC1240026
 for <bug-gnu-emacs@HIDDEN>; Sat, 29 Oct 2022 04:23:57 +0200 (CEST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017;
 t=1667010239; bh=FXqJtXZEkvtFicWoIBBYsNJDtpDN/+QWsKPa5C8+TtI=;
 h=From:To:Subject:Date:From;
 b=j2SrrHhDipdzp0ysBAIxUXh/WduJYjQV5+IbGtc758My8k55IIYvaBFVHgbXzWe1a
 xQ4TfDW1A6tbcY9qHWrwyGPI/EbINxb3M/RLnlj49IX64pt8tdHy8rvlRr5Nfd0SWX
 f583zLG8K1ZQagY4i6M+AdOiaTkpiiPCXoV2h64PMtsq9vNLO2oiub4NcDar54Rvy2
 X19PcxO2T1l6j1tvEQwWpViwrQKZcgHVnZEG2oKUtlpreOntKnF96mIhti6BVYzHop
 hTT3hAFGilEAaw9DM7RrDDCYBLTl0IiYGEy3XLgdwToe3tZBwlZYmRNdywD/oEIpc5
 5zYIPesKgling==
Received: from customer (localhost [127.0.0.1])
 by submission (posteo.de) with ESMTPSA id 4Mzjs81Fxsz9rxD
 for <bug-gnu-emacs@HIDDEN>; Sat, 29 Oct 2022 04:23:55 +0200 (CEST)
From: Ihor Radchenko <yantar92@HIDDEN>
To: bug-gnu-emacs@HIDDEN
Subject: [WISH] Could *Help* buffers provide information about :type of
 defcustoms?
Date: Sat, 29 Oct 2022 02:24:39 +0000
Message-ID: <87mt9fl63c.fsf@localhost>
MIME-Version: 1.0
Content-Type: text/plain
Received-SPF: pass client-ip=185.67.36.65; envelope-from=yantar92@HIDDEN;
 helo=mout01.posteo.de
X-Spam_score_int: -43
X-Spam_score: -4.4
X-Spam_bar: ----
X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,
 RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001,
 SPF_PASS=-0.001 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -1.3 (-)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -2.3 (--)

Hi,

In Org, we have seen a number of reports when people tried to set
custom variables via setq and used the values that are not recognized.

Such issue commonly occurred when the allowed values were listed in
:type specification, but not in the docstring.

Indeed, one can update the docstring every time :type specification is
changed/added. However, it would be nice if *Help* buffers automatically
listed the allowed variable values according to :type specification.

I propose the following:
1. If a defcustom contains :type keyword, *Help* can add auto-generated
   paragraph describing the allowed values:

   The variable can take the following values:
   - <type1 :tag> :: <type1>
     - <subtype :tag> :: <subtype>
     ...
   - <type2 :tag> :: <type2>
   ...
2. The feature can be explicitly disabled by setting :type-doc nil.

WDYT?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>