Run edoc to generate diagnostics

[alanz]

Running edoc against a file can generate diagnostics for errors in the comments.

Do this on save, and present the output as LSP diagnostics.

[robertoaloi]

Hi, I just looked at edoc and it looks like the high-level API makes extensive usage of a edoc_report which use standard IO to display messages (errors and warnings) to the user. I could not find a way to return those messages programmatically, so that we can convert them into LSP messages. I see two optionsn here:

1. Modify edoc so that it can return errors/warnings (require an upstream change, will only work with new versions of OTP)
2. Duplicate some of the edoc logic and use a lower level API to retrieve the errors (lower level API may change at any time, so harder to maintain).

Maybe @richcarl, @garazdawi or @KennethL have an opinion on this? The goal is to run edoc on save and show EDoc errors and warnings to the user in the IDE.

[KennethL]

I think a modification of edoc in OTP is the best choice. What is the problem with requiring OTP 24.x or 25 for all features of Erlang LS? You can even bundle the required OTP version with Erlang LS and separate what Erlang LS is using for it execution from what the user i running his code on. I think the general approach should be to add features in PTP which makes other code and dependencies unnecessary. I will support feature requests on OTP in that direction By the way what would the criteria for running edoc on save be? I hope it will not run for modules not using edoc comments at all? Or maybe it should be configurable? /Kenneth

…

On Wed, Jul 14, 2021, 16:10 Roberto Aloi ***@***.***> wrote: Hi, I just looked at edoc and it looks like the high-level API makes extensive usage of a edoc_report which use standard IO to display messages (errors and warnings) to the user. I could not find a way to return those messages programmatically, so that we can convert them into LSP messages. I see two optionsn here: 1. Modify edoc so that it can return errors/warnings (require an upstream change, will only work with new versions of OTP) 2. Duplicate some of the edoc logic and use a lower level API to retrieve the errors (lower level API may change at any time, so harder to maintain). Maybe @richcarl <https://github.com/richcarl>, @garazdawi <https://github.com/garazdawi> or @KennethL <https://github.com/KennethL> have an opinion on this? The goal is to run edoc on save and show EDoc errors and warnings to the user in the IDE. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#384 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABFWSBTR7VDIOHB45LCKSLTXWLFDANCNFSM4KGR3STA> .

[richcarl]

Yes, I think it would be good to modify edoc to make it return errors/warnings. Back when I wrote this stuff, I didn't have any real understanding of programmatic use of error information for integrations or even proper logging, so that's where it's really weak.

[robertoaloi]

I think a modification of edoc in OTP is the best choice.

It looks like we have an agreement, then.

What is the problem with requiring OTP 24.x or 25 for all features of
Erlang LS? You can even bundle the required OTP version with Erlang LS and
separate what Erlang LS is using for it execution from what the user i
running his code on.

In principle, yes. Unfortunately the decoupling between the Erlang LS and the user runtime is not yet complete, but that's exactly where we want to be. For the time being, the backend will have to distinguish between OTP versions and provide certain features only for newer versions.

By the way what would the criteria for running edoc on save be?
I hope it will not run for modules not using edoc comments at all?
Or maybe it should be configurable?

As all diagnostics backend, it will be configurable. We generally disable new backends by default until they get stable. It's up to the backend us to specify when to actually run edoc. A backend that only runs if there's at least one edoc tag sounds like a reasonable optimization.

[robertoaloi]

Raised a feature request to erlang/otp about this: erlang/otp#5056