introspection: Add more filename type annotations for strings which can contain filenames

This continues the changes done in https://bugzilla.gnome.org/show_bug.cgi?id=767245

This makes it possible to pass Python path types as process arguments and env vars
in PyGObject and and makes it clear that the values are not strictly utf-8 and need
to be validated/converted first.

https://bugzilla.gnome.org/show_bug.cgi?id=788863

gio/gappinfo.c

@@ -987,8 +987,8 @@ g_app_launch_context_init (GAppLaunchContext *context)
 /**
  * g_app_launch_context_setenv:
  * @context: a #GAppLaunchContext
- * @variable: the environment variable to set
+ * @variable: (type filename): the environment variable to set
- * @value: the value for to set the variable to.
+ * @value: (type filename): the value for to set the variable to.
  *
  * Arranges for @variable to be set to @value in the child's
  * environment when @context is used to launch an application.
@@ -1010,7 +1010,7 @@ g_app_launch_context_setenv (GAppLaunchContext *context,
 /**
  * g_app_launch_context_unsetenv:
  * @context: a #GAppLaunchContext
- * @variable: the environment variable to remove
+ * @variable: (type filename): the environment variable to remove
  *
  * Arranges for @variable to be unset in the child's environment
  * when @context is used to launch an application.
@@ -1037,8 +1037,8 @@ g_app_launch_context_unsetenv (GAppLaunchContext *context,
  * This is a %NULL-terminated array of strings, where each string has
  * the form `KEY=VALUE`.
  *
- * Returns: (array zero-terminated=1) (transfer full): the
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
- *     child's environment
+ *     the child's environment
  *
  * Since: 2.32
  */

gio/gapplication.c

@@ -2218,7 +2218,8 @@ g_application_open (GApplication  *application,
  * g_application_run:
  * @application: a #GApplication
  * @argc: the argc from main() (or 0 if @argv is %NULL)
- * @argv: (array length=argc) (nullable): the argv from main(), or %NULL
+ * @argv: (array length=argc) (element-type filename) (nullable):
+ *     the argv from main(), or %NULL
  *
  * Runs the application.
  *

gio/gapplicationcommandline.c

@@ -463,8 +463,8 @@ g_application_command_line_class_init (GApplicationCommandLineClass *class)
  * The return value is %NULL-terminated and should be freed using
  * g_strfreev().
  *
- * Returns: (array length=argc) (transfer full): the string array
+ * Returns: (array length=argc) (element-type filename) (transfer full)
- * containing the arguments (the argv)
+ *      the string array containing the arguments (the argv)
  *
  * Since: 2.28
  **/
@@ -582,8 +582,8 @@ g_application_command_line_get_cwd (GApplicationCommandLine *cmdline)
  * See g_application_command_line_getenv() if you are only interested
  * in the value of a single environment variable.
  *
- * Returns: (array zero-terminated=1) (transfer none): the environment
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
- * strings, or %NULL if they were not sent
+ *     the environment strings, or %NULL if they were not sent
  *
  * Since: 2.28
  **/
@@ -596,7 +596,7 @@ g_application_command_line_get_environ (GApplicationCommandLine *cmdline)
 /**
  * g_application_command_line_getenv:
  * @cmdline: a #GApplicationCommandLine
- * @name: the environment variable to get
+ * @name: (type filename): the environment variable to get
  *
  * Gets the value of a particular environment variable of the command
  * line invocation, as would be returned by g_getenv().  The strings may
@@ -805,7 +805,7 @@ g_application_command_line_get_platform_data (GApplicationCommandLine *cmdline)
 /**
  * g_application_command_line_create_file_for_arg:
  * @cmdline: a #GApplicationCommandLine
- * @arg: an argument from @cmdline
+ * @arg: (type filename): an argument from @cmdline
  *
  * Creates a #GFile corresponding to a filename that was given as part
  * of the invocation of @cmdline.

gio/gdesktopappinfo.c

@@ -3706,7 +3706,7 @@ g_desktop_app_info_delete (GAppInfo *appinfo)
 /* Create for commandline {{{2 */
 /**
  * g_app_info_create_from_commandline:
- * @commandline: the commandline to use
+ * @commandline: (type filename): the commandline to use
  * @application_name: (nullable): the application name, or %NULL to use @commandline
  * @flags: flags that can specify details of the created #GAppInfo
  * @error: a #GError location to store the error occurring, %NULL to ignore.

gio/gfile.c

@@ -6498,7 +6498,7 @@ new_for_cmdline_arg (const gchar *arg,
 
 /**
  * g_file_new_for_commandline_arg:
- * @arg: a command line string
+ * @arg: (type filename): a command line string
  *
  * Creates a #GFile with the given argument from the command line.
  * The value of @arg can be either a URI, an absolute path or a
@@ -6528,7 +6528,7 @@ g_file_new_for_commandline_arg (const char *arg)
 
 /**
  * g_file_new_for_commandline_arg_and_cwd:
- * @arg: a command line string
+ * @arg: (type filename): a command line string
  * @cwd: (type filename): the current working directory of the commandline
  *
  * Creates a #GFile with the given argument from the command line.

gio/gsubprocess.c

@@ -717,7 +717,7 @@ g_subprocess_new (GSubprocessFlags   flags,
 
 /**
  * g_subprocess_newv: (rename-to g_subprocess_new)
- * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess
+ * @argv: (array zero-terminated=1) (element-type filename): commandline arguments for the subprocess
  * @flags: flags that define the behaviour of the subprocess
  * @error: (nullable): return location for an error, or %NULL
  *

gio/gsubprocesslauncher.c

@@ -228,7 +228,8 @@ g_subprocess_launcher_new (GSubprocessFlags flags)
 /**
  * g_subprocess_launcher_set_environ:
  * @self: a #GSubprocess
- * @env: (array zero-terminated=1) (transfer none): the replacement environment
+ * @env: (array zero-terminated=1) (element-type filename) (transfer none):
+ *     the replacement environment
  *
  * Replace the entire environment of processes launched from this
  * launcher with the given 'environ' variable.
@@ -266,8 +267,9 @@ g_subprocess_launcher_set_environ (GSubprocessLauncher  *self,
 /**
  * g_subprocess_launcher_setenv:
  * @self: a #GSubprocess
- * @variable: the environment variable to set, must not contain '='
+ * @variable: (type filename): the environment variable to set,
- * @value: the new value for the variable
+ *     must not contain '='
+ * @value: (type filename): the new value for the variable
  * @overwrite: whether to change the variable if it already exists
  *
  * Sets the environment variable @variable in the environment of
@@ -291,7 +293,8 @@ g_subprocess_launcher_setenv (GSubprocessLauncher *self,
 /**
  * g_subprocess_launcher_unsetenv:
  * @self: a #GSubprocess
- * @variable: the environment variable to unset, must not contain '='
+ * @variable: (type filename): the environment variable to unset,
+ *     must not contain '='
  *
  * Removes the environment variable @variable from the environment of
  * processes launched from this launcher.
@@ -311,7 +314,7 @@ g_subprocess_launcher_unsetenv (GSubprocessLauncher *self,
 /**
  * g_subprocess_launcher_getenv:
  * @self: a #GSubprocess
- * @variable: the environment variable to get
+ * @variable: (type filename): the environment variable to get
  *
  * Returns the value of the environment variable @variable in the
  * environment of processes launched from this launcher.
@@ -319,7 +322,8 @@ g_subprocess_launcher_unsetenv (GSubprocessLauncher *self,
  * On UNIX, the returned string can be an arbitrary byte string.
  * On Windows, it will be UTF-8.
  *
- * Returns: the value of the environment variable, %NULL if unset
+ * Returns: (type filename): the value of the environment variable,
+ *     %NULL if unset
  *
  * Since: 2.40
  **/
@@ -724,7 +728,7 @@ g_subprocess_launcher_spawn (GSubprocessLauncher  *launcher,
 /**
  * g_subprocess_launcher_spawnv:
  * @self: a #GSubprocessLauncher
- * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments
+ * @argv: (array zero-terminated=1) (element-type filename): Command line arguments
  * @error: Error
  *
  * Creates a #GSubprocess given a provided array of arguments.

glib/genviron.c

@@ -67,15 +67,15 @@ g_environ_find (gchar       **envp,
 
 /**
  * g_environ_getenv:
- * @envp: (nullable) (array zero-terminated=1) (transfer none): an environment
+ * @envp: (nullable) (array zero-terminated=1) (transfer none) (element-type filename):
- *     list (eg, as returned from g_get_environ()), or %NULL
+ *     an environment list (eg, as returned from g_get_environ()), or %NULL
  *     for an empty environment list
- * @variable: the environment variable to get
+ * @variable: (type filename): the environment variable to get
  *
  * Returns the value of the environment variable @variable in the
  * provided list @envp.
  *
- * Returns: the value of the environment variable, or %NULL if
+ * Returns: (type filename): the value of the environment variable, or %NULL if
  *     the environment variable is not set in @envp. The returned
  *     string is owned by @envp, and will be freed if @variable is
  *     set or unset again.
@@ -99,19 +99,20 @@ g_environ_getenv (gchar       **envp,
 
 /**
  * g_environ_setenv:
- * @envp: (nullable) (array zero-terminated=1) (transfer full): an
+ * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full):
- *     environment list that can be freed using g_strfreev() (e.g., as
+ *     an environment list that can be freed using g_strfreev() (e.g., as
  *     returned from g_get_environ()), or %NULL for an empty
  *     environment list
- * @variable: the environment variable to set, must not contain '='
+ * @variable: (type filename): the environment variable to set, must not
- * @value: the value for to set the variable to
+ *     contain '='
+ * @value: (type filename): the value for to set the variable to
  * @overwrite: whether to change the variable if it already exists
  *
  * Sets the environment variable @variable in the provided list
  * @envp to @value.
  *
- * Returns: (array zero-terminated=1) (transfer full): the
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
- *     updated environment list. Free it using g_strfreev().
+ *     the updated environment list. Free it using g_strfreev().
  *
  * Since: 2.32
  */
@@ -186,16 +187,17 @@ g_environ_unsetenv_internal (gchar        **envp,
 
 /**
  * g_environ_unsetenv:
- * @envp: (nullable) (array zero-terminated=1) (transfer full): an environment
+ * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full):
- *     list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), 
+ *     an environment list that can be freed using g_strfreev() (e.g., as
- *     or %NULL for an empty environment list
+ *     returned from g_get_environ()), or %NULL for an empty environment list
- * @variable: the environment variable to remove, must not contain '='
+ * @variable: (type filename): the environment variable to remove, must not
+ *     contain '='
  *
  * Removes the environment variable @variable from the provided
  * environment @envp.
  *
- * Returns: (array zero-terminated=1) (transfer full): the
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
- *     updated environment list. Free it using g_strfreev().
+ *     the updated environment list. Free it using g_strfreev().
  *
  * Since: 2.32
  */
@@ -217,7 +219,7 @@ g_environ_unsetenv (gchar       **envp,
 
 /**
  * g_getenv:
- * @variable: the environment variable to get
+ * @variable: (type filename): the environment variable to get
  *
  * Returns the value of an environment variable.
  *
@@ -227,7 +229,7 @@ g_environ_unsetenv (gchar       **envp,
  * On Windows, in case the environment variable's value contains
  * references to other environment variables, they are expanded.
  *
- * Returns: the value of the environment variable, or %NULL if
+ * Returns: (type filename): the value of the environment variable, or %NULL if
  *     the environment variable is not found. The returned string
  *     may be overwritten by the next call to g_getenv(), g_setenv()
  *     or g_unsetenv().
@@ -242,8 +244,9 @@ g_getenv (const gchar *variable)
 
 /**
  * g_setenv:
- * @variable: the environment variable to set, must not contain '='.
+ * @variable: (type filename): the environment variable to set, must not
- * @value: the value for to set the variable to.
+ *     contain '='.
+ * @value: (type filename): the value for to set the variable to.
  * @overwrite: whether to change the variable if it already exists.
  *
  * Sets an environment variable. On UNIX, both the variable's name and
@@ -311,7 +314,8 @@ extern char **environ;
 
 /**
  * g_unsetenv:
- * @variable: the environment variable to remove, must not contain '='
+ * @variable: (type filename): the environment variable to remove, must
+ *     not contain '='
  *
  * Removes an environment variable from the environment.
  *
@@ -361,8 +365,9 @@ g_unsetenv (const gchar *variable)
  * use cases for environment variables in GLib-using programs you want
  * the UTF-8 encoding that this function and g_getenv() provide.
  *
- * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
- *     list of strings which must be freed with g_strfreev().
+ *     a %NULL-terminated list of strings which must be freed with
+ *     g_strfreev().
  *
  * Since: 2.8
  */
@@ -402,8 +407,8 @@ g_listenv (void)
  * The return value is freshly allocated and it should be freed with
  * g_strfreev() when it is no longer needed.
  *
- * Returns: (array zero-terminated=1) (transfer full): the list of
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
- *     environment variables
+ *     the list of environment variables
  *
  * Since: 2.28
  */

glib/gshell.c

@@ -188,7 +188,7 @@ unquote_string_inplace (gchar* str, gchar** end, GError** err)
 
 /**
  * g_shell_quote:
- * @unquoted_string: a literal string
+ * @unquoted_string: (type filename): a literal string
  * 
  * Quotes a string so that the shell (/bin/sh) will interpret the
  * quoted string to mean @unquoted_string. If you pass a filename to
@@ -197,7 +197,7 @@ unquote_string_inplace (gchar* str, gchar** end, GError** err)
  * quoting style used is undefined (single or double quotes may be
  * used).
  * 
- * Returns: quoted string
+ * Returns: (type filename): quoted string
  **/
 gchar*
 g_shell_quote (const gchar *unquoted_string)
@@ -238,7 +238,7 @@ g_shell_quote (const gchar *unquoted_string)
 
 /**
  * g_shell_unquote:
- * @quoted_string: shell-quoted string
+ * @quoted_string: (type filename): shell-quoted string
  * @error: error return location or NULL
  * 
  * Unquotes a string as the shell (/bin/sh) would. Only handles
@@ -263,7 +263,7 @@ g_shell_quote (const gchar *unquoted_string)
  * be escaped with backslash. Otherwise double quotes preserve things
  * literally.
  *
- * Returns: an unquoted string
+ * Returns: (type filename): an unquoted string
  **/
 gchar*
 g_shell_unquote (const gchar *quoted_string,
@@ -616,10 +616,10 @@ tokenize_command_line (const gchar *command_line,
 
 /**
  * g_shell_parse_argv:
- * @command_line: command line to parse
+ * @command_line: (type filename): command line to parse
  * @argcp: (out) (optional): return location for number of args
- * @argvp: (out) (optional) (array length=argcp zero-terminated=1): return
+ * @argvp: (out) (optional) (array length=argcp zero-terminated=1) (element-type filename):
- *   location for array of args
+ *   return location for array of args
  * @error: (optional): return location for error
  * 
  * Parses a command line into an argument vector, in much the same way

glib/gspawn.c

@@ -146,9 +146,12 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
 
 /**
  * g_spawn_async:
- * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's
+ * @working_directory: (type filename) (nullable): child's current working
- * @argv: (array zero-terminated=1): child's argument vector
+ *     directory, or %NULL to inherit parent's
- * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's
+ * @argv: (array zero-terminated=1) (element-type filename):
+ *     child's argument vector
+ * @envp: (array zero-terminated=1) (element-type filename) (nullable):
+ *     child's environment, or %NULL to inherit parent's
  * @flags: flags from #GSpawnFlags
  * @child_setup: (scope async) (nullable): function to run in the child just before exec()
  * @user_data: (closure): user data for @child_setup
@@ -256,9 +259,12 @@ read_data (GString *str,
 
 /**
  * g_spawn_sync:
- * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's
+ * @working_directory: (type filename) (nullable): child's current working
- * @argv: (array zero-terminated=1): child's argument vector
+ *     directory, or %NULL to inherit parent's
- * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's
+ * @argv: (array zero-terminated=1) (element-type filename):
+ *     child's argument vector
+ * @envp: (array zero-terminated=1) (element-type filename) (nullable):
+ *     child's environment, or %NULL to inherit parent's
  * @flags: flags from #GSpawnFlags
  * @child_setup: (scope async) (nullable): function to run in the child just before exec()
  * @user_data: (closure): user data for @child_setup
@@ -509,9 +515,13 @@ g_spawn_sync (const gchar          *working_directory,
 
 /**
  * g_spawn_async_with_pipes:
- * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
+ * @working_directory: (type filename) (nullable): child's current working
- * @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding
+ *     directory, or %NULL to inherit parent's, in the GLib file name encoding
- * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
+ * @argv: (array zero-terminated=1) (element-type filename): child's argument
+ *     vector, in the GLib file name encoding
+ * @envp: (array zero-terminated=1) (element-type filename) (nullable):
+ *     child's environment, or %NULL to inherit parent's, in the GLib file
+ *     name encoding
  * @flags: flags from #GSpawnFlags
  * @child_setup: (scope async) (nullable): function to run in the child just before exec()
  * @user_data: (closure): user data for @child_setup
@@ -719,7 +729,7 @@ g_spawn_async_with_pipes (const gchar          *working_directory,
 
 /**
  * g_spawn_command_line_sync:
- * @command_line: a command line 
+ * @command_line: (type filename): a command line
  * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output
  * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child errors
  * @exit_status: (out) (optional): return location for child exit status, as returned by waitpid()
@@ -784,7 +794,7 @@ g_spawn_command_line_sync (const gchar  *command_line,
 
 /**
  * g_spawn_command_line_async:
- * @command_line: a command line
+ * @command_line: (type filename): a command line
  * @error: return location for errors
  * 
  * A simple version of g_spawn_async() that parses a command line with