value of documenting error messages?

[Alec Theriault]

Hello,

If these are the messages that get pretty-printed into errors or warnings,
I would think detailed documentation is definitely useful. However, since
this is documentation that users of GHC will want to read (and not just
contributors), I think it should live primarily in the user's guide and not
the Haddocks.

Rust has taken an interesting approach for this: every error message is
given a unique number like "E0119" and there is an error index
<https://doc.rust-lang.org/error-index.html#E0119> generated from simple
markdown files
<https://github.com/rust-lang/rust/tree/master/compiler/rustc_error_codes/src/error_codes>
containing explanations and examples for the errors (error codes by
themselves already massively help searchability). If GHC were to take this
approach, I think it would be fine to just include the error message
identifier in the Haddocks.

Alec

PS: Rust even bundles the documentation for errors into the compiler, so
you can do something like `rustc --explain E0119` to get the full
description of the error. It'd be pretty neat if GHC could do this too.
Some errors don't have much to say about them, but others definitely could
be explained!

On Tue, Jun 1, 2021 at 2:36 PM Richard Eisenberg <rae at richarde.dev> wrote:

> Hi devs,
>
> Take a quick look at
> https://gitlab.haskell.org/ghc/ghc/-/blob/6db8a0f76ec45d47060e28bb303e9eef60bdb16b/compiler/GHC/Driver/Errors/Types.hs#L107
> You will see a datatype there with constructors describing error messages
> that GHC might produce. These constructors have comments describing the
> error, sometimes giving an example, and sometimes listing test cases. More
> datatypes like this one and more constructors in these datatypes are on the
> way.
>
> Question: Is there sufficient value in carefully documenting each
> constructor?
>
> In my ideal world, each constructor would have a high-level description, a
> detailed description of each field, an example of a program that generates
> the error, and one or more test cases that test the output. Along the way,
> we might discover that no such test case exists, and then we would add.
> However, generating this documentation is hard. I was thinking of whipping
> up an army of volunteers (Hécate has advised me how to do this) to do the
> work, but that army will need to be fed (with instructions, supervision,
> and reviews) and will want to know that their work is important. Is this
> effort worthwhile? Do we see ourselves maintaining this documentation? Or
> is the effort better spent elsewhere, perhaps tagging each constructor with
> an ID and then making wiki pages? Not sure what's best -- would love ideas!
>
> Credit to Alfredo di Napoli, who's done the heavy lifting of getting us
> this far.
>
> Relevant tickets:
> Original: https://gitlab.haskell.org/ghc/ghc/-/issues/18516
> Tasks left: https://gitlab.haskell.org/ghc/ghc/-/issues/19905
>
> Thanks,
> Richard
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20210601/958c2ae7/attachment.html>