Re: [PATCH] driver: Improve the generated help text for alias options with arguments

[Richard Sandiford <richard.sandiford@arm.com>]

Lewis Hyatt via Gcc-patches <gcc-patches@gcc.gnu.org> writes:
> Hello-
>
> Currently, if an option is both undocumented and an alias for a second option,
> the help text generated by gcc --help directs the reader to use the other
> option instead. This makes sense for deprecated options, but it seems this
> pattern is also used for another case, namely when an option exists so as to
> pass a default argument to another option. For instance this one, from
> common.opt:
>
> -------------
> fdiagnostics-color
> Common Alias(fdiagnostics-color=,always,never)
> ;
>
> fdiagnostics-color=
> Driver Common Joined RejectNegative Var(flag_diagnostics_show_color) Enum(diagnostic_color_rule) Init(DIAGNOSTICS_COLOR_NO)
> -fdiagnostics-color=[never|always|auto]	Colorize diagnostics.
> -------------
>
> This is nice because it means you can say -fdiagnostics-color as a shorthand
> for -fdiagnostics-color=always, or -fno-diagnostics-color as a shorthand for
> -fdiagnostics-color=never. However, the generated help text does not describe
> it this way:
>
> -------------
> $ gcc --help=common | grep fdiagnostics-color
>   -fdiagnostics-color         Same as -fdiagnostics-color=.  Use the latter option instead.
>   -fdiagnostics-color=[never|always|auto] Colorize diagnostics.
> -------------
>
> Perhaps I am wrong and the non-argument usage is indeed meant to be deprecated,
> but it feels more like it was intended as a convenience and could be documented
> as such. What actually prompted this patch is that I am adding a new option for
> GCC 11 with these never/always/auto semantics and I am a bit confused whether I
> am supposed to add the aliased version or not. Feels like it's nice to add it,
> but then the --help output says the opposite...
>
> Anyway, the attached patch would change the help output to the following... If
> that seems to be an improvement and closer to the intended behavior, please let
> me know. Thanks!
>
> -------------
>   -fdiagnostics-color         Same as -fdiagnostics-color=always (or, in negated form, -fdiagnostics-color=never).
>   -fdiagnostics-color=[never|always|auto] Colorize diagnostics.
> -------------
>
> FWIW there are three other options currently affected by this change
> (-Wimplicit-fallthrough, -fcf-protection, and -flive-patching). The change for
> -Wimplicit-fallthrough I think is particularly helpful:
>
> -Wimplicit-fallthrough      Same as -Wimplicit-fallthrough=.  Use the latter option instead.
> becomes
> -Wimplicit-fallthrough      Same as -Wimplicit-fallthrough=3 (or, in negated form, -Wimplicit-fallthrough=0).

I also see:

-  -ftail-call-workaround      Same as -ftail-call-workaround=.  Use the latter option instead.
+  -ftail-call-workaround      Same as -ftail-call-workaround=1 (or, in negated form, -ftail-call-workaround=0).
   -ftail-call-workaround=<0,2> Disallow tail call optimization when a calling routine may have omitted character lengths.
...
   --imacros                   Same as -imacros.  Use the latter option instead.
   --imacros=                  Same as -imacros.  Use the latter option instead.
   --include                   Same as -include.  Use the latter option instead.
-  --include-barrier           Same as -I.  Use the latter option instead.
+  --include-barrier           Same as -I-.
   --include-directory         Same as -I.  Use the latter option instead.
   --include-directory-after   Same as -idirafter.  Use the latter option instead.
   --include-directory-after=  Same as -idirafter.  Use the latter option instead.
...
-  -Wnormalized                Same as -Wnormalized=.  Use the latter option instead.
+  -Wnormalized                Same as -Wnormalized=nfc (or, in negated form, -Wnormalized=none).
   -Wnormalized=[none|id|nfc|nfkc] Warn about non-normalized Unicode strings.

I agree all of these look like improvements, especially the
--include-barrier one.  But I think the include ones also show
that the "Use the latter option instead." decision is independent
of whether the option is defined to be an alias.

FWIW, there's also:

Wmissing-format-attribute
C ObjC C++ ObjC++ Warning Alias(Wsuggest-attribute=format)
;

which still ends up as:

  -Wmissing-format-attribute  Same as -Wsuggest-attribute=format.  Use the latter option instead.

Not really my area though, so I don't have any specific suggestion
about how to separate the cases.

Thanks,
Richard