EEP 74: Erlang Error Index

[robertoaloi]

This EEP introduces the idea of an "Error Index" (a catalogue of errors) and a standardized format for diagnostics.
While I am not sure an EEP is strictly necessary for this - since this is not really an extension to the language -, we can use this to start the discussion.

[josevalim]

Good call, I was thinking about adopting the same for Elixir. I have two questions for now:

1. How important is the doc url? I often prefer to include all information in the diagnostic, rather than send the user to a separate page. Is it required or optional at the LSP level?

2. What about "shared codes"? For example, both Erlang and Elixir emit unused variable warnings. Should they have the same code? Perhaps the same number? But different prefixes?

[essen]

I would say the doc URI is very important when the user needs to find more info as the alternative is the good old search, and it's not very good.

Instead of ERL-1234 you can refer to it as a URI such as erlc:1234 or use a more descriptive name such as erlc:expr_upd_lit. Then define the erlc scheme as translating to HTTP into https://errors.erlang.org/erlc/expr_upd_lit where you'd get the details about the error.

This would have minimal impact over OTP tooling, but be a lot more beneficial for third party tools as they could provide their own URIs instead of making the user guess where to find info on the error. For example Elvis could use elvis.github.io/lines_too_long as its error identifier.

Alternatively, you could have the official registry open to third party submissions and use the erl scheme that translates to https://registry.erlang.org where for example erl:expr_upd_lit would lead to https://registry.erlang.org/expr_upd_lit and erl:elvis/lines_too_long would translate to https://registry.erlang.org/elvis/expr_upd_lit.

In both cases it is fairly easy to reach the docs.

[robertoaloi]

1. How important is the doc url? I often prefer to include all information in the diagnostic, rather than send the user to a separate page. Is it required or optional at the LSP level?

It is optional in LSP. Specifically, a LSP Diagnostic has an optional CodeDescription field, which in turns contains a href (the URI). See the specs.

I totally agree the doc_uri should be optional and present only when it contains additional information (context, examples) that cannot be expressed in a single, one-liner, error message.

2. What about "shared codes"? For example, both Erlang and Elixir emit unused variable warnings. Should they have the same code? Perhaps the same number? But different prefixes?

Good question. Spontaneously, I would expect Elixir codes to have a different namespace/prefix, which would imply the numeric part doesn't really matter. The main reason is that you may want to search for an Elixir error code and get to a page with Elixir info/examples. Nothing stops the Elixir page to link to the corresponding Erlang error code if there's extra information that could be relevant. We could make an effort to keep them align, but it's probably not so important.