[glib] gio: Add filename type annotations

From: Christoph Reiter <creiter src gnome org>
To: commits-list gnome org
Cc:
Subject: [glib] gio: Add filename type annotations
Date: Sat, 4 Jun 2016 18:39:47 +0000 (UTC)
commit f8189ddf9869ed8e90f9b640d9545fe4011adb7d
Author: Christoph Reiter <reiter christoph gmail com>
Date:   Sat Jun 4 17:53:42 2016 +0200

    gio: Add filename type annotations
    
    https://bugzilla.gnome.org/show_bug.cgi?id=767245

 gio/gappinfo.c                |   17 +++++++++--------
 gio/gapplication.c            |    3 ++-
 gio/gapplicationcommandline.c |   14 +++++++-------
 gio/gdesktopappinfo.c         |    8 +++++---
 gio/gfile.c                   |   25 +++++++++++++------------
 gio/gfileinfo.c               |    4 ++--
 gio/giomodule.c               |   14 +++++++++-----
 gio/gsettingsschema.c         |    2 +-
 gio/gsubprocess.c             |    2 +-
 gio/gsubprocesslauncher.c     |   26 +++++++++++++++-----------
 gio/gtlscertificate.c         |   11 ++++++-----
 gio/gtlsfiledatabase.c        |    2 +-
 gio/gunixmounts.c             |   10 +++++-----
 13 files changed, 76 insertions(+), 62 deletions(-)
---
diff --git a/gio/gappinfo.c b/gio/gappinfo.c
index 0bbb44d..01c5d09 100644
--- a/gio/gappinfo.c
+++ b/gio/gappinfo.c
@@ -240,7 +240,7 @@ g_app_info_get_description (GAppInfo *appinfo)
  * 
  * Gets the executable's name for the installed application.
  *
- * Returns: a string containing the @appinfo's application 
+ * Returns: (type filename): a string containing the @appinfo's application
  * binaries name
  **/
 const char *
@@ -263,7 +263,7 @@ g_app_info_get_executable (GAppInfo *appinfo)
  * Gets the commandline with which the application will be
  * started.  
  *
- * Returns: a string containing the @appinfo's commandline, 
+ * Returns: (type filename): a string containing the @appinfo's commandline,
  *     or %NULL if this information is not available
  *
  * Since: 2.20
@@ -339,7 +339,8 @@ g_app_info_set_as_last_used_for_type (GAppInfo    *appinfo,
 /**
  * g_app_info_set_as_default_for_extension:
  * @appinfo: a #GAppInfo.
- * @extension: a string containing the file extension (without the dot).
+ * @extension: (type filename): a string containing the file extension
+ *     (without the dot).
  * @error: a #GError.
  * 
  * Sets the application as the default handler for the given file extension.
@@ -876,8 +877,8 @@ g_app_launch_context_init (GAppLaunchContext *context)
 /**
  * g_app_launch_context_setenv:
  * @context: a #GAppLaunchContext
- * @variable: the environment variable to set
- * @value: the value for to set the variable to.
+ * @variable: (type filename): the environment variable to set
+ * @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.
@@ -899,7 +900,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.
@@ -926,8 +927,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
- *     child's environment
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     the child's environment
  *
  * Since: 2.32
  */
diff --git a/gio/gapplication.c b/gio/gapplication.c
index f0af77b..9909a44 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -2198,7 +2198,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) (allow-none): the argv from main(), or %NULL
+ * @argv: (array length=argc) (element-type filename) (allow-none):
+ *     the argv from main(), or %NULL
  *
  * Runs the application.
  *
diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c
index 8ef0f51..151ec58 100644
--- a/gio/gapplicationcommandline.c
+++ b/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
- * containing the arguments (the argv)
+ * Returns: (array length=argc) (element-type filename) (transfer full)
+ *      the string array containing the arguments (the argv)
  *
  * Since: 2.28
  **/
@@ -552,7 +552,7 @@ g_application_command_line_get_stdin (GApplicationCommandLine *cmdline)
  * The return value should not be modified or freed and is valid for as
  * long as @cmdline exists.
  *
- * Returns: the current directory, or %NULL
+ * Returns: (type filename): the current directory, or %NULL
  *
  * 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
- * strings, or %NULL if they were not sent
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
+ *     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.
diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c
index d65288d..6318cbc 100644
--- a/gio/gdesktopappinfo.c
+++ b/gio/gdesktopappinfo.c
@@ -1852,7 +1852,8 @@ g_desktop_app_info_new_from_keyfile (GKeyFile *key_file)
 
 /**
  * g_desktop_app_info_new_from_filename:
- * @filename: the path of a desktop file, in the GLib filename encoding
+ * @filename: (type filename): the path of a desktop file, in the GLib
+ *      filename encoding
  *
  * Creates a new #GDesktopAppInfo.
  *
@@ -2027,7 +2028,8 @@ g_desktop_app_info_get_is_hidden (GDesktopAppInfo *info)
  * situations such as the #GDesktopAppInfo returned from
  * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
  *
- * Returns: The full path to the file for @info, or %NULL if not known.
+ * Returns: (type filename): The full path to the file for @info,
+ *     or %NULL if not known.
  * Since: 2.24
  */
 const char *
@@ -3674,7 +3676,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: (allow-none): 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.
diff --git a/gio/gfile.c b/gio/gfile.c
index db76aec..9a5a661 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -492,9 +492,9 @@ g_file_get_uri_scheme (GFile *file)
  *
  * This call does no blocking I/O.
  *
- * Returns: (nullable): string containing the #GFile's base name, or
- *     %NULL if given #GFile is invalid. The returned string should be
- *     freed with g_free() when no longer needed.
+ * Returns: (type filename) (nullable): string containing the #GFile's
+ *     base name, or %NULL if given #GFile is invalid. The returned string
+ *     should be freed with g_free() when no longer needed.
  */
 char *
 g_file_get_basename (GFile *file)
@@ -517,8 +517,8 @@ g_file_get_basename (GFile *file)
  *
  * This call does no blocking I/O.
  *
- * Returns: (nullable): string containing the #GFile's path, or %NULL
- *     if no such path exists. The returned string should be freed
+ * Returns: (type filename) (nullable): string containing the #GFile's path,
+ *     or %NULL if no such path exists. The returned string should be freed
  *     with g_free() when no longer needed.
  */
 char *
@@ -861,8 +861,8 @@ g_file_has_prefix (GFile *file,
  *
  * This call does no blocking I/O.
  *
- * Returns: (nullable): string with the relative path from @descendant
- *     to @parent, or %NULL if @descendant doesn't have @parent as
+ * Returns: (type filename) (nullable): string with the relative path from
+ *     @descendant to @parent, or %NULL if @descendant doesn't have @parent as
  *     prefix. The returned string should be freed with g_free() when
  *     no longer needed.
  */
@@ -3849,7 +3849,8 @@ g_file_make_directory_with_parents (GFile         *file,
 /**
  * g_file_make_symbolic_link:
  * @file: a #GFile with the name of the symlink to create
- * @symlink_value: a string with the path for the target of the new symlink
+ * @symlink_value: (type filename): a string with the path for the target
+ *     of the new symlink
  * @cancellable: (allow-none): optional #GCancellable object,
  *     %NULL to ignore
  * @error: a #GError
@@ -6317,7 +6318,7 @@ g_file_real_copy_finish (GFile        *file,
 
 /**
  * g_file_new_for_path:
- * @path: a string containing a relative or absolute path.
+ * @path: (type filename): a string containing a relative or absolute path.
  *     The string must be encoded in the glib filename encoding.
  *
  * Constructs a #GFile for a given path. This operation never
@@ -6482,7 +6483,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
@@ -6512,8 +6513,8 @@ g_file_new_for_commandline_arg (const char *arg)
 
 /**
  * g_file_new_for_commandline_arg_and_cwd:
- * @arg: a command line string
- * @cwd: the current working directory of the commandline
+ * @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.
  *
diff --git a/gio/gfileinfo.c b/gio/gfileinfo.c
index b8e3179..49e0606 100644
--- a/gio/gfileinfo.c
+++ b/gio/gfileinfo.c
@@ -1576,7 +1576,7 @@ g_file_info_get_is_symlink (GFileInfo *info)
  *
  * Gets the name for a file.
  *
- * Returns: a string containing the file name.
+ * Returns: (type filename): a string containing the file name.
  **/
 const char *
 g_file_info_get_name (GFileInfo *info)
@@ -1921,7 +1921,7 @@ g_file_info_set_is_symlink (GFileInfo *info,
 /**
  * g_file_info_set_name:
  * @info: a #GFileInfo.
- * @name: a string containing a name.
+ * @name: (type filename): a string containing a name.
  *
  * Sets the name attribute for the current #GFileInfo.
  * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
diff --git a/gio/giomodule.c b/gio/giomodule.c
index da7c167..54471c7 100644
--- a/gio/giomodule.c
+++ b/gio/giomodule.c
@@ -339,7 +339,7 @@ g_io_module_unload_module (GTypeModule *gmodule)
 
 /**
  * g_io_module_new:
- * @filename: filename of the shared library module.
+ * @filename: (type filename): filename of the shared library module.
  * 
  * Creates a new GIOModule that will load the specific
  * shared library when in use.
@@ -389,7 +389,8 @@ is_valid_module_name (const gchar        *basename,
 
 /**
  * g_io_modules_scan_all_in_directory_with_scope:
- * @dirname: pathname for a directory containing modules to scan.
+ * @dirname: (type filename): pathname for a directory containing modules
+ *     to scan.
  * @scope: a scope to use when scanning the modules
  *
  * Scans all the modules in the specified directory, ensuring that
@@ -531,7 +532,8 @@ g_io_modules_scan_all_in_directory_with_scope (const char     *dirname,
 
 /**
  * g_io_modules_scan_all_in_directory:
- * @dirname: pathname for a directory containing modules to scan.
+ * @dirname: (type filename): pathname for a directory containing modules
+ *     to scan.
  *
  * Scans all the modules in the specified directory, ensuring that
  * any extension point implemented by a module is registered.
@@ -555,7 +557,8 @@ g_io_modules_scan_all_in_directory (const char *dirname)
 
 /**
  * g_io_modules_load_all_in_directory_with_scope:
- * @dirname: pathname for a directory containing modules to load.
+ * @dirname: (type filename): pathname for a directory containing modules
+ *     to load.
  * @scope: a scope to use when scanning the modules.
  *
  * Loads all the modules in the specified directory.
@@ -620,7 +623,8 @@ g_io_modules_load_all_in_directory_with_scope (const char     *dirname,
 
 /**
  * g_io_modules_load_all_in_directory:
- * @dirname: pathname for a directory containing modules to load.
+ * @dirname: (type filename): pathname for a directory containing modules
+ *     to load.
  *
  * Loads all the modules in the specified directory.
  *
diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c
index 5b90d01..ee31f81 100644
--- a/gio/gsettingsschema.c
+++ b/gio/gsettingsschema.c
@@ -246,7 +246,7 @@ g_settings_schema_source_unref (GSettingsSchemaSource *source)
 
 /**
  * g_settings_schema_source_new_from_directory:
- * @directory: the filename of a directory
+ * @directory: (type filename): the filename of a directory
  * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
  * @trusted: %TRUE, if the directory is trusted
  * @error: a pointer to a #GError pointer set to %NULL, or %NULL
diff --git a/gio/gsubprocess.c b/gio/gsubprocess.c
index 170e7e7..cd88eb8 100644
--- a/gio/gsubprocess.c
+++ b/gio/gsubprocess.c
@@ -697,7 +697,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: (allow-none): return location for an error, or %NULL
  *
diff --git a/gio/gsubprocesslauncher.c b/gio/gsubprocesslauncher.c
index e32f9bd..75a5cd6 100644
--- a/gio/gsubprocesslauncher.c
+++ b/gio/gsubprocesslauncher.c
@@ -225,7 +225,8 @@ g_subprocess_launcher_new (GSubprocessFlags flags)
 /**
  * g_subprocess_launcher_set_environ:
  * @self: a #GSubprocess
- * @env: the replacement environment
+ * @env: (array zero-terminated=1) (element-type filename) (nullable) (transfer none):
+ *     the replacement environment
  *
  * Replace the entire environment of processes launched from this
  * launcher with the given 'environ' variable.
@@ -253,8 +254,9 @@ g_subprocess_launcher_set_environ (GSubprocessLauncher  *self,
 /**
  * g_subprocess_launcher_setenv:
  * @self: a #GSubprocess
- * @variable: the environment variable to set, must not contain '='
- * @value: the new value for the variable
+ * @variable: (type filename): the environment variable to set,
+ *     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
@@ -278,7 +280,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.
@@ -298,7 +301,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.
@@ -306,7 +309,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
  **/
@@ -320,7 +324,7 @@ g_subprocess_launcher_getenv (GSubprocessLauncher *self,
 /**
  * g_subprocess_launcher_set_cwd:
  * @self: a #GSubprocess
- * @cwd: the cwd for launched processes
+ * @cwd: (type filename): the cwd for launched processes
  *
  * Sets the current working directory that processes will be launched
  * with.
@@ -403,7 +407,7 @@ assign_fd (gint *fd_ptr, gint fd)
 /**
  * g_subprocess_launcher_set_stdin_file_path:
  * @self: a #GSubprocessLauncher
- * @path: a filename or %NULL
+ * @path: (type filename) (nullable: a filename or %NULL
  *
  * Sets the file path to use as the stdin for spawned processes.
  *
@@ -466,7 +470,7 @@ g_subprocess_launcher_take_stdin_fd (GSubprocessLauncher *self,
 /**
  * g_subprocess_launcher_set_stdout_file_path:
  * @self: a #GSubprocessLauncher
- * @path: a filename or %NULL
+ * @path: (type filename) (nullable): a filename or %NULL
  *
  * Sets the file path to use as the stdout for spawned processes.
  *
@@ -529,7 +533,7 @@ g_subprocess_launcher_take_stdout_fd (GSubprocessLauncher *self,
 /**
  * g_subprocess_launcher_set_stderr_file_path:
  * @self: a #GSubprocessLauncher
- * @path: a filename or %NULL
+ * @path: (type filename) (nullable): a filename or %NULL
  *
  * Sets the file path to use as the stderr for spawned processes.
  *
@@ -711,7 +715,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.
diff --git a/gio/gtlscertificate.c b/gio/gtlscertificate.c
index e43c2ce..59edab3 100644
--- a/gio/gtlscertificate.c
+++ b/gio/gtlscertificate.c
@@ -496,7 +496,7 @@ g_tls_certificate_new_from_pem  (const gchar  *data,
 
 /**
  * g_tls_certificate_new_from_file:
- * @file: file containing a PEM-encoded certificate to import
+ * @file: (type filename): file containing a PEM-encoded certificate to import
  * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Creates a #GTlsCertificate from the PEM-encoded data in @file. The
@@ -535,9 +535,10 @@ g_tls_certificate_new_from_file (const gchar  *file,
 
 /**
  * g_tls_certificate_new_from_files:
- * @cert_file: file containing one or more PEM-encoded certificates to
- * import
- * @key_file: file containing a PEM-encoded private key to import
+ * @cert_file: (type filename): file containing one or more PEM-encoded
+ *     certificates to import
+ * @key_file: (type filename): file containing a PEM-encoded private key
+ *     to import
  * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
@@ -591,7 +592,7 @@ g_tls_certificate_new_from_files (const gchar  *cert_file,
 
 /**
  * g_tls_certificate_list_new_from_file:
- * @file: file containing PEM-encoded certificates to import
+ * @file: (type filename): file containing PEM-encoded certificates to import
  * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Creates one or more #GTlsCertificates from the PEM-encoded
diff --git a/gio/gtlsfiledatabase.c b/gio/gtlsfiledatabase.c
index dd341bc..d07c702 100644
--- a/gio/gtlsfiledatabase.c
+++ b/gio/gtlsfiledatabase.c
@@ -74,7 +74,7 @@ g_tls_file_database_default_init (GTlsFileDatabaseInterface *iface)
 
 /**
  * g_tls_file_database_new:
- * @anchors: filename of anchor certificate authorities.
+ * @anchors: (type filename): filename of anchor certificate authorities.
  * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Creates a new #GTlsFileDatabase which uses anchor certificate authorities
diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c
index 2e2ff5e..1e0d6c5 100644
--- a/gio/gunixmounts.c
+++ b/gio/gunixmounts.c
@@ -196,7 +196,7 @@ is_in (const char *value, const char *set[])
 
 /**
  * g_unix_is_mount_path_system_internal:
- * @mount_path: a mount path, e.g. `/media/disk` or `/usr`
+ * @mount_path: (type filename): a mount path, e.g. `/media/disk` or `/usr`
  *
  * Determines if @mount_path is considered an implementation of the
  * OS. This is primarily used for hiding mountable and mounted volumes
@@ -1657,7 +1657,7 @@ g_unix_mount_compare (GUnixMountEntry *mount1,
  * 
  * Gets the mount path for a unix mount.
  * 
- * Returns: the mount path for @mount_entry.
+ * Returns: (type filename): the mount path for @mount_entry.
  */
 const gchar *
 g_unix_mount_get_mount_path (GUnixMountEntry *mount_entry)
@@ -1673,7 +1673,7 @@ g_unix_mount_get_mount_path (GUnixMountEntry *mount_entry)
  * 
  * Gets the device path for a unix mount.
  * 
- * Returns: a string containing the device path.
+ * Returns: (type filename): a string containing the device path.
  */
 const gchar *
 g_unix_mount_get_device_path (GUnixMountEntry *mount_entry)
@@ -1787,7 +1787,7 @@ g_unix_mount_point_compare (GUnixMountPoint *mount1,
  * 
  * Gets the mount path for a unix mount point.
  * 
- * Returns: a string containing the mount path.
+ * Returns: (type filename): a string containing the mount path.
  */
 const gchar *
 g_unix_mount_point_get_mount_path (GUnixMountPoint *mount_point)
@@ -1803,7 +1803,7 @@ g_unix_mount_point_get_mount_path (GUnixMountPoint *mount_point)
  * 
  * Gets the device path for a unix mount point.
  * 
- * Returns: a string containing the device path.
+ * Returns: (type filename): a string containing the device path.
  */
 const gchar *
 g_unix_mount_point_get_device_path (GUnixMountPoint *mount_point)
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]