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

[Drew Adams <drew.adams@oracle.com>]

> 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.

What can I say, beyond what I said?  I don't think that is really
relevant.  A nil value means (I think) precisely that an error
condition is declared that has no associated message string.  The
fact that no code makes use of such an error condition doesn't
mean anything significant, IMO.

IIUC, the use of `bookmark-errors' with a nil value in bookmark.el
is precisely the same as its use of `bookmark-errors' with
`error-condition' prior to Emacs 24.4.  It declares, even if it
does not define an error message for, an error condition that
is more general than `bookmark-error-no-filename'.

It tells programmers who might define their own bookmark errors
to have them, like `bookmark-error-no-filename', inherit from
condition `bookmark-errors'.  That seems reasonable to me.  But
of course it is not necessary - users can just have their new
bookmark errors inherit from `error'.

Now you could argue that the presence of `bookmark-errors' in
bookmark.el prior to Emacs 24.4 was a mistake.  That is the
same argument as saying that its presence now is a mistake.
But if you suppose that it is a good idea to predefine a general
error class for bookmark code, then I don't see why doing so
using `define-error' is any less meaningful/reasonable than
doing so using property `error-conditions' directly.

> 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.

I tried to explain the meaning, as I understand it.  Perhaps
the person who changed the Emacs 24.3 bookmark.el code to use
`define-error', or the person who introduced `define-error' to
Emacs 24.4, can confirm what I said or otherwise weigh in here.

Meanwhile, perhaps you could consider mentioning that the
MESSAGE value can be nil.  (This doc bug would remain open, as
long as what nil means is not described, but at least the type
of MESSAGE would not be incorrectly specified).  And perhaps
you could consider making parameter MESSAGE optional (since,
in effect, it is).