bug#18694: 25.0.50; `ibuffer(-saved)-filter-groups', `ibuffer-saved-filters'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> The user says: "I'm guessing at the predicate bit as I can't find any
> examples or documentation. What should it really look like?"
>
> 1. The doc string for these variables should describe the structure
> better.  It should not send readers off to look at the doc string of
> internal variable `ibuffer-filtering-qualifiers', especially since that
> doc string just says that a qualifier has the form (SYMBOL . QUALIFIER),
> and it does not even say what form or type this QUALIFIER has as a Lisp
> entity.

I've now added a modified version of the example that Alexis gave later
in this bug report.

> This would also encourage you not to use QUALIFIER in two completely
> different ways: QUALIFIER ==> (SYMBOL . QUALIFIER).
>
> The doc of the two user options even refers to the doc string of
> `ibuffer-filtering-qualifiers' *twice*, unnecessarily.

Digging down into all the doc strings that refer to each other, it seems
to me that the information is there, it just tries to avoid repeating
the same information in several doc strings.

But the example should help tremendously.

> 2. The defcustoms of the user options should use something more specific
> (so more useful to users) as the :type than just (repeat 'sexp).  A
> better :type will help users customize the option and understand its
> structure.  And if you try to specify the structure for defcustom :type
> then maybe that will help you do a better job of describing it for
> users in the doc string.

This has been fixed somewhat since this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no