Hi devs,
Take a quick look at
https://gitlab.haskell.org/ghc/ghc/-/blob/6db8a0f76ec45d47060e28bb303e9eef60bdb16b/compiler/GHC/Driver/Errors/Types.hs#L107
<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@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
