Fix up the docs

Taken from gedit, commit: 42a6a8d8d87f32572f56b56a9c4e92f7181d339a from: Garrett Regier <[email protected]>
author: infirit <[email protected]> 2015-09-05 21:06:15 +0200
committer: infirit <[email protected]> 2015-09-05 21:46:09 +0200
commit: 3d9e640cc4221a43d214951da5cbdc43c4f55662 (patch)
tree: a4fbe0612956b35a63c1cec927ea9ad7e79bb217
parent: 1618c8f7248722265450b11ef48ced34c7a317a5 (diff)
download: pluma-3d9e640cc4221a43d214951da5cbdc43c4f55662.tar.bz2
pluma-3d9e640cc4221a43d214951da5cbdc43c4f55662.tar.xz
15 files changed, 205 insertions, 77 deletions
diff --git a/pluma/pluma-app.c b/pluma/pluma-app.c
index 3f486f0b..d9e713e4 100644
--- a/pluma/pluma-app.c
+++ b/pluma/pluma-app.c
@@ -551,6 +551,7 @@ pluma_app_create_window_real (PlumaApp *app,
 /**
 * pluma_app_create_window:
 * @app: the #PlumaApp
+ * @screen: (allow-none):
 *
 * Create a new #PlumaWindow part of @app.
 *
@@ -591,8 +592,8 @@ _pluma_app_restore_window (PlumaApp *app,
 *
 * Returns all the windows currently present in #PlumaApp.
 *
- * Return value: the list of #PlumaWindows objects. The list
- * should not be freed
+ * Return value: (transfer none): the list of #PlumaWindows objects.
+ * The list should not be freed
 */
 const GList *
 pluma_app_get_windows (PlumaApp *app)
@@ -737,7 +738,8 @@ _pluma_app_get_window_in_viewport (PlumaApp *app,
 *
 * Returns all the documents currently open in #PlumaApp.
 *
- * Return value: a newly allocated list of #PlumaDocument objects
+ * Return value: (element-type Pluma.Document) (transfer container):
+ * a newly allocated list of #PlumaDocument objects
 */
 GList *
 pluma_app_get_documents (PlumaApp *app)
@@ -766,7 +768,8 @@ pluma_app_get_documents (PlumaApp *app)
 *
 * Returns all the views currently present in #PlumaApp.
 *
- * Return value: a newly allocated list of #PlumaView objects
+ * Return value: (element-type Pluma.View) (transfer container):
+ * a newly allocated list of #PlumaView objects
 */
 GList *
 pluma_app_get_views (PlumaApp *app)
diff --git a/pluma/pluma-commands-file.c b/pluma/pluma-commands-file.c
index a21cdff6..5407c212 100644
--- a/pluma/pluma-commands-file.c
+++ b/pluma/pluma-commands-file.c
@@ -304,8 +304,14 @@ load_uri_list (PlumaWindow *window,
 
 /**
 * pluma_commands_load_uri:
+ * @window:
+ * @uri:
+ * @encoding: (allow-none):
+ * @line_pos:
 *
- * Do nothing if URI does not exist
+ * Do nothing if uri does not exist
+ *
+ * Returns: (transfer container):
 */
 void
 pluma_commands_load_uri (PlumaWindow *window,
@@ -330,8 +336,14 @@ pluma_commands_load_uri (PlumaWindow *window,
 
 /**
 * pluma_commands_load_uris:
+ * @window:
+ * @uris:
+ * @encoding:
+ * @line_pos:
+ *
+ * Ignore non-existing URIs
 *
- * Ignore non-existing URIs 
+ * Returns: (transfer container):
 */
 gint
 pluma_commands_load_uris (PlumaWindow *window,
diff --git a/pluma/pluma-debug.h b/pluma/pluma-debug.h
index 321d3c51..3ef47256 100644
--- a/pluma/pluma-debug.h
+++ b/pluma/pluma-debug.h
@@ -60,6 +60,7 @@ typedef enum {
 } PlumaDebugSection;
 
 
+/* FIXME this is an issue for introspection */
 #define DEBUG_VIEW PLUMA_DEBUG_VIEW, __FILE__, __LINE__, G_STRFUNC
 #define DEBUG_SEARCH PLUMA_DEBUG_SEARCH, __FILE__, __LINE__, G_STRFUNC
 #define DEBUG_PRINT PLUMA_DEBUG_PRINT, __FILE__, __LINE__, G_STRFUNC
diff --git a/pluma/pluma-document.c b/pluma/pluma-document.c
index 563e9500..f99d9f43 100644
--- a/pluma/pluma-document.c
+++ b/pluma/pluma-document.c
@@ -1003,6 +1003,11 @@ set_content_type (PlumaDocument *doc,
 }
 }
 
+/**
+ * pluma_document_set_content_type:
+ * @doc:
+ * @content_type: (allow-none):
+ */
 void
 pluma_document_set_content_type (PlumaDocument *doc,
 const gchar *content_type)
@@ -1070,7 +1075,12 @@ pluma_document_set_uri (PlumaDocument *doc,
 set_content_type (doc, NULL);
 }
 
-/* Never returns NULL */
+/**
+ * pluma_document_get_uri_for_display:
+ * @doc:
+ *
+ * Note: this never returns %NULL.
+ **/
 gchar *
 pluma_document_get_uri_for_display (PlumaDocument *doc)
 {
@@ -1083,7 +1093,12 @@ pluma_document_get_uri_for_display (PlumaDocument *doc)
 return pluma_utils_uri_for_display (doc->priv->uri);
 }
 
-/* Never returns NULL */
+/**
+ * pluma_document_get_short_name_for_display:
+ * @doc:
+ *
+ * Note: this never returns %NULL.
+ **/
 gchar *
 pluma_document_get_short_name_for_display (PlumaDocument *doc)
 {
@@ -1098,6 +1113,11 @@ pluma_document_get_short_name_for_display (PlumaDocument *doc)
 return pluma_utils_basename_for_display (doc->priv->uri);
 }
 
+/**
+ * pluma_document_set_short_name_for_display:
+ * @doc:
+ * @short_name: (allow-none):
+ */
 void
 pluma_document_set_short_name_for_display (PlumaDocument *doc,
 const gchar *short_name)
@@ -1118,7 +1138,12 @@ pluma_document_get_content_type (PlumaDocument *doc)
 return g_strdup (doc->priv->content_type);
 }
 
-/* Never returns NULL */
+/**
+ * pluma_document_get_mime_type:
+ * @doc:
+ *
+ * Note: this never returns %NULL.
+ **/
 gchar *
 pluma_document_get_mime_type (PlumaDocument *doc)
 {
@@ -1760,6 +1785,12 @@ compute_num_of_lines (const gchar *text)
 return n;
 }
 
+/**
+ * pluma_document_set_search_text"
+ * @doc:
+ * @text: (allow-none):
+ * @flags:
+ **/
 void
 pluma_document_set_search_text (PlumaDocument *doc,
 const gchar *text,
@@ -1822,6 +1853,11 @@ pluma_document_set_search_text (PlumaDocument *doc,
 g_object_notify (G_OBJECT (doc), "can-search-again");
 }
 
+/**
+ * pluma_document_get_search_text:
+ * @doc:
+ * @flags: (allow-none):
+ */
 gchar *
 pluma_document_get_search_text (PlumaDocument *doc,
 guint *flags)
@@ -1843,6 +1879,14 @@ pluma_document_get_can_search_again (PlumaDocument *doc)
 (*doc->priv->search_text != '\0'));
 }
 
+/**
+ * pluma_document_search_forward:
+ * @doc:
+ * @start: (allow-none):
+ * @end: (allow-none):
+ * @match_start: (allow-none):
+ * @match_end: (allow=none):
+ **/
 gboolean
 pluma_document_search_forward (PlumaDocument *doc,
 const GtkTextIter *start,
@@ -1927,7 +1971,15 @@ pluma_document_search_forward (PlumaDocument *doc,
 
 return found; 
 }
- 
+
+/**
+ * pluma_document_search_backward:
+ * @doc:
+ * @start: (allow-none):
+ * @end: (allow-none):
+ * @match_start: (allow-none):
+ * @match_end: (allow=none):
+ **/
 gboolean
 pluma_document_search_backward (PlumaDocument *doc,
 const GtkTextIter *start,
@@ -2013,6 +2065,7 @@ pluma_document_search_backward (PlumaDocument *doc,
 return found; 
 }
 
+/* FIXME this is an issue for introspection regardning @find */
 gint 
 pluma_document_replace_all (PlumaDocument *doc,
 const gchar *find, 
@@ -2146,6 +2199,11 @@ pluma_document_replace_all (PlumaDocument *doc,
 return cont;
 }
 
+/**
+ * pluma_document_set_language:
+ * @doc:
+ * @lang: (allow-none):
+ **/
 void
 pluma_document_set_language (PlumaDocument *doc, 
 GtkSourceLanguage *lang)
diff --git a/pluma/pluma-encodings-combo-box.c b/pluma/pluma-encodings-combo-box.c
index 2f355424..f4815997 100644
--- a/pluma/pluma-encodings-combo-box.c
+++ b/pluma/pluma-encodings-combo-box.c
@@ -430,6 +430,11 @@ pluma_encodings_combo_box_get_selected_encoding (PlumaEncodingsComboBox *menu)
 return NULL;
 }
 
+/**
+ * pluma_encodings_combo_box_set_selected_encoding:
+ * @menu:
+ * @encoding: (allow-none):
+ **/
 void
 pluma_encodings_combo_box_set_selected_encoding (PlumaEncodingsComboBox *menu,
 const PlumaEncoding *encoding)
diff --git a/pluma/pluma-file-chooser-dialog.c b/pluma/pluma-file-chooser-dialog.c
index 5349cc90..569545a8 100644
--- a/pluma/pluma-file-chooser-dialog.c
+++ b/pluma/pluma-file-chooser-dialog.c
@@ -461,11 +461,13 @@ pluma_file_chooser_dialog_new_valist (const gchar *title,
 
 /**
 * pluma_file_chooser_dialog_new:
- * @title: Title of the dialog, or %NULL
- * @parent: Transient parent of the dialog, or %NULL
+ * @title: (allow-none): Title of the dialog, or %NULL
+ * @parent: (allow-none): Transient parent of the dialog, or %NULL
 * @action: Open or save mode for the dialog
- * @first_button_text: stock ID or text to go in the first button, or %NULL
- * @Varargs: response ID for the first button, then additional (button, id) pairs, ending with %NULL
+ * @first_button_text: (allow-none): stock ID or text to go in
+ * the first button, or %NULL
+ * @Varargs: (allow-none): response ID for the first button, then
+ * additional (button, id) pairs, ending with %NULL
 *
 * Creates a new #PlumaFileChooserDialog. This function is analogous to
 * gtk_dialog_new_with_buttons().
diff --git a/pluma/pluma-message-type.c b/pluma/pluma-message-type.c
index 838dc7d6..f399887b 100644
--- a/pluma/pluma-message-type.c
+++ b/pluma/pluma-message-type.c
@@ -45,6 +45,7 @@ typedef struct
 
 struct _PlumaMessageType
 {
+ /* FIXME this is an issue for introspection */
 gint ref_count;
 
 gchar *object_path;
@@ -121,8 +122,8 @@ pluma_message_type_get_type (void)
 
 /**
 * pluma_message_type_identifier:
- * @object_path: the object path
- * @method: the method
+ * @object_path: (allow-none): the object path
+ * @method: (allow-none): the method
 *
 * Get the string identifier for @method at @object_path.
 *
@@ -138,7 +139,7 @@ pluma_message_type_identifier (const gchar *object_path,
 
 /**
 * pluma_message_type_is_valid_object_path:
- * @object_path: the object path
+ * @object_path: (allow-none): the object path
 *
 * Returns whether @object_path is a valid object path
 *
@@ -226,8 +227,8 @@ pluma_message_type_is_supported (GType type)
 
 /**
 * pluma_message_type_new_valist:
- * @object_path: the object path
- * @method: the method
+ * @object_path: (allow-none): the object path
+ * @method: (allow-none): the method
 * @num_optional: number of optional arguments
 * @var_args: key/gtype pair variable argument list
 *
@@ -267,8 +268,8 @@ pluma_message_type_new_valist (const gchar *object_path,
 
 /**
 * pluma_message_type_new:
- * @object_path: the object path
- * @method: the method
+ * @object_path: (allow-none): the object path
+ * @method: (allow-none): the method
 * @num_optional: number of optional arguments
 * @...: key/gtype pair variable argument list
 *
diff --git a/pluma/pluma-message.c b/pluma/pluma-message.c
index 2e9ffcc3..0e138b04 100644
--- a/pluma/pluma-message.c
+++ b/pluma/pluma-message.c
@@ -266,7 +266,7 @@ pluma_message_get_object_path (PlumaMessage *message)
 /**
 * pluma_message_set:
 * @message: the #PlumaMessage
- * @...: a NULL terminated variable list of key/value pairs
+ * @...: a %NULL terminated variable list of key/value pairs
 *
 * Set values of message arguments. The supplied @var_args should contain
 * pairs of keys and argument values.
@@ -288,7 +288,7 @@ pluma_message_set (PlumaMessage *message,
 /**
 * pluma_message_set_valist:
 * @message: the #PlumaMessage
- * @var_args: a NULL terminated variable list of key/value pairs
+ * @var_args: a %NULL terminated variable list of key/value pairs
 *
 * Set values of message arguments. The supplied @var_args should contain
 * pairs of keys and argument values.
@@ -338,7 +338,7 @@ pluma_message_set_valist (PlumaMessage *message,
 * pluma_message_set_value:
 * @message: the #PlumaMessage
 * @key: the argument key
- * @value: the argument value
+ * @value: (out): the argument value
 *
 * Set value of message argument @key to @value.
 *
@@ -367,8 +367,8 @@ pluma_message_set_value (PlumaMessage *message,
 /**
 * pluma_message_set_valuesv:
 * @message: the #PlumaMessage
- * @keys: keys to set values for
- * @values: values to set
+ * @keys: (array-length=n_values): keys to set values for
+ * @values: (array-length=n_values): values to set
 * @n_values: number of arguments to set values for
 *
 * Set message argument values.
@@ -390,10 +390,11 @@ pluma_message_set_valuesv (PlumaMessage *message,
 }
 }
 
+/* FIXME this is an issue for introspection */
 /**
 * pluma_message_get:
 * @message: the #PlumaMessage
- * @...: a NULL variable argument list of key/value container pairs
+ * @...: a %NULL variable argument list of key/value container pairs
 *
 * Get values of message arguments. The supplied @var_args should contain
 * pairs of keys and pointers to variables which are set to the argument
@@ -416,7 +417,7 @@ pluma_message_get (PlumaMessage *message,
 /**
 * pluma_message_get_valist:
 * @message: the #PlumaMessage
- * @var_args: a NULL variable argument list of key/value container pairs
+ * @var_args: a %NULL variable argument list of key/value container pairs
 *
 * Get values of message arguments. The supplied @var_args should contain
 * pairs of keys and pointers to variables which are set to the argument
@@ -470,7 +471,7 @@ pluma_message_get_valist (PlumaMessage *message,
 * pluma_message_get_value:
 * @message: the #PlumaMessage
 * @key: the argument key
- * @value: value return container
+ * @value: (out): value return container
 *
 * Get the value of a specific message argument. @value will be initialized
 * with the correct type.
diff --git a/pluma/pluma-panel.c b/pluma/pluma-panel.c
index f75e45f9..c3fdc03a 100644
--- a/pluma/pluma-panel.c
+++ b/pluma/pluma-panel.c
@@ -738,9 +738,9 @@ pluma_panel_add_item_with_stock_icon (PlumaPanel *panel,
 * @item: the item to be removed from the panel
 *
 * Removes the widget @item from the panel if it is in the @panel and returns
- * TRUE if there was not any problem.
+ * %TRUE if there was not any problem.
 *
- * Returns: TRUE if it was well removed.
+ * Returns: %TRUE if it was well removed.
 */
 gboolean
 pluma_panel_remove_item (PlumaPanel *panel,
@@ -793,7 +793,7 @@ pluma_panel_remove_item (PlumaPanel *panel,
 *
 * Switches to the page that contains @item.
 *
- * Returns: TRUE if it was activated
+ * Returns: %TRUE if it was activated
 */
 gboolean
 pluma_panel_activate_item (PlumaPanel *panel,
@@ -819,11 +819,11 @@ pluma_panel_activate_item (PlumaPanel *panel,
 /**
 * pluma_panel_item_is_active:
 * @panel: a #PlumaPanel
- * @item: a widget contained in #PlumaPanel
+ * @item: a #GtkWidget
 *
- * Whether @item is the one current active in @panel
+ * Returns whether @item is the active widget in @panel
 *
- * Returns: TRUE if the widget is active
+ * Returns: %TRUE if @item is the active widget
 */
 gboolean
 pluma_panel_item_is_active (PlumaPanel *panel,
diff --git a/pluma/pluma-status-combo-box.c b/pluma/pluma-status-combo-box.c
index e800c406..c5b8ac3c 100644
--- a/pluma/pluma-status-combo-box.c
+++ b/pluma/pluma-status-combo-box.c
@@ -307,12 +307,22 @@ pluma_status_combo_box_init (PlumaStatusComboBox *self)
 }
 
 /* public functions */
+
+/**
+ * pluma_status_combo_box_new:
+ * @label: (allow-none):
+ */
 GtkWidget *
 pluma_status_combo_box_new (const gchar *label)
 {
 return g_object_new (PLUMA_TYPE_STATUS_COMBO_BOX, "label", label, NULL);
 }
 
+/**
+ * pluma_status_combo_box_set_label:
+ * @combo:
+ * @label: (allow-none):
+ */
 void
 pluma_status_combo_box_set_label (PlumaStatusComboBox *combo, 
 const gchar *label)
@@ -341,6 +351,12 @@ item_activated (GtkMenuItem *item,
 pluma_status_combo_box_set_item (combo, item);
 }
 
+/**
+ * pluma_status_combo_box_add_item:
+ * @combo:
+ * @item:
+ * @text: (allow-none):
+ */
 void
 pluma_status_combo_box_add_item (PlumaStatusComboBox *combo,
 GtkMenuItem *item,
@@ -388,6 +404,12 @@ pluma_status_combo_box_get_item_text (PlumaStatusComboBox *combo,
 return ret;
 }
 
+/**
+ * pluma_status_combo_box_set_item_text:
+ * @combo:
+ * @item:
+ * @text: (allow-none):
+ */
 void 
 pluma_status_combo_box_set_item_text (PlumaStatusComboBox *combo,
 GtkMenuItem *item,
diff --git a/pluma/pluma-statusbar.c b/pluma/pluma-statusbar.c
index f1a0fd54..6b31bb5d 100644
--- a/pluma/pluma-statusbar.c
+++ b/pluma/pluma-statusbar.c
@@ -268,6 +268,7 @@ remove_message_timeout (PlumaStatusbar *statusbar)
 return FALSE;
 }
 
+/* FIXME this is an issue for introspection */
 /**
 * pluma_statusbar_flash_message:
 * @statusbar: a #PlumaStatusbar
diff --git a/pluma/pluma-tab.c b/pluma/pluma-tab.c
index b02c10fb..86e1b184 100644
--- a/pluma/pluma-tab.c
+++ b/pluma/pluma-tab.c
@@ -2650,7 +2650,7 @@ pluma_tab_get_auto_save_enabled (PlumaTab *tab)
 **/
 void
 pluma_tab_set_auto_save_enabled (PlumaTab *tab, 
- gboolean enable)
+ gboolean enable)
 {
 PlumaDocument *doc = NULL;
 PlumaLockdownMask lockdown;
@@ -2732,7 +2732,7 @@ pluma_tab_get_auto_save_interval (PlumaTab *tab)
 **/
 void 
 pluma_tab_set_auto_save_interval (PlumaTab *tab, 
- gint interval)
+ gint interval)
 {
 PlumaDocument *doc = NULL;
 
diff --git a/pluma/pluma-utils.c b/pluma/pluma-utils.c
index ddfeee4a..571cf81f 100644
--- a/pluma/pluma-utils.c
+++ b/pluma/pluma-utils.c
@@ -61,7 +61,11 @@
 
 #define STDIN_DELAY_MICROSECONDS 100000
 
-/* Returns true if uri is a file: uri and is not a chained uri */
+/**
+ * pluma_utils_uris_has_file_scheme
+ *
+ * Returns: %TRUE if @uri is a file: uri and is not a chained uri
+ */
 gboolean
 pluma_utils_uri_has_file_scheme (const gchar *uri)
 {
@@ -288,11 +292,12 @@ finally_2:
 }
 
 /**
- * pluma_utils_set_atk_name_description
- * @widget : The Gtk widget for which name/description to be set
- * @name : Atk name string
- * @description : Atk description string
- * Description : This function sets up name and description
+ * pluma_utils_set_atk_name_description:
+ * @widget: The Gtk widget for which name/description to be set
+ * @name: Atk name string
+ * @description: Atk description string
+ *
+ * This function sets up name and description
 * for a specified gtk widget.
 */
 void
@@ -315,10 +320,12 @@ pluma_utils_set_atk_name_description (GtkWidget *widget,
 }
 
 /**
- * pluma_set_atk__relation
- * @obj1,@obj2 : specified widgets.
- * @rel_type : the type of relation to set up.
- * Description : This function establishes atk relation
+ * pluma_set_atk_relation:
+ * @obj1: specified widget.
+ * @obj2: specified widget.
+ * @rel_type: the type of relation to set up.
+ *
+ * This function establishes atk relation
 * between 2 specified widgets.
 */
 void
@@ -693,7 +700,11 @@ pluma_utils_make_valid_utf8 (const char *name)
 return g_string_free (string, FALSE);
 }
 
-/* Note that this function replace home dir with ~ */
+/**
+ * pluma_utils_uri_get_dirname:
+ *
+ * Note: this function replace home dir with ~
+ */
 gchar *
 pluma_utils_uri_get_dirname (const gchar *uri)
 {
@@ -842,7 +853,9 @@ pluma_utils_replace_home_dir_with_tilde (const gchar *uri)
 /* the following two functions are courtesy of galeon */
 
 /**
- * pluma_utils_get_current_workspace: Get the current workspace
+ * pluma_utils_get_current_workspace:
+ *
+ * Get the current workspace
 *
 * Get the currently visible workspace for the #GdkScreen.
 *
@@ -891,7 +904,9 @@ pluma_utils_get_current_workspace (GdkScreen *screen)
 }
 
 /**
- * pluma_utils_get_window_workspace: Get the workspace the window is on
+ * pluma_utils_get_window_workspace:
+ *
+ * Get the workspace the window is on
 *
 * This function gets the workspace that the #GtkWindow is visible on,
 * it returns PLUMA_ALL_WORKSPACES if the window is sticky, or if
@@ -940,7 +955,9 @@ pluma_utils_get_window_workspace (GtkWindow *gtkwindow)
 }
 
 /**
- * pluma_utils_get_current_viewport: Get the current viewport origin
+ * pluma_utils_get_current_viewport:
+ *
+ * Get the current viewport origin
 *
 * Get the currently visible viewport origin for the #GdkScreen.
 *
@@ -1085,21 +1102,22 @@ handle_builder_error (const gchar *message, ...)
 return label;
 }
 
+/* FIXME this is an issue for introspection */
 /**
 * pluma_utils_get_ui_objects:
 * @filename: the path to the gtk builder file
- * @root_objects: a NULL terminated list of root objects to load or NULL to
+ * @root_objects: a %NULL terminated list of root objects to load or NULL to
 * load all objects
 * @error_widget: a pointer were a #GtkLabel
 * @object_name: the name of the first object
 * @...: a pointer were the first object is returned, followed by more
- * name / object pairs and terminated by NULL.
+ * name / object pairs and terminated by %NULL.
 *
 * This function gets the requested objects from a GtkBuilder ui file. In case
- * of error it returns FALSE and sets error_widget to a GtkLabel containing
+ * of error it returns %FALSE and sets error_widget to a GtkLabel containing
 * the error message to display.
 *
- * Returns FALSE if an error occurs, TRUE on success.
+ * Returns: %FALSE if an error occurs, %TRUE on success.
 */
 gboolean
 pluma_utils_get_ui_objects (const gchar *filename,
@@ -1232,7 +1250,7 @@ pluma_utils_make_canonical_uri_from_shell_arg (const gchar *str)
 * pluma_utils_file_has_parent:
 * @gfile: the GFile to check the parent for
 *
- * Return TRUE if the specified gfile has a parent (is not the root), FALSE
+ * Return %TRUE if the specified gfile has a parent (is not the root), %FALSE
 * otherwise
 */
 gboolean
@@ -1359,11 +1377,10 @@ pluma_utils_uri_for_display (const gchar *uri)
 /**
 * pluma_utils_drop_get_uris:
 * @selection_data: the #GtkSelectionData from drag_data_received
- * @info: the info from drag_data_received
 *
 * Create a list of valid uri's from a uri-list drop.
 * 
- * Return value: a string array which will hold the uris or NULL if there 
+ * Return value: a string array which will hold the uris or %NULL if there
 * were no valid uris. g_strfreev should be used when the 
 * string array is no longer used
 */
@@ -1410,26 +1427,27 @@ null_ptr (gchar **ptr)
 /**
 * pluma_utils_decode_uri:
 * @uri: the uri to decode
- * @scheme: return value pointer for the uri's scheme (e.g. http, sftp, ...)
- * @user: return value pointer for the uri user info
- * @port: return value pointer for the uri port
- * @host: return value pointer for the uri host
- * @path: return value pointer for the uri path
+ * @scheme: (allow-none): return value pointer for the uri's
+ * scheme (e.g. http, sftp, ...), or %NULL
+ * @user: (allow-none): return value pointer for the uri user info, or %NULL
+ * @port: (allow-none): return value pointer for the uri port, or %NULL
+ * @host: (allow-none): return value pointer for the uri host, or %NULL
+ * @path: (allow-none): return value pointer for the uri path, or %NULL
 *
 * Parse and break an uri apart in its individual components like the uri
 * scheme, user info, port, host and path. The return value pointer can be
- * NULL to ignore certain parts of the uri. If the function returns TRUE, then
+ * %NULL to ignore certain parts of the uri. If the function returns %TRUE, then
 * all return value pointers should be freed using g_free
 * 
- * Return value: TRUE if the uri could be properly decoded, FALSE otherwise.
+ * Return value: %TRUE if the uri could be properly decoded, %FALSE otherwise.
 */
 gboolean
-pluma_utils_decode_uri (const gchar *uri,
- gchar **scheme,
- gchar **user,
- gchar **host,
- gchar **port,
- gchar **path
+pluma_utils_decode_uri (const gchar *uri,
+ gchar **scheme,
+ gchar **user,
+ gchar **host,
+ gchar **port,
+ gchar **path
 )
 {
 /* Largely copied from glib/gio/gdummyfile.c:_g_decode_uri. This 
diff --git a/pluma/pluma-view.c b/pluma/pluma-view.c
index 55dc9671..a9a1d54a 100644
--- a/pluma/pluma-view.c
+++ b/pluma/pluma-view.c
@@ -463,7 +463,7 @@ pluma_view_focus_out (GtkWidget *widget, GdkEventFocus *event)
 * @doc: a #PlumaDocument
 * 
 * Creates a new #PlumaView object displaying the @doc document. 
- * @doc cannot be NULL.
+ * @doc cannot be %NULL.
 *
 * Return value: a new #PlumaView
 **/
@@ -649,6 +649,7 @@ pluma_view_scroll_to_cursor (PlumaView *view)
 0.0);
 }
 
+/* FIXME this is an issue for introspection */
 /**
 * pluma_view_set_font:
 * @view: a #PlumaView
diff --git a/pluma/pluma-window.c b/pluma/pluma-window.c
index f00f2ac8..5ed3e6e2 100644
--- a/pluma/pluma-window.c
+++ b/pluma/pluma-window.c
@@ -4115,7 +4115,8 @@ add_document (PlumaTab *tab, GList **res)
 * Gets a newly allocated list with all the documents in the window.
 * This list must be freed.
 *
- * Returns: a newly allocated list with all the documents in the window
+ * Returns: (element-type Pluma.Document) (transfer container): a newly
+ * allocated list with all the documents in the window
 */
 GList *
 pluma_window_get_documents (PlumaWindow *window)
@@ -4149,7 +4150,8 @@ add_view (PlumaTab *tab, GList **res)
 *
 * Gets a list with all the views in the window. This list must be freed.
 *
- * Returns: a newly allocated list with all the views in the window
+ * Returns: (element-type Pluma.View) (transfer container): a newly allocated
+ * list with all the views in the window
 */
 GList *
 pluma_window_get_views (PlumaWindow *window)
@@ -4210,7 +4212,7 @@ pluma_window_close_all_tabs (PlumaWindow *window)
 /**
 * pluma_window_close_tabs:
 * @window: a #PlumaWindow
- * @tabs: a list of #PlumaTab
+ * @tabs: (element-type Pluma.Tab): a list of #PlumaTab
 *
 * Closes all tabs specified by @tabs.
 */
@@ -4426,7 +4428,8 @@ _pluma_window_set_default_location (PlumaWindow *window,
 *
 * Gets the list of documents that need to be saved before closing the window.
 *
- * Returns: a list of #PlumaDocument that need to be saved before closing the window
+ * Returns: (element-type Pluma.Document) (transfer container): a list of
+ * #PlumaDocument that need to be saved before closing the window
 */
 GList *
 pluma_window_get_unsaved_documents (PlumaWindow *window)
@@ -4630,7 +4633,7 @@ pluma_window_get_tab_from_location (PlumaWindow *window,
 * Gets the #PlumaMessageBus associated with @window. The returned reference
 * is owned by the window and should not be unreffed.
 *
- * Return value: the #PlumaMessageBus associated with @window
+ * Return value: (transfer none): the #PlumaMessageBus associated with @window
 */
 PlumaMessageBus *
 pluma_window_get_message_bus (PlumaWindow *window)
author	infirit <[email protected]>	2015-09-05 21:06:15 +0200
committer	infirit <[email protected]>	2015-09-05 21:46:09 +0200
commit	3d9e640cc4221a43d214951da5cbdc43c4f55662 (patch)
tree	a4fbe0612956b35a63c1cec927ea9ad7e79bb217
parent	1618c8f7248722265450b11ef48ced34c7a317a5 (diff)
download	pluma-3d9e640cc4221a43d214951da5cbdc43c4f55662.tar.bz2 pluma-3d9e640cc4221a43d214951da5cbdc43c4f55662.tar.xz