[glib: 5/8] gshell: Mention handling of empty argv arrays in the documentation

[Philip Withnall <pwithnall src gnome org>]

commit 18fc711355248ddf5032e9fe568870bf3e19d1b3
Author: Philip Withnall <pwithnall endlessos org>
Date:   Mon Jan 31 14:49:50 2022 +0000

    gshell: Mention handling of empty argv arrays in the documentation
    
    It is not possible for `g_shell_parse_argv()` to return an empty `argv`
    array. Make that clear in the documentation and add some assertions to
    encode it explicitly in the code.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 glib/gshell.c | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)
---
diff --git a/glib/gshell.c b/glib/gshell.c
index 33c53497a..ed893905e 100644
--- a/glib/gshell.c
+++ b/glib/gshell.c
@@ -646,6 +646,11 @@ tokenize_command_line (const gchar *command_line,
  *
  * Possible errors are those from the %G_SHELL_ERROR domain.
  *
+ * In particular, if @command_line is an empty string (or a string containing
+ * only whitespace), %G_SHELL_ERROR_EMPTY_STRING will be returned. It’s
+ * guaranteed that @argvp will be a non-empty array if this function returns
+ * successfully.
+ *
  * Free the returned vector with g_strfreev().
  * 
  * Returns: %TRUE on success, %FALSE if error set
@@ -702,7 +707,10 @@ g_shell_parse_argv (const gchar *command_line,
     }
   
   g_slist_free_full (tokens, g_free);
-  
+
+  g_assert (argc > 0);
+  g_assert (argv != NULL && argv[0] != NULL);
+
   if (argcp)
     *argcp = argc;