[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#20625: 25.0.50; doc of `define-error` is incorrect
From: |
Drew Adams |
Subject: |
bug#20625: 25.0.50; doc of `define-error` is incorrect |
Date: |
Sat, 23 May 2015 07:48:46 -0700 (PDT) |
> > 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.