[gtk+/gi-annotations-2: 8/12] [GI] Annotate strings holding file paths as (type filename)

From: Pavel Holejsovsky <pholejs src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk+/gi-annotations-2: 8/12] [GI] Annotate strings holding file paths as (type filename)
Date: Tue, 18 Jan 2011 09:32:56 +0000 (UTC)
commit abaf2603db4486a60b6e2f329478da7569357db4
Author: Pavel Holejsovsky <pholejs src gnome org>
Date:   Tue Jan 18 06:42:31 2011 +0100

    [GI] Annotate strings holding file paths as (type filename)

 gtk/gtkaccelmap.c       |    6 +++---
 gtk/gtkfilechooser.c    |   41 ++++++++++++++++++++++-------------------
 gtk/gtkiconfactory.c    |    6 +++---
 gtk/gtkicontheme.c      |   15 ++++++++-------
 gtk/gtkimage.c          |    4 ++--
 gtk/gtkpagesetup.c      |    6 +++---
 gtk/gtkprintjob.c       |    2 +-
 gtk/gtkprintoperation.c |    2 +-
 gtk/gtkprintsettings.c  |    6 +++---
 gtk/gtkrc.c             |   23 ++++++++++++-----------
 gtk/gtkstatusicon.c     |    4 ++--
 gtk/gtkuimanager.c      |    2 +-
 gtk/gtkwindow.c         |    4 ++--
 13 files changed, 63 insertions(+), 58 deletions(-)
---
diff --git a/gtk/gtkaccelmap.c b/gtk/gtkaccelmap.c
index f678f02..32d8c79 100644
--- a/gtk/gtkaccelmap.c
+++ b/gtk/gtkaccelmap.c
@@ -669,7 +669,7 @@ gtk_accel_map_load_fd (gint fd)
 
 /**
  * gtk_accel_map_load:
- * @file_name: a file containing accelerator specifications,
+ * @file_name: (type filename): a file containing accelerator specifications,
  *   in the GLib file name encoding
  *
  * Parses a file previously saved with gtk_accel_map_save() for
@@ -780,8 +780,8 @@ gtk_accel_map_save_fd (gint fd)
 
 /**
  * gtk_accel_map_save:
- * @file_name: the name of the file to contain accelerator specifications,
- *   in the GLib file name encoding
+ * @file_name: (type filename): the name of the file to contain
+ *   accelerator specifications, in the GLib file name encoding
  *
  * Saves current accelerator specifications (accelerator path, key
  * and modifiers) to @file_name.
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 64fcdc9..1b782a7 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -1033,7 +1033,7 @@ gtk_file_chooser_get_create_folders (GtkFileChooser *chooser)
  * If the file chooser is in folder mode, this function returns the selected
  * folder.
  * 
- * Return value: The currently selected filename, or %NULL
+ * Return value: (type filename): The currently selected filename, or %NULL
  *  if no file is selected, or the selected file can't
  *  be represented with a local filename. Free with g_free().
  *
@@ -1061,7 +1061,7 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
 /**
  * gtk_file_chooser_set_filename:
  * @chooser: a #GtkFileChooser
- * @filename: the filename to set as current
+ * @filename: (type filename): the filename to set as current
  * 
  * Sets @filename as the current filename for the file chooser, by changing
  * to the file's parent folder and actually selecting the file in list.  If
@@ -1115,7 +1115,7 @@ gtk_file_chooser_set_filename (GtkFileChooser *chooser,
 /**
  * gtk_file_chooser_select_filename:
  * @chooser: a #GtkFileChooser
- * @filename: the filename to select
+ * @filename: (type filename): the filename to select
  * 
  * Selects a filename. If the file name isn't in the current
  * folder of @chooser, then the current folder of @chooser will
@@ -1146,7 +1146,7 @@ gtk_file_chooser_select_filename (GtkFileChooser *chooser,
 /**
  * gtk_file_chooser_unselect_filename:
  * @chooser: a #GtkFileChooser
- * @filename: the filename to unselect
+ * @filename: (type filename): the filename to unselect
  * 
  * Unselects a currently selected filename. If the filename
  * is not in the current directory, does not exist, or
@@ -1201,9 +1201,10 @@ files_to_strings (GSList  *files,
  * folder cannot be represented as local filenames they will be ignored. (See
  * gtk_file_chooser_get_uris())
  *
- * Return value: (element-type utf8) (transfer full): a #GSList containing the filenames of all selected
- *   files and subfolders in the current folder. Free the returned list
- *   with g_slist_free(), and the filenames with g_free().
+ * Return value: (element-type filename) (transfer full): a #GSList
+ *    containing the filenames of all selected files and subfolders in
+ *    the current folder. Free the returned list with g_slist_free(),
+ *    and the filenames with g_free().
  *
  * Since: 2.4
  **/
@@ -1226,7 +1227,7 @@ gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
 /**
  * gtk_file_chooser_set_current_folder:
  * @chooser: a #GtkFileChooser
- * @filename: the full path of the new current folder
+ * @filename: (type filename): the full path of the new current folder
  * 
  * Sets the current folder for @chooser from a local filename.
  * The user will be shown the full contents of the current folder,
@@ -1269,10 +1270,11 @@ gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
  * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
  * usual way to get the selection.
  * 
- * Return value: the full path of the current folder, or %NULL if the current
- * path cannot be represented as a local filename.  Free with g_free().  This
- * function will also return %NULL if the file chooser was unable to load the
- * last folder that was requested from it; for example, as would be for calling
+ * Return value: (type filename): the full path of the current folder,
+ * or %NULL if the current path cannot be represented as a local
+ * filename.  Free with g_free().  This function will also return
+ * %NULL if the file chooser was unable to load the last folder that
+ * was requested from it; for example, as would be for calling
  * gtk_file_chooser_set_current_folder() on a nonexistent folder.
  *
  * Since: 2.4
@@ -1298,7 +1300,7 @@ gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
 /**
  * gtk_file_chooser_set_current_name:
  * @chooser: a #GtkFileChooser
- * @name: the filename to use, as a UTF-8 string
+ * @name: (type filename): the filename to use, as a UTF-8 string
  * 
  * Sets the current name in the file selector, as if entered
  * by the user. Note that the name passed in here is a UTF-8
@@ -2057,8 +2059,8 @@ _gtk_file_chooser_remove_shortcut_folder (GtkFileChooser  *chooser,
  * Gets the filename that should be previewed in a custom preview
  * widget. See gtk_file_chooser_set_preview_widget().
  * 
- * Return value: the filename to preview, or %NULL if no file
- *  is selected, or if the selected file cannot be represented
+ * Return value: (type filename): the filename to preview, or %NULL if
+ *  no file is selected, or if the selected file cannot be represented
  *  as a local filename. Free with g_free()
  *
  * Since: 2.4
@@ -2277,7 +2279,7 @@ gtk_file_chooser_get_filter (GtkFileChooser *chooser)
 /**
  * gtk_file_chooser_add_shortcut_folder:
  * @chooser: a #GtkFileChooser
- * @folder: filename of the folder to add
+ * @folder: (type filename): filename of the folder to add
  * @error: (allow-none): location to store error, or %NULL
  * 
  * Adds a folder to be displayed with the shortcut folders in a file chooser.
@@ -2311,7 +2313,7 @@ gtk_file_chooser_add_shortcut_folder (GtkFileChooser    *chooser,
 /**
  * gtk_file_chooser_remove_shortcut_folder:
  * @chooser: a #GtkFileChooser
- * @folder: filename of the folder to remove
+ * @folder: (type filename): filename of the folder to remove
  * @error: (allow-none): location to store error, or %NULL
  * 
  * Removes a folder from a file chooser's list of shortcut folders.
@@ -2348,8 +2350,9 @@ gtk_file_chooser_remove_shortcut_folder (GtkFileChooser    *chooser,
  * Queries the list of shortcut folders in the file chooser, as set by
  * gtk_file_chooser_add_shortcut_folder().
  *
- * Return value: (element-type utf8) (transfer full): A list of folder filenames, or %NULL if there are no shortcut
- * folders.  Free the returned list with g_slist_free(), and the filenames with
+ * Return value: (element-type filename) (transfer full): A list of
+ * folder filenames, or %NULL if there are no shortcut folders.  Free
+ * the returned list with g_slist_free(), and the filenames with
  * g_free().
  *
  * Since: 2.4
diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c
index 5147282..a890a46 100644
--- a/gtk/gtkiconfactory.c
+++ b/gtk/gtkiconfactory.c
@@ -2018,7 +2018,7 @@ icon_source_clear (GtkIconSource *source)
 /**
  * gtk_icon_source_set_filename:
  * @source: a #GtkIconSource
- * @filename: image file to use
+ * @filename: (type filename): image file to use
  *
  * Sets the name of an image file to use as a base image when creating
  * icon variants for #GtkIconSet. The filename must be absolute.
@@ -2106,8 +2106,8 @@ gtk_icon_source_set_pixbuf (GtkIconSource *source,
  * filename is not a copy, and should not be modified or expected to
  * persist beyond the lifetime of the icon source.
  *
- * Return value: image filename. This string must not be modified
- * or freed.
+ * Return value: (type filename): image filename. This string must not
+ * be modified or freed.
  */
 G_CONST_RETURN gchar*
 gtk_icon_source_get_filename (const GtkIconSource *source)
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index e35894a..8103be4 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -738,7 +738,9 @@ gtk_icon_theme_set_search_path (GtkIconTheme *icon_theme,
 /**
  * gtk_icon_theme_get_search_path:
  * @icon_theme: a #GtkIconTheme
- * @path: (allow-none) (array length=n_elements) (out): location to store a list of icon theme path directories or %NULL
+
+ * @path: (allow-none) (array length=n_elements) (element-type filename) (out):
+ *        location to store a list of icon theme path directories or %NULL .
  *        The stored value should be freed with g_strfreev().
  * @n_elements: location to store number of elements
  *              in @path, or %NULL
@@ -774,7 +776,7 @@ gtk_icon_theme_get_search_path (GtkIconTheme      *icon_theme,
 /**
  * gtk_icon_theme_append_search_path:
  * @icon_theme: a #GtkIconTheme
- * @path: directory name to append to the icon path
+ * @path: (type filename): directory name to append to the icon path
  * 
  * Appends a directory to the search path. 
  * See gtk_icon_theme_set_search_path(). 
@@ -803,7 +805,7 @@ gtk_icon_theme_append_search_path (GtkIconTheme *icon_theme,
 /**
  * gtk_icon_theme_prepend_search_path:
  * @icon_theme: a #GtkIconTheme
- * @path: directory name to prepend to the icon path
+ * @path: (type filename): directory name to prepend to the icon path
  * 
  * Prepends a directory to the search path. 
  * See gtk_icon_theme_set_search_path().
@@ -2699,10 +2701,9 @@ gtk_icon_info_get_base_size (GtkIconInfo *icon_info)
  * no filename if a builtin icon is returned; in this
  * case, you should use gtk_icon_info_get_builtin_pixbuf().
  * 
- * Return value: the filename for the icon, or %NULL
- *  if gtk_icon_info_get_builtin_pixbuf() should
- *  be used instead. The return value is owned by
- *  GTK+ and should not be modified or freed.
+ * Return value: (type filename): the filename for the icon, or %NULL
+ *  if gtk_icon_info_get_builtin_pixbuf() should be used instead. The
+ *  return value is owned by GTK+ and should not be modified or freed.
  *
  * Since: 2.4
  **/
diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c
index dca9566..278a127 100644
--- a/gtk/gtkimage.c
+++ b/gtk/gtkimage.c
@@ -520,7 +520,7 @@ gtk_image_get_property (GObject     *object,
 
 /**
  * gtk_image_new_from_file:
- * @filename: a filename
+ * @filename: (type filename): a filename
  * 
  * Creates a new #GtkImage displaying the file @filename. If the file
  * isn't found or can't be loaded, the resulting #GtkImage will
@@ -726,7 +726,7 @@ gtk_image_new_from_gicon (GIcon *icon,
 /**
  * gtk_image_set_from_file:
  * @image: a #GtkImage
- * @filename: (allow-none): a filename or %NULL
+ * @filename: (type filename) (allow-none): a filename or %NULL
  *
  * See gtk_image_new_from_file() for details.
  **/
diff --git a/gtk/gtkpagesetup.c b/gtk/gtkpagesetup.c
index a00177e..0ba69d3 100644
--- a/gtk/gtkpagesetup.c
+++ b/gtk/gtkpagesetup.c
@@ -526,7 +526,7 @@ gtk_page_setup_get_page_height (GtkPageSetup *setup,
 /**
  * gtk_page_setup_load_file:
  * @setup: a #GtkPageSetup
- * @file_name: the filename to read the page setup from
+ * @file_name: (type filename): the filename to read the page setup from
  * @error: (allow-none): return location for an error, or %NULL
  *
  * Reads the page setup from the file @file_name.
@@ -560,7 +560,7 @@ gtk_page_setup_load_file (GtkPageSetup *setup,
 
 /**
  * gtk_page_setup_new_from_file:
- * @file_name: the filename to read the page setup from
+ * @file_name: (type filename): the filename to read the page setup from
  * @error: (allow-none): return location for an error, or %NULL
  * 
  * Reads the page setup from the file @file_name. Returns a 
@@ -730,7 +730,7 @@ gtk_page_setup_new_from_key_file (GKeyFile     *key_file,
 /**
  * gtk_page_setup_to_file:
  * @setup: a #GtkPageSetup
- * @file_name: the file to save to
+ * @file_name: (type filename): the file to save to
  * @error: (allow-none): return location for errors, or %NULL
  * 
  * This function saves the information from @setup to @file_name.
diff --git a/gtk/gtkprintjob.c b/gtk/gtkprintjob.c
index fc9407c..634e6b4 100644
--- a/gtk/gtkprintjob.c
+++ b/gtk/gtkprintjob.c
@@ -422,7 +422,7 @@ gtk_print_job_set_status (GtkPrintJob   *job,
 /**
  * gtk_print_job_set_source_file:
  * @job: a #GtkPrintJob
- * @filename: the file to be printed
+ * @filename: (type filename): the file to be printed
  * @error: return location for errors
  * 
  * Make the #GtkPrintJob send an existing document to the 
diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c
index ff5e00c..15eadf1 100644
--- a/gtk/gtkprintoperation.c
+++ b/gtk/gtkprintoperation.c
@@ -1891,7 +1891,7 @@ gtk_print_operation_set_custom_tab_label (GtkPrintOperation  *op,
 /**
  * gtk_print_operation_set_export_filename:
  * @op: a #GtkPrintOperation
- * @filename: the filename for the exported file
+ * @filename: (type filename): the filename for the exported file
  * 
  * Sets up the #GtkPrintOperation to generate a file instead
  * of showing the print dialog. The indended use of this function
diff --git a/gtk/gtkprintsettings.c b/gtk/gtkprintsettings.c
index da3d60d..64c8e51 100644
--- a/gtk/gtkprintsettings.c
+++ b/gtk/gtkprintsettings.c
@@ -1677,7 +1677,7 @@ gtk_print_settings_set_output_bin (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_load_file:
  * @settings: a #GtkPrintSettings
- * @file_name: the filename to read the settings from
+ * @file_name: (type filename): the filename to read the settings from
  * @error: (allow-none): return location for errors, or %NULL
  *
  * Reads the print settings from @file_name. If the file could not be loaded
@@ -1712,7 +1712,7 @@ gtk_print_settings_load_file (GtkPrintSettings *settings,
 
 /**
  * gtk_print_settings_new_from_file:
- * @file_name: the filename to read the settings from
+ * @file_name: (type filename): the filename to read the settings from
  * @error: (allow-none): return location for errors, or %NULL
  * 
  * Reads the print settings from @file_name. Returns a new #GtkPrintSettings
@@ -1837,7 +1837,7 @@ gtk_print_settings_new_from_key_file (GKeyFile     *key_file,
 /**
  * gtk_print_settings_to_file:
  * @settings: a #GtkPrintSettings
- * @file_name: the file to save to
+ * @file_name: (type filename): the file to save to
  * @error: (allow-none): return location for errors, or %NULL
  * 
  * This function saves the print settings from @settings to @file_name. If the
diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c
index 394c90b..fa5789b 100644
--- a/gtk/gtkrc.c
+++ b/gtk/gtkrc.c
@@ -250,8 +250,8 @@ gtk_rc_make_default_dir (const gchar *type)
 
 /**
  * gtk_rc_get_im_module_path:
- * @returns: a newly-allocated string containing the path in which to 
- *    look for IM modules.
+ * @returns: (type filename): a newly-allocated string containing the
+ *    path in which to look for IM modules.
  *
  * Obtains the path in which to look for IM modules. See the documentation
  * of the <link linkend="im-module-path"><envar>GTK_PATH</envar></link>
@@ -271,8 +271,8 @@ gtk_rc_get_im_module_path (void)
 
 /**
  * gtk_rc_get_im_module_file:
- * @returns: a newly-allocated string containing the name of the file
- * listing the IM modules available for loading
+ * @returns: (type filename): a newly-allocated string containing the
+ *    name of the file listing the IM modules available for loading
  *
  * Obtains the path to the IM modules file. See the documentation
  * of the <link linkend="im-module-file"><envar>GTK_IM_MODULE_FILE</envar></link>
@@ -322,7 +322,7 @@ gtk_rc_get_theme_dir (void)
  * see the docs for <envar>GTK_PATH</envar> in
  * <xref linkend="gtk-running"/>.
  * 
- * return value: the directory. (Must be freed with g_free())
+ * return value: (type filename): the directory. (Must be freed with g_free())
  **/
 gchar *
 gtk_rc_get_module_dir (void)
@@ -332,8 +332,8 @@ gtk_rc_get_module_dir (void)
 
 /**
  * gtk_rc_add_default_file:
- * @filename: the pathname to the file. If @filename is not absolute, it
- *    is searched in the current directory.
+ * @filename: (type filename): the pathname to the file. If @filename
+ *    is not absolute, it is searched in the current directory.
  *
  * Adds a file to the list of files to be parsed at the
  * end of gtk_init().
@@ -347,7 +347,8 @@ gtk_rc_add_default_file (const gchar *filename)
 
 /**
  * gtk_rc_set_default_files:
- * @filenames: A %NULL-terminated list of filenames.
+ * @filenames: (array zero-terminated=1) (element-type filename): A
+ *     %NULL-terminated list of filenames.
  *
  * Sets the list of files that GTK+ will read at the
  * end of gtk_init().
@@ -937,7 +938,7 @@ lookup_color (GtkRcStyle *style,
  * If the file is not found, it outputs a warning message using
  * g_warning() and returns %NULL.
  *
- * Return value: the filename. 
+ * Return value: (type filename): the filename. 
  **/
 gchar*
 gtk_rc_find_pixmap_in_path (GtkSettings  *settings,
@@ -956,8 +957,8 @@ gtk_rc_find_pixmap_in_path (GtkSettings  *settings,
  * Searches for a theme engine in the GTK+ search path. This function
  * is not useful for applications and should not be used.
  * 
- * Return value: The filename, if found (must be freed with g_free()),
- *   otherwise %NULL.
+ * Return value: (type filename): The filename, if found (must be
+ *   freed with g_free()), otherwise %NULL.
  **/
 gchar*
 gtk_rc_find_module_in_path (const gchar *module_file)
diff --git a/gtk/gtkstatusicon.c b/gtk/gtkstatusicon.c
index ed5e64a..82e4a37 100644
--- a/gtk/gtkstatusicon.c
+++ b/gtk/gtkstatusicon.c
@@ -1185,7 +1185,7 @@ gtk_status_icon_new_from_pixbuf (GdkPixbuf *pixbuf)
 
 /**
  * gtk_status_icon_new_from_file:
- * @filename: a filename
+ * @filename: (type filename): a filename
  * 
  * Creates a status icon displaying the file @filename. 
  *
@@ -1913,7 +1913,7 @@ gtk_status_icon_set_from_pixbuf (GtkStatusIcon *status_icon,
 /**
  * gtk_status_icon_set_from_file:
  * @status_icon: a #GtkStatusIcon
- * @filename: a filename
+ * @filename: (type filename): a filename
  * 
  * Makes @status_icon display the file @filename.
  * See gtk_status_icon_new_from_file() for details.
diff --git a/gtk/gtkuimanager.c b/gtk/gtkuimanager.c
index 7162f77..e5e536a 100644
--- a/gtk/gtkuimanager.c
+++ b/gtk/gtkuimanager.c
@@ -1700,7 +1700,7 @@ gtk_ui_manager_add_ui_from_string (GtkUIManager *manager,
 /**
  * gtk_ui_manager_add_ui_from_file:
  * @manager: a #GtkUIManager object
- * @filename: the name of the file to parse 
+ * @filename: (type filename): the name of the file to parse 
  * @error: return location for an error
  * 
  * Parses a file containing a <link linkend="XML-UI">UI definition</link> and 
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 4376657..86cbba5 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -3686,7 +3686,7 @@ load_pixbuf_verbosely (const char *filename,
 /**
  * gtk_window_set_icon_from_file:
  * @window: a #GtkWindow
- * @filename: location of icon file
+ * @filename: (type filename): location of icon file
  * @err: (allow-none): location to store error, or %NULL.
  *
  * Sets the icon for @window.  
@@ -3864,7 +3864,7 @@ gtk_window_get_default_icon_name (void)
 
 /**
  * gtk_window_set_default_icon_from_file:
- * @filename: location of icon file
+ * @filename: (type filename): location of icon file
  * @err: (allow-none): location to store error, or %NULL.
  *
  * Sets an icon to be used as fallback for windows that haven't
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]