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

[Boruch Baum]

On 2021-05-09 20:15, Eli Zaretskii wrote:
> > 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.

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.

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

The most efficent way seems to me to add the sanity-check to the code.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0