[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#20625: 25.0.50; doc of `define-error` is incorrect
From: |
Eli Zaretskii |
Subject: |
bug#20625: 25.0.50; doc of `define-error` is incorrect |
Date: |
Sat, 23 May 2015 17:57:16 +0300 |
> 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.