glib: Add filename type annotations

Adds the filename annotation for all file names
and things which can contain file names like
environment variables, argv-

On Unix they can contain anything while on Windows
they are always utf-8.

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

12 files changed, 157 insertions, 111 deletions

diff --git a/glib/gbookmarkfile.c b/glib/gbookmarkfile.c
index 3123669cb..2fd4ee383 100644
--- a/glib/gbookmarkfile.c
+++ b/glib/gbookmarkfile.c
@@ -1657,7 +1657,8 @@ g_bookmark_file_load_from_data (GBookmarkFile  *bookmark,
 /**
  * g_bookmark_file_load_from_file:
  * @bookmark: an empty #GBookmarkFile struct
- * @filename: the path of a filename to load, in the GLib file name encoding
+ * @filename: (type filename): the path of a filename to load, in the
+ *     GLib file name encoding
  * @error: return location for a #GError, or %NULL
  *
  * Loads a desktop bookmark file into an empty #GBookmarkFile structure.
@@ -1765,9 +1766,9 @@ find_file_in_data_dirs (const gchar   *file,
 /**
  * g_bookmark_file_load_from_data_dirs:
  * @bookmark: a #GBookmarkFile
- * @file: a relative path to a filename to open and parse
- * @full_path: (allow-none): return location for a string containing the full path
- *   of the file, or %NULL
+ * @file: (type filename): a relative path to a filename to open and parse
+ * @full_path: (type filename) (allow-none): return location for a string
+ *    containing the full path of the file, or %NULL
  * @error: return location for a #GError, or %NULL
  *
  * This function looks for a desktop bookmark file named @file in the
@@ -1881,7 +1882,7 @@ g_bookmark_file_to_data (GBookmarkFile  *bookmark,
 /**
  * g_bookmark_file_to_file:
  * @bookmark: a #GBookmarkFile
- * @filename: path of the output file
+ * @filename: (type filename): path of the output file
  * @error: return location for a #GError, or %NULL
  *
  * This function outputs @bookmark into a file.  The write process is
diff --git a/glib/gconvert.c b/glib/gconvert.c
index a6e28a34e..3deac7873 100644
--- a/glib/gconvert.c
+++ b/glib/gconvert.c
@@ -1114,7 +1114,7 @@ get_filename_charset (const gchar **filename_charset)
 
 /**
  * g_filename_to_utf8:
- * @opsysstring:   a string in the encoding for filenames
+ * @opsysstring: (type filename): a string in the encoding for filenames
  * @len:           the length of the string, or -1 if the string is
  *                 nul-terminated (Note that some encodings may allow nul
  *                 bytes to occur inside strings. In that case, using -1
@@ -1689,9 +1689,9 @@ g_filename_from_uri (const gchar *uri,
 
 /**
  * g_filename_to_uri:
- * @filename: an absolute filename specified in the GLib file name encoding,
- *            which is the on-disk file name bytes on Unix, and UTF-8 on 
- *            Windows
+ * @filename: (type filename): an absolute filename specified in the GLib file
+ *     name encoding, which is the on-disk file name bytes on Unix, and UTF-8
+ *     on Windows
  * @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none.
  * @error: location to store the error occurring, or %NULL to ignore
  *         errors. Any of the errors in #GConvertError may occur.
@@ -1839,7 +1839,8 @@ g_uri_list_extract_uris (const gchar *uri_list)
 
 /**
  * g_filename_display_basename:
- * @filename: an absolute pathname in the GLib file name encoding
+ * @filename: (type filename): an absolute pathname in the
+ *     GLib file name encoding
  *
  * Returns the display basename for the particular filename, guaranteed
  * to be valid UTF-8. The display name might not be identical to the filename,
@@ -1879,7 +1880,8 @@ g_filename_display_basename (const gchar *filename)
 
 /**
  * g_filename_display_name:
- * @filename: a pathname hopefully in the GLib file name encoding
+ * @filename: (type filename): a pathname hopefully in the
+ *     GLib file name encoding
  * 
  * Converts a filename into a valid UTF-8 string. The conversion is 
  * not necessarily reversible, so you should keep the original around 
diff --git a/glib/gdir.c b/glib/gdir.c
index e6cf5e634..208a92c5e 100644
--- a/glib/gdir.c
+++ b/glib/gdir.c
@@ -241,7 +241,7 @@ g_dir_new_from_dirp (gpointer dirp)
  * On Windows, as is true of all GLib functions which operate on
  * filenames, the returned name is in UTF-8.
  *
- * Returns: The entry's name or %NULL if there are no
+ * Returns: (type filename): The entry's name or %NULL if there are no
  *   more entries. The return value is owned by GLib and
  *   must not be modified or freed.
  **/
diff --git a/glib/genviron.c b/glib/genviron.c
index 8c64cdaf8..d4aa1df68 100644
--- a/glib/genviron.c
+++ b/glib/genviron.c
@@ -67,15 +67,15 @@ g_environ_find (gchar       **envp,
 
 /**
  * g_environ_getenv:
- * @envp: (allow-none) (array zero-terminated=1) (transfer none): an environment
- *     list (eg, as returned from g_get_environ()), or %NULL
+ * @envp: (allow-none) (array zero-terminated=1) (transfer none) (element-type filename):
+ *     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: (allow-none) (array zero-terminated=1) (transfer full): an
- *     environment list that can be freed using g_strfreev() (e.g., as
+ * @envp: (allow-none) (array zero-terminated=1) (element-type filename) (transfer full):
+ *     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 '='
- * @value: the value for to set the variable to
+ * @variable: (type filename): the environment variable to set, must not
+ *     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
- *     updated environment list. Free it using g_strfreev().
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     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: (allow-none) (array zero-terminated=1) (transfer full): 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 remove, must not contain '='
+ * @envp: (allow-none) (array zero-terminated=1) (element-type filename) (transfer full):
+ *     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: (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
- *     updated environment list. Free it using g_strfreev().
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     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 '='.
- * @value: the value for to set the variable to.
+ * @variable: (type filename): the environment variable to set, must not
+ *     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
- *     list of strings which must be freed with g_strfreev().
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     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
- *     environment variables
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     the list of environment variables
  *
  * Since: 2.28
  */
diff --git a/glib/gfileutils.c b/glib/gfileutils.c
index 31a84cf11..dc1513fc3 100644
--- a/glib/gfileutils.c
+++ b/glib/gfileutils.c
@@ -194,7 +194,7 @@
 
 /**
  * g_mkdir_with_parents:
- * @pathname: a pathname in the GLib file name encoding
+ * @pathname: (type filename): a pathname in the GLib file name encoding
  * @mode: permissions to use for newly created directories
  *
  * Create a directory if it doesn't already exist. Create intermediate
@@ -266,7 +266,8 @@ g_mkdir_with_parents (const gchar *pathname,
 
 /**
  * g_file_test:
- * @filename: a filename to test in the GLib file name encoding
+ * @filename: (type filename): a filename to test in the
+ *     GLib file name encoding
  * @test: bitfield of #GFileTest flags
  * 
  * Returns %TRUE if any of the tests in the bitfield @test are
@@ -1365,7 +1366,7 @@ wrap_g_open (const gchar *filename,
  * in the GLib file name encoding. Most importantly, on Windows it
  * should be in UTF-8.
  *
- * Returns: A pointer to @tmpl, which has been modified
+ * Returns: (type filename): A pointer to @tmpl, which has been modified
  *     to hold the directory name. In case of errors, %NULL is
  *     returned, and %errno will be set.
  *
@@ -1397,7 +1398,7 @@ g_mkdtemp_full (gchar *tmpl,
  * The string should be in the GLib file name encoding. Most importantly,
  * on Windows it should be in UTF-8.
  *
- * Returns: A pointer to @tmpl, which has been modified
+ * Returns: (type filename): A pointer to @tmpl, which has been modified
  *     to hold the directory name.  In case of errors, %NULL is
  *     returned and %errno will be set.
  *
@@ -1745,13 +1746,15 @@ g_build_path_va (const gchar  *separator,
 /**
  * g_build_pathv:
  * @separator: a string used to separator the elements of the path.
- * @args: (array zero-terminated=1): %NULL-terminated array of strings containing the path elements.
+ * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
+ *     array of strings containing the path elements.
  * 
  * Behaves exactly like g_build_path(), but takes the path elements 
  * as a string array, instead of varargs. This function is mainly
  * meant for language bindings.
  *
- * Returns: a newly-allocated string that must be freed with g_free().
+ * Returns: (type filename): a newly-allocated string that must be freed
+ *     with g_free().
  *
  * Since: 2.8
  */
@@ -1936,13 +1939,15 @@ g_build_pathname_va (const gchar  *first_element,
 
 /**
  * g_build_filenamev:
- * @args: (array zero-terminated=1): %NULL-terminated array of strings containing the path elements.
+ * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
+ *     array of strings containing the path elements.
  * 
  * Behaves exactly like g_build_filename(), but takes the path elements 
  * as a string array, instead of varargs. This function is mainly
  * meant for language bindings.
  *
- * Returns: a newly-allocated string that must be freed with g_free().
+ * Returns: (type filename): a newly-allocated string that must be freed
+ *     with g_free().
  * 
  * Since: 2.8
  */
@@ -2003,15 +2008,15 @@ g_build_filename (const gchar *first_element,
 
 /**
  * g_file_read_link:
- * @filename: the symbolic link
+ * @filename: (type filename): the symbolic link
  * @error: return location for a #GError
  *
  * Reads the contents of the symbolic link @filename like the POSIX
  * readlink() function.  The returned string is in the encoding used
  * for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
  *
- * Returns: A newly-allocated string with the contents of the symbolic link, 
- *          or %NULL if an error occurred.
+ * Returns: (type filename): A newly-allocated string with the contents of
+ *     the symbolic link, or %NULL if an error occurred.
  *
  * Since: 2.4
  */
@@ -2062,7 +2067,7 @@ g_file_read_link (const gchar  *filename,
 
 /**
  * g_path_is_absolute:
- * @file_name: a file name
+ * @file_name: (type filename): a file name
  *
  * Returns %TRUE if the given @file_name is an absolute file name.
  * Note that this is a somewhat vague concept on Windows.
@@ -2111,13 +2116,14 @@ g_path_is_absolute (const gchar *file_name)
 
 /**
  * g_path_skip_root:
- * @file_name: a file name
+ * @file_name: (type filename): a file name
  *
  * Returns a pointer into @file_name after the root component,
  * i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name
  * is not an absolute path it returns %NULL.
  *
- * Returns: (nullable): a pointer into @file_name after the root component
+ * Returns: (type filename) (nullable): a pointer into @file_name after the
+ *     root component
  */
 const gchar *
 g_path_skip_root (const gchar *file_name)
@@ -2181,13 +2187,13 @@ g_path_skip_root (const gchar *file_name)
 
 /**
  * g_basename:
- * @file_name: the name of the file
+ * @file_name: (type filename): the name of the file
  *
  * Gets the name of the file without any leading directory
  * components. It returns a pointer into the given file name
  * string.
  *
- * Returns: the name of the file without any leading
+ * Returns: (type filename): the name of the file without any leading
  *     directory components
  *
  * Deprecated:2.2: Use g_path_get_basename() instead, but notice
@@ -2226,7 +2232,7 @@ g_basename (const gchar *file_name)
 
 /**
  * g_path_get_basename:
- * @file_name: the name of the file
+ * @file_name: (type filename): the name of the file
  *
  * Gets the last component of the filename.
  *
@@ -2235,7 +2241,7 @@ g_basename (const gchar *file_name)
  * separators (and on Windows, possibly a drive letter), a single
  * separator is returned. If @file_name is empty, it gets ".".
  *
- * Returns: a newly allocated string containing the last
+ * Returns: (type filename): a newly allocated string containing the last
  *    component of the filename
  */
 gchar *
@@ -2303,14 +2309,14 @@ g_path_get_basename (const gchar *file_name)
 
 /**
  * g_path_get_dirname:
- * @file_name: the name of the file
+ * @file_name: (type filename): the name of the file
  *
  * Gets the directory components of a file name.
  *
  * If the file name has no directory components "." is returned.
  * The returned string should be freed when no longer needed.
  *
- * Returns: the directory components of the file
+ * Returns: (type filename): the directory components of the file
  */
 gchar *
 g_path_get_dirname (const gchar *file_name)
@@ -2430,7 +2436,7 @@ g_path_get_dirname (const gchar *file_name)
  * the current directory.  This can make a difference in the case that
  * the current directory is the target of a symbolic link.
  *
- * Returns: the current directory
+ * Returns: (type filename): the current directory
  */
 gchar *
 g_get_current_dir (void)
diff --git a/glib/giochannel.c b/glib/giochannel.c
index 1f0133697..8e9d22216 100644
--- a/glib/giochannel.c
+++ b/glib/giochannel.c
@@ -421,7 +421,7 @@ g_io_channel_seek (GIOChannel *channel,
 
 /**
  * g_io_channel_new_file:
- * @filename: A string containing the name of a file
+ * @filename: (type filename): A string containing the name of a file
  * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
  *        the same meaning as in fopen()
  * @error: A location to return an error of type %G_FILE_ERROR
diff --git a/glib/gmappedfile.c b/glib/gmappedfile.c
index 7c8702d2f..9886cceb7 100644
--- a/glib/gmappedfile.c
+++ b/glib/gmappedfile.c
@@ -212,7 +212,8 @@ mapped_file_new_from_fd (int           fd,
 
 /**
  * g_mapped_file_new:
- * @filename: The path of the file to load, in the GLib filename encoding
+ * @filename: (type filename): The path of the file to load, in the GLib
+ *     filename encoding
  * @writable: whether the mapping should be writable
  * @error: return location for a #GError, or %NULL
  *
diff --git a/glib/gshell.c b/glib/gshell.c
index 2c50af8f3..340a285b0 100644
--- a/glib/gshell.c
+++ b/glib/gshell.c
@@ -190,7 +190,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
@@ -199,7 +199,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)
@@ -240,7 +240,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
@@ -265,7 +265,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,
@@ -618,10 +618,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
- *   location for array of args
+ * @argvp: (out) (optional) (array length=argcp zero-terminated=1) (element-type filename):
+ *   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
diff --git a/glib/gspawn.c b/glib/gspawn.c
index 5aed1a9ab..a60ee9b8e 100644
--- a/glib/gspawn.c
+++ b/glib/gspawn.c
@@ -105,9 +105,12 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
 
 /**
  * g_spawn_async:
- * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's
- * @argv: (array zero-terminated=1): child's argument vector
- * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
+ * @working_directory: (type filename) (allow-none): child's current working
+ *     directory, 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) (allow-none):
+ *     child's environment, or %NULL to inherit parent's
  * @flags: flags from #GSpawnFlags
  * @child_setup: (scope async) (allow-none): function to run in the child just before exec()
  * @user_data: (closure): user data for @child_setup
@@ -215,9 +218,12 @@ read_data (GString *str,
 
 /**
  * g_spawn_sync:
- * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's
- * @argv: (array zero-terminated=1): child's argument vector
- * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
+ * @working_directory: (type filename) (allow-none): child's current working
+ *     directory, 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) (allow-none):
+ *     child's environment, or %NULL to inherit parent's
  * @flags: flags from #GSpawnFlags
  * @child_setup: (scope async) (allow-none): function to run in the child just before exec()
  * @user_data: (closure): user data for @child_setup
@@ -467,9 +473,13 @@ g_spawn_sync (const gchar          *working_directory,
 
 /**
  * g_spawn_async_with_pipes:
- * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
- * @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding
- * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
+ * @working_directory: (type filename) (allow-none): child's current working
+ *     directory, 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) (allow-none):
+ *     child's environment, or %NULL to inherit parent's, in the GLib file
+ *     name encoding
  * @flags: flags from #GSpawnFlags
  * @child_setup: (scope async) (allow-none): function to run in the child just before exec()
  * @user_data: (closure): user data for @child_setup
@@ -676,7 +686,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) (allow-none): return location for child output
  * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child errors
  * @exit_status: (out) (allow-none): return location for child exit status, as returned by waitpid()
@@ -741,7 +751,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
diff --git a/glib/gstdio.c b/glib/gstdio.c
index 92f1ba91d..588b0758e 100644
--- a/glib/gstdio.c
+++ b/glib/gstdio.c
@@ -56,7 +56,8 @@
 
 /**
  * g_access:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @mode: as in access()
  *
  * A wrapper for the POSIX access() function. This function is used to
@@ -111,7 +112,8 @@ g_access (const gchar *filename,
 
 /**
  * g_chmod:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @mode: as in chmod()
  *
  * A wrapper for the POSIX chmod() function. The chmod() function is
@@ -157,7 +159,8 @@ g_chmod (const gchar *filename,
 }
 /**
  * g_open:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @flags: as in open()
  * @mode: as in open()
  *
@@ -220,7 +223,8 @@ g_open (const gchar *filename,
 
 /**
  * g_creat:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @mode: as in creat()
  *
  * A wrapper for the POSIX creat() function. The creat() function is
@@ -278,8 +282,9 @@ g_creat (const gchar *filename,
 
 /**
  * g_rename:
- * @oldfilename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @newfilename: a pathname in the GLib file name encoding
+ * @oldfilename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
+ * @newfilename: (type filename): a pathname in the GLib file name encoding
  *
  * A wrapper for the POSIX rename() function. The rename() function 
  * renames a file, moving it between directories if required.
@@ -350,7 +355,8 @@ g_rename (const gchar *oldfilename,
 
 /**
  * g_mkdir: 
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @mode: permissions to use for the newly created directory
  *
  * A wrapper for the POSIX mkdir() function. The mkdir() function 
@@ -393,7 +399,8 @@ g_mkdir (const gchar *filename,
 
 /**
  * g_chdir: 
- * @path: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @path: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  *
  * A wrapper for the POSIX chdir() function. The function changes the
  * current directory of the process to @path.
@@ -440,7 +447,8 @@ g_chdir (const gchar *path)
  */
 /**
  * g_stat: 
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @buf: a pointer to a stat struct, which will be filled with the file
  *     information
  *
@@ -507,7 +515,8 @@ g_stat (const gchar *filename,
 
 /**
  * g_lstat: 
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @buf: a pointer to a stat struct, which will be filled with the file
  *     information
  *
@@ -538,7 +547,8 @@ g_lstat (const gchar *filename,
 
 /**
  * g_unlink:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  *
  * A wrapper for the POSIX unlink() function. The unlink() function 
  * deletes a name from the filesystem. If this was the last link to the 
@@ -582,7 +592,8 @@ g_unlink (const gchar *filename)
 
 /**
  * g_remove:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  *
  * A wrapper for the POSIX remove() function. The remove() function
  * deletes a name from the filesystem.
@@ -636,7 +647,8 @@ g_remove (const gchar *filename)
 
 /**
  * g_rmdir:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  *
  * A wrapper for the POSIX rmdir() function. The rmdir() function
  * deletes a directory from the filesystem.
@@ -677,7 +689,8 @@ g_rmdir (const gchar *filename)
 
 /**
  * g_fopen:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @mode: a string describing the mode in which the file should be opened
  *
  * A wrapper for the stdio fopen() function. The fopen() function
@@ -737,7 +750,8 @@ g_fopen (const gchar *filename,
 
 /**
  * g_freopen:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @mode: a string describing the mode in which the file should be  opened
  * @stream: (allow-none): an existing stream which will be reused, or %NULL
  *
@@ -792,7 +806,8 @@ g_freopen (const gchar *filename,
 
 /**
  * g_utime:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ *     (UTF-8 on Windows)
  * @utb: a pointer to a struct utimbuf.
  *
  * A wrapper for the POSIX utime() function. The utime() function
diff --git a/glib/gtestutils.c b/glib/gtestutils.c
index a76760782..b272b1987 100644
--- a/glib/gtestutils.c
+++ b/glib/gtestutils.c
@@ -3447,7 +3447,7 @@ g_test_build_filename (GTestFileType  file_type,
  * This is approximately the same as calling g_test_build_filename("."),
  * but you don't need to free the return value.
  *
- * Returns: the path of the directory, owned by GLib
+ * Returns: (type filename): the path of the directory, owned by GLib
  *
  * Since: 2.38
  **/
diff --git a/glib/gutils.c b/glib/gutils.c
index 7fc3c6f62..9f7b7e3cf 100644
--- a/glib/gutils.c
+++ b/glib/gutils.c
@@ -298,7 +298,7 @@ g_find_program_in_path (const gchar *program)
 
 /**
  * g_find_program_in_path:
- * @program: a program name in the GLib file name encoding
+ * @program: (type filename): a program name in the GLib file name encoding
  * 
  * Locates the first executable named @program in the user's path, in the
  * same way that execvp() would locate it. Returns an allocated string
@@ -318,7 +318,8 @@ g_find_program_in_path (const gchar *program)
  * the program is found, the return value contains the full name
  * including the type suffix.
  *
- * Returns: a newly-allocated string with the absolute path, or %NULL
+ * Returns: (type filename): a newly-allocated string with the absolute path,
+ *     or %NULL
  **/
 #ifdef G_OS_WIN32
 static gchar *
@@ -750,7 +751,7 @@ g_get_user_database_entry (void)
  * encoding, or something else, and there is no guarantee that it is even
  * consistent on a machine. On Windows, it is always UTF-8.
  *
- * Returns: the user name of the current user.
+ * Returns: (type filename): the user name of the current user.
  */
 const gchar *
 g_get_user_name (void)
@@ -771,7 +772,7 @@ g_get_user_name (void)
  * real user name cannot be determined, the string "Unknown" is 
  * returned.
  *
- * Returns: the user's real name.
+ * Returns: (type filename): the user's real name.
  */
 const gchar *
 g_get_real_name (void)
@@ -807,7 +808,7 @@ g_get_real_name (void)
  * should either directly check the `HOME` environment variable yourself
  * or unset it before calling any functions in GLib.
  *
- * Returns: the current user's home directory
+ * Returns: (type filename): the current user's home directory
  */
 const gchar *
 g_get_home_dir (void)
@@ -903,7 +904,7 @@ g_get_home_dir (void)
  * it is always UTF-8. The return value is never %NULL or the empty
  * string.
  *
- * Returns: the directory to use for temporary files.
+ * Returns: (type filename): the directory to use for temporary files.
  */
 const gchar *
 g_get_tmp_dir (void)
@@ -1145,7 +1146,7 @@ g_set_application_name (const gchar *application_name)
  * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
  * what g_get_user_config_dir() returns.
  *
- * Returns: a string owned by GLib that must not be modified 
+ * Returns: (type filename): a string owned by GLib that must not be modified
  *               or freed.
  * Since: 2.6
  **/
@@ -1231,7 +1232,7 @@ g_init_user_config_dir (void)
  * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
  * what g_get_user_data_dir() returns.
  *
- * Returns: a string owned by GLib that must not be modified 
+ * Returns: (type filename): a string owned by GLib that must not be modified
  *               or freed.
  * Since: 2.6
  **/
@@ -1263,7 +1264,7 @@ g_get_user_config_dir (void)
  * C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
  * See documentation for CSIDL_INTERNET_CACHE.
  *
- * Returns: a string owned by GLib that must not be modified 
+ * Returns: (type filename): a string owned by GLib that must not be modified
  *               or freed.
  * Since: 2.6
  **/
@@ -1322,7 +1323,8 @@ g_get_user_cache_dir (void)
  * CSIDL_LOCAL_APPDATA.  Note that on Windows it thus is the same as
  * what g_get_user_config_dir() returns.
  *
- * Returns: a string owned by GLib that must not be modified or freed.
+ * Returns: (type filename): a string owned by GLib that must not be
+ *     modified or freed.
  *
  * Since: 2.28
  **/
@@ -1718,8 +1720,8 @@ g_reload_user_special_dirs_cache (void)
  * of the special directory without requiring the session to restart; GLib
  * will not reflect any change once the special directories are loaded.
  *
- * Returns: the path to the specified special directory, or %NULL
- *   if the logical id was not found. The returned string is owned by
+ * Returns: (type filename): the path to the specified special directory, or
+ *   %NULL if the logical id was not found. The returned string is owned by
  *   GLib and should not be modified or freed.
  *
  * Since: 2.14
@@ -1936,8 +1938,10 @@ g_win32_get_system_data_dirs_for_module (void (*address_of_function)(void))
  * Note that on Windows the returned list can vary depending on where
  * this function is called.
  *
- * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must 
- *               not be modified or freed.
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
+ *     a %NULL-terminated array of strings owned by GLib that must not be
+ *     modified or freed.
+ * 
  * Since: 2.6
  **/
 const gchar * const * 
@@ -1988,8 +1992,10 @@ g_get_system_data_dirs (void)
  * of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
  * This information will not roam and is available to anyone using the computer.
  *
- * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must 
- *               not be modified or freed.
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
+ *     a %NULL-terminated array of strings owned by GLib that must not be
+ *     modified or freed.
+ * 
  * Since: 2.6
  **/
 const gchar * const *