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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 9 May 2021 12:55:15 -0400
> From: Boruch Baum <boruch_baum@gmx.com>
> Cc: fgunbin@fastmail.fm, 48269@debbugs.gnu.org
> 
> On 2021-05-07 09:20, Eli Zaretskii wrote:
> > > Date: Thu, 6 May 2021 22:47:17 -0400
> > > From: Boruch Baum <boruch_baum@gmx.com>
> >
> > So the problem seems to be that the doc strings don't say the command
> > should be invoked from a *vc-log* buffer, is that right?
> 
> 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.

> >  may I suggest to try looking up the command/variable in the manual?
> 
> For me personally that's a great suggestion, but if that's going to
> be your position for all emacs users you're taking a major step back
> from a long strong precedent of emacs documentation standards and
> one of the features that makes emacs such an attractive environment
> to work in.

I was just trying to help you (and all the other Emacs users) to find
the information more efficiently next time.  No matter how hard we
work on it, there will always be deficiencies in Emacs documentation
(as in any other software documentation), so relying on the developers
to get everything 110% correct is impractical, assuming we all have
something else to do other than read the documentation.