GNU bug report logs - #59954
29.0.50; flymake-reporting-backends documentation could use some work

Previous Next

To reply to this bug, email your comments to 59954 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.50; flymake-reporting-backends documentation could use some work
Date: Sat, 10 Dec 2022 15:26:18 -0800

From reading its documentation, I don't understand what the
`flymake-reporting-backends' command does.

The docstring of `flymake-reporting-backends' says:

    Compute reporting Flymake backends in current buffer.

It is also not really explained in (info "(flymake) Troubleshooting").
More precisely, I think it must be spelled out how it's different from
`flymake-running-backends', and in which situations one would want to
use one or the other.

I understand that the "reporting" ones are basically the union of the
running and disabled ones, right?  But why are they considered
"reporting"?  That is not immediately clear to me.  Surely if they are
disabled, they are *not* reporting?  This could use some explanation.

Also, why does the docstring of `flymake-running-backends' and
`flymake-disabled-backends' talk about "computing backends", instead of
simply saying that it "displays" the running/disabled backends?

On a side note, and not necessarily part of this bug report, it would
also be useful with some documentation that says to find out more about
a particular back-end.  Currently, I guess `C-h f' is the recommended
way to do that?

Message #8 received at 59954 <at> debbugs.gnu.org (full text, mbox):

From: João Távora <joaotavora <at> gmail.com>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59954 <at> debbugs.gnu.org
Subject: Re: bug#59954: 29.0.50; flymake-reporting-backends documentation
 could use some work
Date: Sun, 11 Dec 2022 11:28:38 +0000

Stefan Kangas <stefankangas <at> gmail.com> writes:

> The docstring of `flymake-reporting-backends' says:
>
>     Compute reporting Flymake backends in current buffer.

From all the Flymake backends present in `flymake-diagnostic-functions',
the "reporting" ones are the ones that have reported back, i.e. called
their REPORT-FN arguments.

The distinction is (mildly) useful because the Lisp function that
implements them always returns, but that doesn't necessarily mean that
the backend has arranged for the REPORT-FN callback to be called.  When
it is called, the backend enters the "reporting set".

> It is also not really explained in (info "(flymake) Troubleshooting").
> More precisely, I think it must be spelled out how it's different from
> `flymake-running-backends', and in which situations one would want to
> use one or the other.

A "running" backend is simply a backend which has been activated

> I understand that the "reporting" ones are basically the union of the
> running and disabled ones, right?

Not necessarily.  A backend may be running and we haven't yet decided if
it will become a reporting backend or a disabled one.

> "reporting"?  That is not immediately clear to me.  Surely if they are
> disabled, they are *not* reporting?  This could use some explanation.

Best explanation is in these notes and in the code.  There is partially
a historical rationale, as I was trying to keep the visual interface of
the old Flymake reasonably intact, and AFAIR it had representation for
all these states.

But there is also a fair bit of overengineering here.  It makes sense to
represent the states internally, but I've never ever found those
interactive functions useful.  Maybe a bit in the early days of
debugging... IMO you could just trash them or redesign them into a
tabulated list or something.

João

Message #11 received at 59954 <at> debbugs.gnu.org (full text, mbox):

From: João Távora <joaotavora <at> gmail.com>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59954 <at> debbugs.gnu.org
Subject: Re: bug#59954: 29.0.50; flymake-reporting-backends documentation
 could use some work
Date: Sun, 11 Dec 2022 11:36:51 +0000

Stefan Kangas <stefankangas <at> gmail.com> writes:

> On a side note, and not necessarily part of this bug report, it would
> also be useful with some documentation that says to find out more about
> a particular back-end.  Currently, I guess `C-h f' is the recommended
> way to do that?

Yes.  describe-function (C-h f) is the right way because back-ends are
represented by functions.  You can invent a M-x flymake-describe-backend
with a different completion set, but it should funnel to M-x
describe-function and give the very same output.

On a related note, you can see that in the commands M-x
flymake-show-[buffer|project]-diagnostics, the backend's itself is
represented in a column.  Currently this name is synthesized from the
initials of the symbol name bound to the function.  This works well as a
default, but it could be augmented:

For example:

* There could be a 'flymake-backend-name' property on the symbols for
  an extra indirection or better names

* Clicking the name in that report could bring up the same thing as C-h
  f, effectively describing the backend.

João

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.