Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE

From: Eli Zaretskii <[email-masked]>
Date: Sun, 09 May 2021 21:54:44 +0300

> Date: Sun, 9 May 2021 14:44:43 -0400
> From: Boruch Baum <[email-masked]>
> Cc: [email-masked], [email-masked]
> 
> > > There could be a sanity-check at the beginning of the function in the form:
> > >
> > >     (unless (eq major-mode foo)
> > >       (user-error "Not in foo buffer"))
> >
> > Yes, but my question was about the doc string: if it said the function
> > should be invoked from a *vc-log* buffer, would that have helped you?
> > Since your original report was against the doc string, I think it's
> > important to understand how we could improve it.
> 
> The short answer then, is yes. But the long answer, adding a sanity
> check to the code, would avoid needing to look at the docstring.

Assuming the text of the user-error message could be detailed enough
to make sense.  A doc string doesn't have to be short, so it's easier
to explain complex stuff there.