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

Previous Next

To reply to this bug, email your comments to 58854 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [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>

Message #10 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Yuu Yin <yuu <at> anche.no>
To: Ihor Radchenko <yantar92 <at> posteo.net>, bug-gnu-emacs <at> gnu.org
Subject: Re: [WISH] Could *Help* buffers provide information about :type of
 defcustoms?
Date: Sat, 18 Feb 2023 13:42:48 -0300

Ihor Radchenko <yantar92 <at> 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

Previous Next

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