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

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

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

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.