[gedit] Fix up the docs and add preliminary GObject Introspection support

[Garrett Regier <gregier src gnome org>]

commit 42a6a8d8d87f32572f56b56a9c4e92f7181d339a
Author: Garrett Regier <alias301 gmail com>
Date:   Sat Jun 12 13:09:13 2010 -0700

    Fix up the docs and add preliminary GObject Introspection support

 gedit/gedit-app.c                 |   11 +++--
 gedit/gedit-commands-file.c       |   18 +++++++-
 gedit/gedit-debug.h               |    1 +
 gedit/gedit-document.c            |   76 +++++++++++++++++++++++++++++++--
 gedit/gedit-encodings-combo-box.c |    5 ++
 gedit/gedit-file-chooser-dialog.c |   10 +++--
 gedit/gedit-message-type.c        |   15 ++++---
 gedit/gedit-message.c             |   17 ++++----
 gedit/gedit-panel.c               |   16 ++++----
 gedit/gedit-status-combo-box.c    |   22 ++++++++++
 gedit/gedit-statusbar.c           |    1 +
 gedit/gedit-tab.c                 |    4 +-
 gedit/gedit-utils.c               |   85 ++++++++++++++++++++++---------------
 gedit/gedit-view.c                |   17 +-------
 gedit/gedit-window.c              |   13 ++++--
 15 files changed, 217 insertions(+), 94 deletions(-)
---
diff --git a/gedit/gedit-app.c b/gedit/gedit-app.c
index 946ac9d..8948350 100644
--- a/gedit/gedit-app.c
+++ b/gedit/gedit-app.c
@@ -711,6 +711,7 @@ gedit_app_create_window_real (GeditApp    *app,
 /**
  * gedit_app_create_window:
  * @app: the #GeditApp
+ * @screen: (allow-none):
  *
  * Create a new #GeditWindow part of @app.
  *
@@ -751,8 +752,8 @@ _gedit_app_restore_window (GeditApp    *app,
  *
  * Returns all the windows currently present in #GeditApp.
  *
- * Return value: the list of #GeditWindows objects. The list
- * should not be freed
+ * Return value: (transfer none): the list of #GeditWindows objects.
+ * The list should not be freed
  */
 const GList *
 gedit_app_get_windows (GeditApp *app)
@@ -894,7 +895,8 @@ _gedit_app_get_window_in_viewport (GeditApp  *app,
  *
  * Returns all the documents currently open in #GeditApp.
  *
- * Return value: a newly allocated list of #GeditDocument objects
+ * Return value: (element-type Gedit.Document) (transfer container):
+ * a newly allocated list of #GeditDocument objects
  */
 GList *
 gedit_app_get_documents	(GeditApp *app)
@@ -923,7 +925,8 @@ gedit_app_get_documents	(GeditApp *app)
  *
  * Returns all the views currently present in #GeditApp.
  *
- * Return value: a newly allocated list of #GeditView objects
+ * Return value: (element-type Gedit.View) (transfer container):
+ * a newly allocated list of #GeditView objects
  */
 GList *
 gedit_app_get_views (GeditApp *app)
diff --git a/gedit/gedit-commands-file.c b/gedit/gedit-commands-file.c
index 44006e9..7f52e24 100644
--- a/gedit/gedit-commands-file.c
+++ b/gedit/gedit-commands-file.c
@@ -292,8 +292,15 @@ load_file_list (GeditWindow         *window,
 
 /**
  * gedit_commands_load_uri:
+ * @window:
+ * @location:
+ * @encoding: (allow-none):
+ * @line_pos:
+ * @column_pos:
  *
- * Do nothing if location does not exist
+ * Ignore non-existing locations
+ *
+ * Returns: (transfer container):
  */
 void
 gedit_commands_load_location (GeditWindow         *window,
@@ -324,8 +331,15 @@ gedit_commands_load_location (GeditWindow         *window,
 
 /**
  * gedit_commands_load_uris:
+ * @window:
+ * @locations: (element-type Glib.File) (transfer none):
+ * @encoding: (allow-none):
+ * @line_pos:
+ * @column_pos:
+ *
+ * Ignore non-existing locations
  *
- * Ignore non-existing locations 
+ * Returns: (transfer container):
  */
 GSList *
 gedit_commands_load_locations (GeditWindow         *window,
diff --git a/gedit/gedit-debug.h b/gedit/gedit-debug.h
index 91db5be..9e00067 100644
--- a/gedit/gedit-debug.h
+++ b/gedit/gedit-debug.h
@@ -60,6 +60,7 @@ typedef enum {
 } GeditDebugSection;
 
 
+/* FIXME this is an issue for introspection */
 #define	DEBUG_VIEW	GEDIT_DEBUG_VIEW,    __FILE__, __LINE__, G_STRFUNC
 #define	DEBUG_SEARCH	GEDIT_DEBUG_SEARCH,  __FILE__, __LINE__, G_STRFUNC
 #define	DEBUG_PRINT	GEDIT_DEBUG_PRINT,   __FILE__, __LINE__, G_STRFUNC
diff --git a/gedit/gedit-document.c b/gedit/gedit-document.c
index 18e58ad..ecbeba2 100644
--- a/gedit/gedit-document.c
+++ b/gedit/gedit-document.c
@@ -1143,6 +1143,11 @@ set_content_type (GeditDocument *doc,
 	}
 }
 
+/**
+ * gedit_document_set_content_type:
+ * @doc:
+ * @content_type: (allow-none):
+ */
 void
 gedit_document_set_content_type (GeditDocument *doc,
                                  const gchar   *content_type)
@@ -1207,7 +1212,12 @@ gedit_document_set_location (GeditDocument *doc,
 	set_content_type (doc, NULL);
 }
 
-/* Never returns NULL */
+/**
+ * gedit_document_get_uri_for_display:
+ * @doc:
+ *
+ * Note: this never returns %NULL.
+ **/
 gchar *
 gedit_document_get_uri_for_display (GeditDocument *doc)
 {
@@ -1224,7 +1234,12 @@ gedit_document_get_uri_for_display (GeditDocument *doc)
 	}
 }
 
-/* Never returns NULL */
+/**
+ * gedit_document_get_short_name_for_display:
+ * @doc:
+ *
+ * Note: this never returns %NULL.
+ **/
 gchar *
 gedit_document_get_short_name_for_display (GeditDocument *doc)
 {
@@ -1245,6 +1260,11 @@ gedit_document_get_short_name_for_display (GeditDocument *doc)
 	}
 }
 
+/**
+ * gedit_document_set_short_name_for_display:
+ * @doc:
+ * @short_name: (allow-none):
+ */
 void
 gedit_document_set_short_name_for_display (GeditDocument *doc,
                                            const gchar   *short_name)
@@ -1265,7 +1285,12 @@ gedit_document_get_content_type (GeditDocument *doc)
  	return g_strdup (doc->priv->content_type);
 }
 
-/* Never returns NULL */
+/**
+ * gedit_document_get_mime_type:
+ * @doc:
+ *
+ * Note: this never returns %NULL.
+ **/
 gchar *
 gedit_document_get_mime_type (GeditDocument *doc)
 {
@@ -1584,6 +1609,14 @@ gedit_document_load_real (GeditDocument       *doc,
 	gedit_document_loader_load (doc->priv->loader);
 }
 
+/**
+ * gedit_document_load_stream:
+ * @doc:
+ * @stream:
+ * @encoding: (allow-none):
+ * @line_pop:
+ * @column_pos:
+ **/
 void
 gedit_document_load_stream (GeditDocument       *doc,
                             GInputStream        *stream,
@@ -1620,7 +1653,7 @@ gedit_document_load_stream (GeditDocument       *doc,
  * gedit_document_load:
  * @doc: the #GeditDocument.
  * @location: the location where to load the document from.
- * @encoding: the #GeditEncoding to encode the document.
+ * @encoding: (allow-none): the #GeditEncoding to encode the document, or %NULL.
  * @line_pos: the line to show.
  * @create: whether the document should be created if it doesn't exist.
  *
@@ -1963,6 +1996,12 @@ compute_num_of_lines (const gchar *text)
 	return n;
 }
 
+/**
+ * gedit_document_set_search_text"
+ * @doc:
+ * @text: (allow-none):
+ * @flags:
+ **/
 void
 gedit_document_set_search_text (GeditDocument *doc,
 				const gchar   *text,
@@ -2025,6 +2064,11 @@ gedit_document_set_search_text (GeditDocument *doc,
 		g_object_notify (G_OBJECT (doc), "can-search-again");
 }
 
+/**
+ * gedit_document_get_search_text:
+ * @doc:
+ * @flags: (allow-none):
+ */
 gchar *
 gedit_document_get_search_text (GeditDocument *doc,
 				guint         *flags)
@@ -2046,6 +2090,14 @@ gedit_document_get_can_search_again (GeditDocument *doc)
 	        (*doc->priv->search_text != '\0'));
 }
 
+/**
+ * gedit_document_search_forward:
+ * @doc:
+ * @start: (allow-none):
+ * @end: (allow-none):
+ * @match_start: (allow-none):
+ * @match_end: (allow=none):
+ **/
 gboolean
 gedit_document_search_forward (GeditDocument     *doc,
 			       const GtkTextIter *start,
@@ -2118,7 +2170,15 @@ gedit_document_search_forward (GeditDocument     *doc,
 	
 	return found;			    
 }
-						 
+
+/**
+ * gedit_document_search_backward:
+ * @doc:
+ * @start: (allow-none):
+ * @end: (allow-none):
+ * @match_start: (allow-none):
+ * @match_end: (allow=none):
+ **/
 gboolean
 gedit_document_search_backward (GeditDocument     *doc,
 				const GtkTextIter *start,
@@ -2192,6 +2252,7 @@ gedit_document_search_backward (GeditDocument     *doc,
 	return found;		      
 }
 
+/* FIXME this is an issue for introspection regardning @find */
 gint 
 gedit_document_replace_all (GeditDocument       *doc,
 			    const gchar         *find, 
@@ -2309,6 +2370,11 @@ gedit_document_replace_all (GeditDocument       *doc,
 	return cont;
 }
 
+/**
+ * gedit_document_set_language:
+ * @doc:
+ * @lang: (allow-none):
+ **/
 void
 gedit_document_set_language (GeditDocument     *doc, 
 			     GtkSourceLanguage *lang)
diff --git a/gedit/gedit-encodings-combo-box.c b/gedit/gedit-encodings-combo-box.c
index a7d403c..f9987c3 100644
--- a/gedit/gedit-encodings-combo-box.c
+++ b/gedit/gedit-encodings-combo-box.c
@@ -446,6 +446,11 @@ gedit_encodings_combo_box_get_selected_encoding (GeditEncodingsComboBox *menu)
 	return NULL;
 }
 
+/**
+ * gedit_encodings_combo_box_set_selected_encoding:
+ * @menu:
+ * @encoding: (allow-none):
+ **/
 void
 gedit_encodings_combo_box_set_selected_encoding (GeditEncodingsComboBox *menu,
 						 const GeditEncoding    *encoding)
diff --git a/gedit/gedit-file-chooser-dialog.c b/gedit/gedit-file-chooser-dialog.c
index 7c50ea2..fe109f1 100644
--- a/gedit/gedit-file-chooser-dialog.c
+++ b/gedit/gedit-file-chooser-dialog.c
@@ -466,11 +466,13 @@ gedit_file_chooser_dialog_new_valist (const gchar          *title,
 
 /**
  * gedit_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 #GeditFileChooserDialog.  This function is analogous to
  * gtk_dialog_new_with_buttons().
diff --git a/gedit/gedit-message-type.c b/gedit/gedit-message-type.c
index 9797696..1087e81 100644
--- a/gedit/gedit-message-type.c
+++ b/gedit/gedit-message-type.c
@@ -67,6 +67,7 @@ typedef struct
 
 struct _GeditMessageType
 {
+	/* FIXME this is an issue for introspection */
 	gint ref_count;
 
 	gchar *object_path;
@@ -143,8 +144,8 @@ gedit_message_type_get_type (void)
 
 /**
  * gedit_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.
  *
@@ -160,7 +161,7 @@ gedit_message_type_identifier (const gchar *object_path,
 
 /**
  * gedit_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
  *
@@ -248,8 +249,8 @@ gedit_message_type_is_supported (GType type)
 
 /**
  * gedit_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
  *
@@ -289,8 +290,8 @@ gedit_message_type_new_valist (const gchar *object_path,
 
 /**
  * gedit_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/gedit/gedit-message.c b/gedit/gedit-message.c
index 39dd53f..3c99da8 100644
--- a/gedit/gedit-message.c
+++ b/gedit/gedit-message.c
@@ -288,7 +288,7 @@ gedit_message_get_object_path (GeditMessage *message)
 /**
  * gedit_message_set:
  * @message: the #GeditMessage
- * @...: 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.
@@ -310,7 +310,7 @@ gedit_message_set (GeditMessage *message,
 /**
  * gedit_message_set_valist:
  * @message: the #GeditMessage
- * @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.
@@ -360,7 +360,7 @@ gedit_message_set_valist (GeditMessage *message,
  * gedit_message_set_value:
  * @message: the #GeditMessage
  * @key: the argument key
- * @value: the argument value
+ * @value: (out): the argument value
  *
  * Set value of message argument @key to @value.
  *
@@ -389,8 +389,8 @@ gedit_message_set_value (GeditMessage *message,
 /**
  * gedit_message_set_valuesv:
  * @message: the #GeditMessage
- * @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.
@@ -412,10 +412,11 @@ gedit_message_set_valuesv (GeditMessage	 *message,
 	}
 }
 
+/* FIXME this is an issue for introspection */
 /**
  * gedit_message_get:
  * @message: the #GeditMessage
- * @...: 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
@@ -438,7 +439,7 @@ gedit_message_get (GeditMessage	*message,
 /**
  * gedit_message_get_valist:
  * @message: the #GeditMessage
- * @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
@@ -492,7 +493,7 @@ gedit_message_get_valist (GeditMessage *message,
  * gedit_message_get_value:
  * @message: the #GeditMessage
  * @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/gedit/gedit-panel.c b/gedit/gedit-panel.c
index bbd2a00..ddc9b5f 100644
--- a/gedit/gedit-panel.c
+++ b/gedit/gedit-panel.c
@@ -678,7 +678,7 @@ item_exists (GeditPanel  *panel,
  * @item: the #GtkWidget to add to the @panel
  * @id: unique name for the new item
  * @display_name: the name to be shown in the @panel
- * @image: the image to be shown in the @panel
+ * @image: (allow-none): the image to be shown in the @panel, or %NULL
  *
  * Adds a new item to the @panel.
  *
@@ -754,7 +754,7 @@ gedit_panel_add_item (GeditPanel  *panel,
  * @item: the #GtkWidget to add to the @panel
  * @id: unique name for the new item
  * @display_name: the name to be shown in the @panel
- * @stock_id: a stock id
+ * @stock_id: (allow-none): a stock id, or %NULL
  *
  * Same as gedit_panel_add_item() but using an image from stock.
  *
@@ -784,9 +784,9 @@ gedit_panel_add_item_with_stock_icon (GeditPanel  *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
 gedit_panel_remove_item (GeditPanel *panel,
@@ -840,7 +840,7 @@ gedit_panel_remove_item (GeditPanel *panel,
  *
  * Switches to the page that contains @item.
  *
- * Returns: TRUE if it was activated
+ * Returns: %TRUE if it was activated
  */
 gboolean
 gedit_panel_activate_item (GeditPanel *panel,
@@ -866,11 +866,11 @@ gedit_panel_activate_item (GeditPanel *panel,
 /**
  * gedit_panel_item_is_active:
  * @panel: a #GeditPanel
- * @item: a widget contained in #GeditPanel
+ * @item: a #GtkWidget
  *
- * Wheter @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
 gedit_panel_item_is_active (GeditPanel *panel,
diff --git a/gedit/gedit-status-combo-box.c b/gedit/gedit-status-combo-box.c
index 9eae04f..3690572 100644
--- a/gedit/gedit-status-combo-box.c
+++ b/gedit/gedit-status-combo-box.c
@@ -343,12 +343,22 @@ gedit_status_combo_box_init (GeditStatusComboBox *self)
 }
 
 /* public functions */
+
+/**
+ * gedit_status_combo_box_new:
+ * @label: (allow-none):
+ */
 GtkWidget *
 gedit_status_combo_box_new (const gchar *label)
 {
 	return g_object_new (GEDIT_TYPE_STATUS_COMBO_BOX, "label", label, NULL);
 }
 
+/**
+ * gedit_status_combo_box_set_label:
+ * @combo:
+ * @label: (allow-none):
+ */
 void
 gedit_status_combo_box_set_label (GeditStatusComboBox *combo, 
 				  const gchar         *label)
@@ -377,6 +387,12 @@ item_activated (GtkMenuItem         *item,
 	gedit_status_combo_box_set_item (combo, item);
 }
 
+/**
+ * gedit_status_combo_box_add_item:
+ * @combo:
+ * @item:
+ * @text: (allow-none):
+ */
 void
 gedit_status_combo_box_add_item (GeditStatusComboBox *combo,
 				 GtkMenuItem         *item,
@@ -424,6 +440,12 @@ gedit_status_combo_box_get_item_text (GeditStatusComboBox *combo,
 	return ret;
 }
 
+/**
+ * gedit_status_combo_box_set_item_text:
+ * @combo:
+ * @item:
+ * @text: (allow-none):
+ */
 void 
 gedit_status_combo_box_set_item_text (GeditStatusComboBox *combo,
 				      GtkMenuItem	  *item,
diff --git a/gedit/gedit-statusbar.c b/gedit/gedit-statusbar.c
index 6366ff6..ae9f427 100644
--- a/gedit/gedit-statusbar.c
+++ b/gedit/gedit-statusbar.c
@@ -348,6 +348,7 @@ remove_message_timeout (GeditStatusbar *statusbar)
   	return FALSE;
 }
 
+/* FIXME this is an issue for introspection */
 /**
  * gedit_statusbar_flash_message:
  * @statusbar: a #GeditStatusbar
diff --git a/gedit/gedit-tab.c b/gedit/gedit-tab.c
index 7e6c9dd..2781e55 100644
--- a/gedit/gedit-tab.c
+++ b/gedit/gedit-tab.c
@@ -2790,7 +2790,7 @@ gedit_tab_get_auto_save_enabled	(GeditTab *tab)
  **/
 void
 gedit_tab_set_auto_save_enabled	(GeditTab *tab, 
-				 gboolean enable)
+				 gboolean  enable)
 {
 	GeditDocument *doc = NULL;
 	GeditLockdownMask lockdown;
@@ -2872,7 +2872,7 @@ gedit_tab_get_auto_save_interval (GeditTab *tab)
  **/
 void 
 gedit_tab_set_auto_save_interval (GeditTab *tab, 
-				  gint interval)
+				  gint      interval)
 {
 	GeditDocument *doc = NULL;
 	
diff --git a/gedit/gedit-utils.c b/gedit/gedit-utils.c
index 54d806f..c475cfa 100644
--- a/gedit/gedit-utils.c
+++ b/gedit/gedit-utils.c
@@ -65,7 +65,10 @@
 
 #define STDIN_DELAY_MICROSECONDS 100000
 
-/* Returns true if location is a file: uri and is not a chained uri */
+/**
+ * gedit_utils_location_has_file_scheme:
+ *
+ * Returns: %TRUE if @location is a file: uri and is not a chained uri */
 gboolean
 gedit_utils_location_has_file_scheme (GFile *location)
 {
@@ -259,11 +262,12 @@ finally_2:
 }
 
 /**
- * gedit_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
+ * gedit_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
@@ -286,10 +290,12 @@ gedit_utils_set_atk_name_description (GtkWidget   *widget,
 }
 
 /**
- * gedit_set_atk__relation
- * @obj1,@obj2 : specified widgets.
- * @rel_type : the type of relation to set up.
- * Description : This function establishes atk relation
+ * gedit_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
@@ -668,7 +674,11 @@ gedit_utils_make_valid_utf8 (const char *name)
 	return g_string_free (string, FALSE);
 }
 
-/* Note that this function replace home dir with ~ */
+/**
+ * gedit_utils_uri_get_dirname:
+ *
+ * Note: this function replace home dir with ~
+ */
 gchar *
 gedit_utils_uri_get_dirname (const gchar *uri)
 {
@@ -817,7 +827,9 @@ gedit_utils_replace_home_dir_with_tilde (const gchar *uri)
 /* the following two functions are courtesy of galeon */
 
 /**
- * gedit_utils_get_current_workspace: Get the current workspace
+ * gedit_utils_get_current_workspace:
+ *
+ * Get the current workspace
  *
  * Get the currently visible workspace for the #GdkScreen.
  *
@@ -866,7 +878,9 @@ gedit_utils_get_current_workspace (GdkScreen *screen)
 }
 
 /**
- * gedit_utils_get_window_workspace: Get the workspace the window is on
+ * gedit_utils_get_window_workspace:
+ *
+ * Get the workspace the window is on
  *
  * This function gets the workspace that the #GtkWindow is visible on,
  * it returns GEDIT_ALL_WORKSPACES if the window is sticky, or if
@@ -915,7 +929,9 @@ gedit_utils_get_window_workspace (GtkWindow *gtkwindow)
 }
 
 /**
- * gedit_utils_get_current_viewport: Get the current viewport origin
+ * gedit_utils_get_current_viewport:
+ *
+ * Get the current viewport origin
  *
  * Get the currently visible viewport origin for the #GdkScreen.
  *
@@ -1090,21 +1106,22 @@ handle_builder_error (const gchar *message, ...)
 	return label;
 }
 
+/* FIXME this is an issue for introspection */
 /**
  * gedit_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
 gedit_utils_get_ui_objects (const gchar  *filename,
@@ -1239,7 +1256,7 @@ gedit_utils_make_canonical_uri_from_shell_arg (const gchar *str)
  * gedit_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
@@ -1363,11 +1380,10 @@ gedit_utils_uri_for_display (GFile *location)
 /**
  * gedit_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
  */
@@ -1412,26 +1428,27 @@ null_ptr (gchar **ptr)
 /**
  * gedit_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
-gedit_utils_decode_uri (const gchar *uri,
-			gchar **scheme,
-			gchar **user,
-			gchar **host,
-			gchar **port,
-			gchar **path
+gedit_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/gedit/gedit-view.c b/gedit/gedit-view.c
index d9cf86d..eeab4ce 100644
--- a/gedit/gedit-view.c
+++ b/gedit/gedit-view.c
@@ -498,7 +498,7 @@ gedit_view_focus_out (GtkWidget *widget, GdkEventFocus *event)
  * @doc: a #GeditDocument
  * 
  * Creates a new #GeditView object displaying the @doc document. 
- * @doc cannot be NULL.
+ * @doc cannot be %NULL.
  *
  * Return value: a new #GeditView
  **/
@@ -684,6 +684,7 @@ gedit_view_scroll_to_cursor (GeditView *view)
 				      0.0);
 }
 
+/* FIXME this is an issue for introspection */
 /**
  * gedit_view_set_font:
  * @view: a #GeditView
@@ -950,26 +951,12 @@ send_focus_change (GtkWidget *widget,
 	GdkEvent *fevent = gdk_event_new (GDK_FOCUS_CHANGE);
 
 	g_object_ref (widget);
-#if !GTK_CHECK_VERSION (2, 21, 0)
-	if (in)
-		GTK_WIDGET_SET_FLAGS (widget, GTK_HAS_FOCUS);
-	else
-		GTK_WIDGET_UNSET_FLAGS (widget, GTK_HAS_FOCUS);
-#endif
 
 	fevent->focus_change.type = GDK_FOCUS_CHANGE;
 	fevent->focus_change.window = g_object_ref (gtk_widget_get_window (widget));
 	fevent->focus_change.in = in;
 
-#if !GTK_CHECK_VERSION (2, 21, 0)
-	gtk_widget_event (widget, fevent);
-  
-	g_object_notify (G_OBJECT (widget), "has-focus");
-
-	g_object_unref (widget);
-#else
 	gtk_widget_send_focus_change (widget, fevent);
-#endif
 
 	gdk_event_free (fevent);
 }
diff --git a/gedit/gedit-window.c b/gedit/gedit-window.c
index 14bb7d0..652ee61 100644
--- a/gedit/gedit-window.c
+++ b/gedit/gedit-window.c
@@ -4487,7 +4487,8 @@ add_document (GeditTab  *tab,
  * 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 Gedit.Document) (transfer container): a newly
+ * allocated list with all the documents in the window
  */
 GList *
 gedit_window_get_documents (GeditWindow *window)
@@ -4522,7 +4523,8 @@ add_view (GeditTab  *tab,
  *
  * 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 Gedit.View) (transfer container): a newly allocated
+ * list with all the views in the window
  */
 GList *
 gedit_window_get_views (GeditWindow *window)
@@ -4586,7 +4588,7 @@ gedit_window_close_all_tabs (GeditWindow *window)
 /**
  * gedit_window_close_tabs:
  * @window: a #GeditWindow
- * @tabs: a list of #GeditTab
+ * @tabs: (element-type Gedit.Tab): a list of #GeditTab
  *
  * Closes all tabs specified by @tabs.
  */
@@ -4801,7 +4803,8 @@ add_unsaved_doc (GeditTab *tab,
  *
  * Gets the list of documents that need to be saved before closing the window.
  *
- * Returns: a list of #GeditDocument that need to be saved before closing the window
+ * Returns: (element-type Gedit.Document) (transfer container): a list of
+ * #GeditDocument that need to be saved before closing the window
  */
 GList *
 gedit_window_get_unsaved_documents (GeditWindow *window)
@@ -5015,7 +5018,7 @@ gedit_window_get_tab_from_location (GeditWindow *window,
  * Gets the #GeditMessageBus associated with @window. The returned reference
  * is owned by the window and should not be unreffed.
  *
- * Return value: the #GeditMessageBus associated with @window
+ * Return value: (transfer none): the #GeditMessageBus associated with @window
  */
 GeditMessageBus	*
 gedit_window_get_message_bus (GeditWindow *window)