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

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

[Ihor Radchenko]

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>

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

[Yuu Yin via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Ihor Radchenko <yantar92@posteo.net> writes:

> 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>

Hi,

Just to make it clear, `:tag' is as in
`(const :tag "nofold: show all" nil)', as in a defcustom composite type, right.

This seems like a simple feature to an experienced Elip programmer to
implement, which in turn would add so much value. Fortunately
`defcustom' provides the types, but users need to be explicitly aware of
types to correctly use the variables, so adding that to *Help*, or
`variable-describle`, would help a lot. Another wish of mine would be
the minibuffer showing the types alongside the signature if feasible, so
the user has instant feedback on the types.

--
Yuu Yin