Warnings: documentation, UI, choice of defaults, synchronization with Dune

[xavierleroy]

There's a discussion at ocaml/dune#8645 on Dune's infamous choice of having more warnings active by default than the core compilers and making these warnings into errors. The Dune maintainers seem open to change this, but several improvements to the core system should be considered in parallel:

• Clarify the documentation of warnings in the reference manual. Right now it's hard to see which are active by default. We need a table with a line for each warning giving number, long name, whether it is active (or active + error) by default, "since" which version, description, and link to examples if any.
• We have letters to designate groups of warnings, e.g. K means "all 'unused' warnings". Why not having long names too?
• What about having a very small number of "presets", i.e. recommended configurations for warnings? For example, "none", "default", "reasonable" and "all", with "default" being the current default choice in the compiler and "reasonable" being something like the current Dune default. In GCC and Clang terms, "reasonable" is -Wall and "all" is -Wall -Wextra -Wpedantic.

I'm sure there are other improvements that can be considered. Let's discuss them here?

[gasche]

The information on whether a warning is active could also be given in the --warn-help output. (In fact one could accept ocamlc -w ... -w ... -warn-error ... -warn-help, and show whether each warning is enabled or disabled with the current user settings.)

I like your idea of reclaiming some choices regarding warnings. One important aspect that is only touched in your question is whether we should do some spring cleaning and change the warnings we enable by default. We have not done it in the last few years, and it did not matter because everyone is using the dune presets anyway. If we want to reach a convergence/consensus between stock OCaml and dune, we should look critically at our current default set -- it is easy to change it as it has very few direct users.

[SkySkimmer]

It sounds rather confusing to say that "default" is not "reasonable". If the default is unreasonable why not change it?

Configurations which may make sense IMO:

• none
• basic: warnings which when triggered are very reliably programmer mistakes (non exhaustive pattern matching, redudant pattern, unused-var), probably close to the current defaults?
• default: warnings which when triggered are reliably programmer mistakes, bad style or at least easily silenced, probably close to dune defaults (modulo the warn-error debate)?
• pedantic: default + warnings which are not recommended but can be useful in some situations (eg unused-var-strict)
• all: pedantic + the warnings which enough people find useful to avoid deleting them but not enough agree to put them in pedantic (disambiguated‐name?)

[xavierleroy]

Yes, changing the warnings we enable by default is also on the table. I would not use the "very few direct users care anyway" argument, as I'm one of those few :-), but there are old choices that should be reconsidered, as we did in #10140.

[dbuenzli]

• What about having a very small number of "presets", i.e. recommended configurations for warnings?

That would be nice. I don't think micro managing warnings is that useful, except for selectively disabling them on a portion of code. That in turn would allow different build systems to agree on default sets via upstream and automatically evolve them as the language evolves.

dune's default set is nice for code hygiene but (especially when combined with their default warn-error behaviour) it's absolutely horrendous for development where for example internal stuff easily goes up transiently unused when you mess around.

For example, "none", "default", "reasonable" and "all",

To try to characterize that a bit more:

• none, no warnings.
• default, obvious programming errors (e.g. incomplete pattern matching) or style upstream wants to mandate (e.g. the recently added mandatory labelling)
• reasonable or rather lint or hygiene, warnings that further help with code maintenance.
• all, all warning.

With the idea that each set is contained in the other. I'm however curious as what the difference between reasonable and all entails in practice.

[xavierleroy]

Don't be fixated on my choice of "default" and "reasonable" words, it was just an example, and I agree "basic" and "extended" would work better. But I do think some OCaml warnings should remain off for most code bases, such as warning 4 fragile-match, as it leads to writing convoluted and non-idiomatic pattern matchings.