bug#20625: 25.0.50; doc of `define-error` is incorrect

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sat, 23 May 2015 07:48:46 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 20625@debbugs.gnu.org
> 
> > > MESSAGE is not necessarily a string. It is a requiredargument,
> > > but the code explicitly makes use of the case where it is nil.
> > > And existing code delivered with Emacs (e.g. bookmark.el) makes
> > > use of a nil MESSAGE.  That case should be documented.
> > 
> > AFAICS, users of this property will yield strange messages if
> > MESSAGE is nil.  So shouldn't we at least advise that it's a string?
> > 
> > Also, what exactly is the purpose of bookmark.el's using nil there?
> 
> I'm no expert in this, and I wasn't the one who changed bookmark.el
> (in 24.4) to use `define-error'.
> 
> But it seems that what is meant is that `bookmark-errors' is being
> declared to be an error condition, but with no definition: no
> message and no parent (other than the default, `error').
> 
> This is the Emacs 24.3 code:
> 
> (put 'bookmark-error-no-filename
>      'error-conditions
>      '(error bookmark-errors bookmark-error-no-filename))
> (put 'bookmark-error-no-filename
>      'error-message
>      "Bookmark has no associated file (or directory)")
> 
> And this is the 24.4+ code:
> 
> (define-error 'bookmark-errors nil)
> (define-error 'bookmark-error-no-filename
>   "Bookmark has no associated file (or directory)"
>   'bookmark-errors)
> 
> In both cases, `bookmark-errors' is presumably being declared
> as an error condition, but it is not defined in any way.  It
> is presumably there to provide a more general category than
> `bookmark-error-no-filename'.  That makes sense to me.

I've grepped all the uses of 'error-message property in the Emacs
sources, and I only see uses that expect the value to be a string.

> If my interpretation is correct, then something like that
> explanation should be added to the doc, I think.  Before
> `define-error', things were clear enough with the doc for
> property `error-conditions'.  It seems that the doc for
> `define-error' should cover the same cases.
> 
> I believe that means that with nil MESSAGE, property
> `error-conditions' is applied (using MESSAGE), and property
> `error-message' is not (absent or nil value).
> 
> In fact, I think that the right change would be not only
> to say what nil MESSAGE means but to make MESSAGE an
> &optional parameter.

I cannot describe in the docs something I don't understand.  I hope
someone who will would either fix the docs or post here what it means
for that property to have a nil value, and then I can put that in the
docs.