Add G_OPTION_FLAG_DEPRECATED

Generate a deprecation notice in the `--help` output for deprecated
options. This helps with the documentation of command line utilities.

Put the deprecation notice near the argument, to allow application
developers to add a notice on the deprecation on their own, and
explain what to use instead.

glib/goption.c

@@ -541,6 +541,10 @@ calculate_max_length (GOptionGroup *group,
       if (!NO_ARG (entry) && entry->arg_description)
         len += 1 + _g_utf8_strwidth (TRANSLATE (group, entry->arg_description));
 
+      /* " (deprecated)" */
+      if (entry->flags & G_OPTION_FLAG_DEPRECATED)
+        len += 3 + _g_utf8_strwidth (_("deprecated"));
+
       max_length = MAX (max_length, len);
     }
 
@@ -577,9 +581,16 @@ print_entry (GOptionGroup       *group,
   if (entry->arg_description)
     g_string_append_printf (str, "=%s", TRANSLATE (group, entry->arg_description));
 
+  if (entry->flags & G_OPTION_FLAG_DEPRECATED)
+    {
+      const char *deprecated = _("deprecated");
+      g_string_append_printf (str, " (%s)", deprecated);
+    }
+
   g_string_append_printf (string, "%s%*s %s\n", str->str,
                           (int) (max_length + 4 - _g_utf8_strwidth (str->str)), "",
                           entry->description ? TRANSLATE (group, entry->description) : "");
+
   g_string_free (str, TRUE);
 }
 

glib/goption.h

@@ -55,32 +55,51 @@ typedef struct _GOptionEntry   GOptionEntry;
 
 /**
  * GOptionFlags:
- * @G_OPTION_FLAG_NONE: No flags. Since: 2.42.
  * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in `--help` output.
  * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
- *     `--help` output, even if it is defined in a group.
+ *   `--help` output, even if it is defined in a group.
  * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this
- *     flag indicates that the sense of the option is reversed. i.e. %FALSE will
+ *   flag indicates that the sense of the option is reversed. i.e. %FALSE will
- *     be stored into the argument rather than %TRUE.
+ *   be stored into the argument rather than %TRUE.
  * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind,
- *     this flag indicates that the callback does not take any argument
+ *   this flag indicates that the callback does not take any argument
- *     (like a %G_OPTION_ARG_NONE option). Since 2.8
+ *   (like a %G_OPTION_ARG_NONE option). Since 2.8
  * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK
- *     kind, this flag indicates that the argument should be passed to the
+ *   kind, this flag indicates that the argument should be passed to the
- *     callback in the GLib filename encoding rather than UTF-8. Since 2.8
+ *   callback in the GLib filename encoding rather than UTF-8. Since 2.8
  * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK 
- *     kind, this flag indicates that the argument supply is optional.
+ *   kind, this flag indicates that the argument supply is optional.
- *     If no argument is given then data of %GOptionParseFunc will be
+ *   If no argument is given then data of %GOptionParseFunc will be
- *     set to NULL. Since 2.8
+ *   set to NULL. Since 2.8
  * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict
- *     resolution which prefixes long option names with `groupname-` if 
+ *   resolution which prefixes long option names with `groupname-` if 
- *     there is a conflict. This option should only be used in situations
+ *   there is a conflict. This option should only be used in situations
- *     where aliasing is necessary to model some legacy commandline interface.
+ *   where aliasing is necessary to model some legacy commandline interface.
- *     It is not safe to use this option, unless all option groups are under
+ *   It is not safe to use this option, unless all option groups are under
- *     your direct control. Since 2.8.
+ *   your direct control. Since 2.8.
  *
  * Flags which modify individual options.
  */
+
+/**
+ * G_OPTION_FLAG_NONE:
+ *
+ * No flags.
+ *
+ * Since: 2.42
+ */
+
+/**
+ * G_OPTION_FLAG_DEPRECATED:
+ *
+ * This flag marks the option as deprecated in the `--help`.
+ *
+ * You should update the description of the option to describe what
+ * the user should do in response to the deprecation, for instance:
+ * remove the option, or replace it with another one.
+ *
+ * Since: 2.84
+ */
 typedef enum
 {
   G_OPTION_FLAG_NONE            = 0,
@@ -90,7 +109,8 @@ typedef enum
   G_OPTION_FLAG_NO_ARG		= 1 << 3,
   G_OPTION_FLAG_FILENAME	= 1 << 4,
   G_OPTION_FLAG_OPTIONAL_ARG    = 1 << 5,
-  G_OPTION_FLAG_NOALIAS	        = 1 << 6
+  G_OPTION_FLAG_NOALIAS	        = 1 << 6,
+  G_OPTION_FLAG_DEPRECATED GLIB_AVAILABLE_ENUMERATOR_IN_2_84 = 1 << 7
 } GOptionFlags;
 
 /**
@@ -98,21 +118,21 @@ typedef enum
  * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags or booleans.
  * @G_OPTION_ARG_STRING: The option takes a UTF-8 string argument.
  * @G_OPTION_ARG_INT: The option takes an integer argument.
- * @G_OPTION_ARG_CALLBACK: The option provides a callback (of type
+ * @G_OPTION_ARG_CALLBACK: The option provides a callback (of type #GOptionArgFunc)
- *     #GOptionArgFunc) to parse the extra argument.
+ *   to parse the extra argument.
  * @G_OPTION_ARG_FILENAME: The option takes a filename as argument, which will
-       be in the GLib filename encoding rather than UTF-8.
+     be in the GLib filename encoding rather than UTF-8.
  * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
- *     uses of the option are collected into an array of strings.
+ *   uses of the option are collected into an array of strings.
  * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, 
- *     multiple uses of the option are collected into an array of strings.
+ *   multiple uses of the option are collected into an array of strings.
  * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument
- *     can be formatted either for the user's locale or for the "C" locale.
+ *   can be formatted either for the user's locale or for the "C" locale.
- *     Since 2.12
+ *   Since 2.12
  * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like
- *     %G_OPTION_ARG_INT but for larger numbers. The number can be in
+ *   %G_OPTION_ARG_INT but for larger numbers. The number can be in
- *     decimal base, or in hexadecimal (when prefixed with `0x`, for
+ *   decimal base, or in hexadecimal (when prefixed with `0x`, for
- *     example, `0xffffffff`). Since 2.12
+ *   example, `0xffffffff`). Since 2.12
  * 
  * The #GOptionArg enum values determine which type of extra argument the
  * options expect to find. If an option expects an extra argument, it can

glib/tests/option-context.c

@@ -2211,6 +2211,31 @@ test_help_no_help_options (void)
   g_option_context_free (context);
 }
 
+static void
+test_help_deprecated (void)
+{
+  GOptionContext *context;
+  gchar *str;
+  gchar *arg = NULL;
+  GOptionEntry entries[] = {
+    { "test", 't', G_OPTION_FLAG_DEPRECATED, G_OPTION_ARG_STRING, &arg, "Test tests", "Argument to use in test" },
+    { "test2", 0, 0, G_OPTION_ARG_NONE, NULL, "Tests also", NULL },
+    G_OPTION_ENTRY_NULL
+  };
+
+  context = g_option_context_new ("blabla");
+  g_option_context_add_main_entries (context, entries, NULL);
+  g_option_context_set_summary (context, "Summary");
+  g_option_context_set_description (context, "Description");
+
+  str = g_option_context_get_help (context, FALSE, NULL);
+  g_test_message ("%s", str);
+  g_assert (strstr (str, "(deprecated)") != NULL);
+  g_free (str);
+
+  g_option_context_free (context);
+}
+
 static void
 set_bool (gpointer data)
 {
@@ -2608,6 +2633,7 @@ main (int   argc,
   g_test_add_func ("/option/help/options", test_help);
   g_test_add_func ("/option/help/no-options", test_help_no_options);
   g_test_add_func ("/option/help/no-help-options", test_help_no_help_options);
+  g_test_add_func ("/option/help/deprecated", test_help_deprecated);
 
   g_test_add_func ("/option/basic", test_basic);
   g_test_add_func ("/option/translate", test_translate);