Subject: bug#58854: [WISH] Could *Help* buffers provide information about :type of defcustoms?

From: Ihor Radchenko <[email-masked]>
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>