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

From: Yuu Yin <[email-masked]>
Date: Sat, 18 Feb 2023 13:42:48 -0300

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