[Bug driver/92757] New: Documentation ambiguous/misleading about interplay of optimization and warning flags
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=92757 Bug ID: 92757 Summary: Documentation ambiguous/misleading about interplay of optimization and warning flags Product: gcc Version: 8.3.0 Status: UNCONFIRMED Severity: normal Priority: P3 Component: driver Assignee: unassigned at gcc dot gnu.org Reporter: ricardolafabreu at gmail dot com Target Milestone: --- The documentation (man page for gcc 8.3.0 or https://gcc.gnu.org/onlinedocs/gcc/) could be clearer in what concerns the interaction of optimization and warnings. That optimization options influence the correctness analysis (warnings report possible incorrections) is too general and important a piece of information to be buried in the documentation of individual warning flags. The general documentation for those flag classes says things like > You can request many specific warnings with options beginning with ‘-W’ or > -Wall > >This enables all the warnings about constructions that some users consider > questionable [...] And the opening message in `--help=warnings` is > The following options control compiler warning messages: [...] I find this a bit misleading. There is an ambiguity in that some warnings, "enabled" via a -Wxyz flag, may be effectively disabled due to optimization options (or lack thereof). A particular consequence is that -W flags are not enough to make a build that prints as many warnings as possible (particular -O flags are needed). While the text for the general flag classes claims they enable/control warnings, it fails to mention that enablement/control is only partial. They don't *entirely* enable warnings, not always. There is no hint to this in the general text discussing optimization either, only in particular warning flags. Without reading the documentation for the right specific warning flag, it is easy to assume that warning and optimization flags are orthogonal in general. To prevent ambiguity from arising in the first place, text claiming general properties of -W flags could be completed with something like "provided the required analysis are enabled with the chosen optimization". I believe this would make the text more accurate and informative. For completeness, the section on optimization could also say it affects what analysis are done and, therefore, what warnings are printed.
[Bug driver/92757] Documentation ambiguous/misleading about interplay of optimization and warning flags
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=92757 --- Comment #2 from Ricardo Abreu --- Saying "-Wall enables all the warnings that [...]" is inaccurate. Unless you consider a very specific interpretation of "enables". Then it is ambiguous, because there are other valid (and probably more intuitive) interpretations. Preventing that ambiguity from arising in the first place would make for better documentation. The reader should not have to read on specific warnings to find that -Wall, on its own, does not really enable the warnings it claims. The interplay of optimization and correctness analysis feels to me too general to be left to the documentation of individual warning flags. It is something pertaining to a bigger, structural scope.
[Bug driver/92757] Documentation ambiguous/misleading about interplay of optimization and warning flags
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=92757 --- Comment #3 from Ricardo Abreu --- Note that I would classify this as a request for improvement rather than a bug. A manual is not a specification, it is something that should inform users, and its contents can be better or worse in achieving that for reasons beyond strict correctness.
[Bug driver/92757] Documentation ambiguous/misleading about interplay of optimization and warning flags
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=92757 --- Comment #5 from Ricardo Abreu --- > It has an unambiguous meaning: > > $ gcc -Q --help=warnings | fgrep maybe-uninit > -Wmaybe-uninitialized [disabled] > $ gcc -Q --help=warnings -Wall | fgrep maybe-uninit > -Wmaybe-uninitialized [enabled] > > That's what it means by "enables". The sentence I quoted says -Wall enables a certain group of warnings, not flags. It goes on to characterize that group. It conveys information on its own, without directing to sub-flags. I understand there is a more restrictive sense of "enables" where the sentence is correct. It is the same as when saying that the on position of a switch enables current to go through, in a circuit that requires two switches for current to actually flow. But this is not the only viable one when reading the sentence. Not even, I believe, the most intuitive. Therein lies ambiguity. Even if reading the whole docs later restricts possible interpretations, humans are not compilers and I propose the manual would be clearer if the necessary clarification was offered where needed. I don't see what the motivation would be to inform that a class of flags enable warnings without explaining that enablement is dependent on other flags. This is just this user's feedback, do with it as you see fit. IMO, the patch you propose is already an obvious improvement.
[Bug driver/92757] Documentation ambiguous/misleading about interplay of optimization and warning flags
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=92757 --- Comment #7 from Ricardo Abreu --- Yes, the very next paragraph directs to tens of other paragraphs that mention other switches. One has to read them SFINAE mode to discover the special meaning of the general text. That may be considered strictly correct, but it is still not very good documentation. It is bound to mislead many readers. Usually CLI switches aren't silently inoperative until you provide other switches. That is a questionable UI decision to begin with, if you ask me. How can you say that expecting a switch to actually turn something on is trying really hard to find alternative meanings? It all seems pretty obvious really, I am only having to try hard explaining because you are trying so hard to dismiss it.
[Bug driver/92757] Documentation ambiguous/misleading about interplay of optimization and warning flags
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=92757 --- Comment #8 from Ricardo Abreu --- Don't get me wrong, I have a lot of admiration for GCC and the people behind! It approaches perfection to a level that is very unusual in software. Still, that does not amount to saying it is perfect. There is always margin for improvement. What I am perceiving is that you are so used to how it is that you immediately resist considering how it could be. You may of course decide a suggestion is not worth the effort, but that is not the same as claiming it invalid.
[Bug driver/92757] Documentation ambiguous/misleading about interplay of optimization and warning flags
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=92757 --- Comment #10 from Ricardo Abreu --- > Usually CLI applications don't have as many switches as GCC with as many > non-trivial interactions between them. True, but I am not sure I understand your point. To me that sounds like all the more reason to avoid coupling between them and document it prominently otherwise. My outsider impression is that, ideally, turning on -W... flags should turn on whatever analysis was needed, independently of optimization. It would make for smoother UI because it would be more in line with the natural affordance of a switch. I suppose the increase in compilation cost would be justified by the request for more checking. I am sure there are reasons why this is unfeasible, undesirable, too risky... Better highlighting in documentation would alleviate the surprise.
