bug#59954: 29.0.50; flymake-reporting-backends documentation could use some work

bug#59954: 29.0.50; flymake-reporting-backends documentation could use some work

[Stefan Kangas]

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?

bug#59954: 29.0.50; flymake-reporting-backends documentation could use some work

[João Távora]

Stefan Kangas <stefankangas@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

bug#59954: 29.0.50; flymake-reporting-backends documentation could use some work

[João Távora]

Stefan Kangas <stefankangas@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