bug#35261: 26.1; EBDB Documentation

[Eric Abrahamsen]

On 04/17/19 03:14 AM, David Masterson wrote:
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> On 04/15/19 20:56 PM, David Masterson wrote:
>
>>> On that, it seems that the documentation is still evolving in that
>>> area. For instance, looking at the documentation of ebdb-field-*
>>> variables says that they are obsolete as of 25.1 and the documentation
>>> is relatively low, so the error above would be confusing in that you'd
>>> wonder if you were looking at the right variable.
>
>> Unfortunately this doesn't have to do with EBDB, but rather with a weird
>> interaction between the help system and EIEIO. Class names apparently
>> once functioned as variables, but no longer do, and so Emacs complains
>> when you try to treat one as a variable. You'll have better luck using
>> help to look up the *function* definitions of the class names, not the
>> variable definition.
>
> Ouch!  That's not logical and will need some explanation somewhere.  The
> logical assumption would be that the function that is asking for input
> is using some variable (structure) as a reference for what it expects as
> input, so, when the error reports a name in the error, the first thought
> would be that that is the structure to look at to get the clue as to
> what it's looking for.  It's a little confusing (to say the least) for
> the lay person to see functions and variables with the same name.
>
> Something to lay out a little more as a primer in the Info docs?

Mmm, I'm not really inclined to spend a lot of time explaining the
weirdnesses of Emacs help system in the EBDB manual, but maybe a pointer
to the function docstrings of the class symbols would be okay.