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

Previous Next

Full log

View this message in rfc822 format

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: 58854 <at> debbugs.gnu.org
Subject: bug#58854: [WISH] Could *Help* buffers provide information about :type of defcustoms?
Date: Sat, 29 Oct 2022 02:24:39 +0000

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>

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.