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

[Lewis Hyatt <lhyatt@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2435 bytes --]

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).

-Lewis

[-- Attachment #2: ChangeLog.txt --]
[-- Type: text/plain, Size: 135 bytes --]

2020-03-15  Lewis Hyatt  <lhyatt@gmail.com>

	* opts.c (print_filtered_help): Improve the help text for alias options
	with arguments.

[-- Attachment #3: alias_opt.patch --]
[-- Type: text/plain, Size: 1591 bytes --]

diff --git a/gcc/opts.c b/gcc/opts.c
index ac160ed8404..a120858d77b 100644
--- a/gcc/opts.c
+++ b/gcc/opts.c
@@ -1315,14 +1315,31 @@ print_filtered_help (unsigned int include_flags,
       if (option->alias_target < N_OPTS
 	  && cl_options [option->alias_target].help)
 	{
+	  const struct cl_option *target = cl_options + option->alias_target;
 	  if (option->help == NULL)
 	    {
-	      /* For undocumented options that are aliases for other options
-		 that are documented, point the reader to the other option in
-		 preference of the former.  */
-	      snprintf (new_help, sizeof new_help,
-			_("Same as %s.  Use the latter option instead."),
-			cl_options [option->alias_target].opt_text);
+	      /* The option is undocumented but is an alias for an option that
+		 is documented.  If the option has alias arguments, then its
+		 purpose is to provide certain arguments to the other option, so
+		 inform the reader of this.  Otherwise, point the reader to the
+		 other option in preference to the former.  */
+
+	      if (option->alias_arg)
+		{
+		  if (option->neg_alias_arg)
+		    snprintf (new_help, sizeof new_help,
+			      _("Same as %s%s (or, in negated form, %s%s)."),
+			      target->opt_text, option->alias_arg,
+			      target->opt_text, option->neg_alias_arg);
+		  else
+		    snprintf (new_help, sizeof new_help,
+			      _("Same as %s%s."),
+			      target->opt_text, option->alias_arg);
+		}
+	      else
+		snprintf (new_help, sizeof new_help,
+			  _("Same as %s.  Use the latter option instead."),
+			  target->opt_text);
 	    }
 	  else
 	    {