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,7 +55,6 @@ 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.
@@ -81,6 +80,26 @@ typedef struct _GOptionEntry   GOptionEntry;
  *
  * 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,8 +118,8 @@ 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.
  * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple

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