introspection: Add many annotations to sources

39 files changed, 602 insertions, 197 deletions

diff --git a/gladeui/glade-adaptor-chooser.c b/gladeui/glade-adaptor-chooser.c
index ebe42bcc..72782616 100644
--- a/gladeui/glade-adaptor-chooser.c
+++ b/gladeui/glade-adaptor-chooser.c
@@ -273,6 +273,11 @@ glade_adaptor_chooser_class_init (GladeAdaptorChooserClass *klass)
 
 /* Public API */
 
+/**
+ * glade_adaptor_chooser_new:
+ *
+ * Returns: (transfer full): A new #GladeAdaptorChooser
+ */
 GtkWidget *
 glade_adaptor_chooser_new ()
 {
@@ -337,6 +342,12 @@ glade_adaptor_chooser_set_project (GladeAdaptorChooser *chooser,
   glade_adaptor_chooser_update_adaptor (chooser);
 }
 
+/**
+ * glade_adaptor_chooser_get_project:
+ * @chooser: a #GladeAdaptorChooser
+ *
+ * Returns: (transfer full): A #GladeProject
+ */
 GladeProject *
 glade_adaptor_chooser_get_project (GladeAdaptorChooser *chooser)
 {
diff --git a/gladeui/glade-adaptor-chooser.h b/gladeui/glade-adaptor-chooser.h
index 6c535ba4..226db8c8 100644
--- a/gladeui/glade-adaptor-chooser.h
+++ b/gladeui/glade-adaptor-chooser.h
@@ -34,9 +34,9 @@ G_DECLARE_FINAL_TYPE (GladeAdaptorChooser, glade_adaptor_chooser, GLADE, ADAPTOR
 
 GtkWidget    *glade_adaptor_chooser_new (void);
 
-void          glade_adaptor_chooser_set_project (GladeAdaptorChooser *bar,
+void          glade_adaptor_chooser_set_project (GladeAdaptorChooser *chooser,
                                                  GladeProject        *project);
-GladeProject *glade_adaptor_chooser_get_project (GladeAdaptorChooser *bar);
+GladeProject *glade_adaptor_chooser_get_project (GladeAdaptorChooser *chooser);
 
 G_END_DECLS
 
diff --git a/gladeui/glade-app.c b/gladeui/glade-app.c
index 24404832..a08cc747 100644
--- a/gladeui/glade-app.c
+++ b/gladeui/glade-app.c
@@ -514,9 +514,9 @@ glade_app_do_event (GdkEvent *event)
 /**
  * glade_app_config_save
  *
- * Saves the GKeyFile to "g_get_user_config_dir()/GLADE_CONFIG_FILENAME"
+ * Saves the #GKeyFile to "g_get_user_config_dir()/GLADE_CONFIG_FILENAME"
  *
- * Return 0 on success.
+ * Returns: 0 on success.
  */
 gint
 glade_app_config_save ()
@@ -626,6 +626,11 @@ glade_app_config_save ()
   return 0;
 }
 
+/**
+ * glade_app_get:
+ *
+ * Returns: (transfer none): the #GladeApp
+ */
 GladeApp *
 glade_app_get (void)
 {
@@ -637,6 +642,12 @@ glade_app_get (void)
   return singleton_app;
 }
 
+/**
+ * glade_app_set_window:
+ * @window: (transfer full): a #GtkWidget
+ *
+ * Set the window of the application
+ */
 void
 glade_app_set_window (GtkWidget *window)
 {
@@ -645,6 +656,12 @@ glade_app_set_window (GtkWidget *window)
   app->priv->window = window;
 }
 
+/**
+ * glade_app_get_catalog:
+ * @name: the name of the catalog
+ *
+ * Returns: (transfer none) (nullable): a #GladeCatalog or %NULL if none is found
+ */
 GladeCatalog *
 glade_app_get_catalog (const gchar *name)
 {
@@ -663,6 +680,16 @@ glade_app_get_catalog (const gchar *name)
   return NULL;
 }
 
+/**
+ * glade_app_get_catalog_version:
+ * @name: the name of the #GladeCatalog
+ * @major: (out) (optional): the major version
+ * @minor: (out) (optional): the minor version
+ *
+ * Returns: %TRUE if the catalog has been found. It is a programming error
+ * to call this function with an unexisting catalog, returns %FALSE in this
+ * case and throws a warning.
+ */
 gboolean
 glade_app_get_catalog_version (const gchar *name, gint *major, gint *minor)
 {
@@ -678,6 +705,11 @@ glade_app_get_catalog_version (const gchar *name, gint *major, gint *minor)
   return TRUE;
 }
 
+/**
+ * glade_app_get_catalogs:
+ *
+ * Returns: (transfer none) (element-type GladeCatalog): a list of #GladeCatalog
+ */
 GList *
 glade_app_get_catalogs (void)
 {
@@ -686,7 +718,11 @@ glade_app_get_catalogs (void)
   return app->priv->catalogs;
 }
 
-
+/**
+ * glade_app_get_window:
+ *
+ * Returns: (transfer none): a #GtkWidget
+ */
 GtkWidget *
 glade_app_get_window (void)
 {
@@ -694,16 +730,22 @@ glade_app_get_window (void)
   return app->priv->window;
 }
 
+/**
+ * glade_app_get_clipboard:
+ *
+ * Returns: (transfer none): a #GladeClipboard
+ */
 GladeClipboard *
 glade_app_get_clipboard (void)
 {
   GladeApp *app = glade_app_get ();
   return app->priv->clipboard;
 }
+
 /**
- * glade_app_get_catalogs:
+ * glade_app_get_projects:
  *
- * Return value: (element-type GladeCatalog): catalogs
+ * Returns: (element-type GladeCatalog) (transfer none): a list of #GladeCatalog
  */
 GList *
 glade_app_get_projects (void)
@@ -712,6 +754,11 @@ glade_app_get_projects (void)
   return app->priv->projects;
 }
 
+/**
+ * glade_app_get_config:
+ *
+ * Returns: (transfer full): a #GKeyFile
+ */
 GKeyFile *
 glade_app_get_config (void)
 {
@@ -759,7 +806,7 @@ glade_app_is_project_loaded (const gchar *project_path)
  *
  * Finds an open project with @path
  *
- * Returns: A #GladeProject, or NULL if no such open project was found
+ * Returns: (nullable) (transfer none): A #GladeProject, or NULL if no such open project was found
  */
 GladeProject *
 glade_app_get_project_by_path (const gchar *project_path)
@@ -792,6 +839,10 @@ glade_app_get_project_by_path (const gchar *project_path)
   return NULL;
 }
 
+/**
+ * glade_app_add_project:
+ * @project: the project to add to the #GladeApp
+ */
 void
 glade_app_add_project (GladeProject *project)
 {
@@ -809,6 +860,10 @@ glade_app_add_project (GladeProject *project)
   app->priv->projects = g_list_append (app->priv->projects, g_object_ref (project));
 }
 
+/**
+ * glade_app_remove_project:
+ * @project: the project to remove from the #GladeApp
+ */
 void
 glade_app_remove_project (GladeProject *project)
 {
@@ -826,8 +881,9 @@ glade_app_remove_project (GladeProject *project)
   g_object_unref (project);
 }
 
-/*
+/**
  * glade_app_set_accel_group:
+ * @accel_group: (transfer full): a #GtkAccelGroup to set
  *
  * Sets @accel_group to app.
  * The acceleration group will made available for editor dialog windows
@@ -844,18 +900,36 @@ glade_app_set_accel_group (GtkAccelGroup *accel_group)
   app->priv->accel_group = accel_group;
 }
 
+/**
+ * glade_app_get_accel_group:
+ *
+ * Returns: (transfer none): the #GtkAccelGroup
+ */
 GtkAccelGroup *
 glade_app_get_accel_group (void)
 {
   return glade_app_get ()->priv->accel_group;
 }
 
+/**
+ * glade_app_new:
+ *
+ * Returns: (transfer full): the #GladeApp
+ */
 GladeApp *
 glade_app_new (void)
 {
   return g_object_new (GLADE_TYPE_APP, NULL);
 }
 
+/**
+ * glade_app_search_docs:
+ * @book: the name of a book
+ * @page: the name of a page
+ * @search: the search query
+ *
+ * Searches for @book, @page and @search in the documentation.
+ */
 void
 glade_app_search_docs (const gchar *book,
                        const gchar *page, 
diff --git a/gladeui/glade-base-editor.c b/gladeui/glade-base-editor.c
index 486218a2..28df0750 100644
--- a/gladeui/glade-base-editor.c
+++ b/gladeui/glade-base-editor.c
@@ -1658,7 +1658,8 @@ glade_base_editor_class_init (GladeBaseEditorClass *klass)
    * Create a child widget here if something else must be done other than
    * calling glade_command_create() such as creating an intermediate parent.
    *
-   * Returns: the newly created #GladeWidget or NULL if child cant be created
+   * Returns: (transfer full) (nullable): the newly created #GladeWidget or
+   * %NULL if child cant be created
    */
   glade_base_editor_signals[SIGNAL_BUILD_CHILD] =
       g_signal_new ("build-child",
@@ -2077,7 +2078,7 @@ glade_base_editor_help (GtkButton *button, gchar *markup)
  *
  * This convenience function create a new dialog window and packs @editor in it.
  *
- * Returns: the newly created window
+ * Returns: (transfer full): the newly created window
  */
 GtkWidget *
 glade_base_editor_pack_new_window (GladeBaseEditor *editor,
diff --git a/gladeui/glade-base-editor.h b/gladeui/glade-base-editor.h
index 5bb42b16..48f0d60e 100644
--- a/gladeui/glade-base-editor.h
+++ b/gladeui/glade-base-editor.h
@@ -49,12 +49,12 @@ struct _GladeBaseEditorClass
 {
   GtkBoxClass parent_class;
 
-  void          (*child_selected)   (GladeBaseEditor *, GladeWidget *);
-  gboolean      (*change_type)      (GladeBaseEditor *, GladeWidget *, GType);
-  gchar *       (*get_display_name) (GladeBaseEditor *, GladeWidget *);
-  GladeWidget * (*build_child)      (GladeBaseEditor *, GladeWidget *, GType);
-  gboolean      (*delete_child)     (GladeBaseEditor *, GladeWidget *, GladeWidget *);
-  gboolean      (*move_child)       (GladeBaseEditor *, GladeWidget *, GladeWidget *);
+  void          (*child_selected)   (GladeBaseEditor *editor, GladeWidget *gchild);
+  gboolean      (*change_type)      (GladeBaseEditor *editor, GladeWidget *gchild, GType type);
+  gchar *       (*get_display_name) (GladeBaseEditor *editor, GladeWidget *gchild);
+  GladeWidget * (*build_child)      (GladeBaseEditor *editor, GladeWidget *parent, GType type);
+  gboolean      (*delete_child)     (GladeBaseEditor *editor, GladeWidget *parent, GladeWidget *gchild);
+  gboolean      (*move_child)       (GladeBaseEditor *editor, GladeWidget *gparent, GladeWidget *gchild);
 
   void   (* glade_reserved1)   (void);
   void   (* glade_reserved2)   (void);
diff --git a/gladeui/glade-builtins.c b/gladeui/glade-builtins.c
index d6144827..74721dd7 100644
--- a/gladeui/glade-builtins.c
+++ b/gladeui/glade-builtins.c
@@ -359,6 +359,11 @@ G_GNUC_END_IGNORE_DEPRECATIONS
   return etype;
 }
 
+/**
+ * glade_standard_stock_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing a list of builtin stock item
+ */
 GParamSpec *
 glade_standard_stock_spec (void)
 {
@@ -367,6 +372,11 @@ glade_standard_stock_spec (void)
                             GLADE_TYPE_STOCK, 0, G_PARAM_READWRITE);
 }
 
+/**
+ * glade_standard_stock_image_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing a list of builtin stock image
+ */
 GParamSpec *
 glade_standard_stock_image_spec (void)
 {
@@ -481,6 +491,11 @@ glade_param_objects_get_type (void)
   return objects_type;
 }
 
+/**
+ * glade_param_spec_objects:
+ *
+ * Returns: (transfer full): a #GParamSpec describing a list of #GObject
+ */
 GParamSpec *
 glade_param_spec_objects (const gchar * name,
                           const gchar * nick,
@@ -508,9 +523,14 @@ glade_param_spec_objects_get_type (GladeParamSpecObjects * pspec)
   return pspec->type;
 }
 
-/* This was developed for the purpose of holding a list
+/**
+ * glade_standard_objects_spec:
+ *
+ * This was developed for the purpose of holding a list
  * of 'targets' in an AtkRelation (we are setting it up
  * as a property)
+ *
+ * Returns: (transfer full): a #GParamSpec describing a list of #GObject
  */
 GParamSpec *
 glade_standard_objects_spec (void)
@@ -520,7 +540,11 @@ glade_standard_objects_spec (void)
                                    G_TYPE_OBJECT, G_PARAM_READWRITE);
 }
 
-/* Pixbuf Type */
+/**
+ * glade_standard_pixbuf_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing a #GdkPixbuf
+ */
 GParamSpec *
 glade_standard_pixbuf_spec (void)
 {
@@ -530,7 +554,11 @@ glade_standard_pixbuf_spec (void)
                               G_PARAM_READWRITE);
 }
 
-/* GdkColor */
+/**
+ * glade_standard_gdkcolor_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing a #GdkColor
+ */
 GParamSpec *
 glade_standard_gdkcolor_spec (void)
 {
@@ -542,6 +570,12 @@ glade_standard_gdkcolor_spec (void)
 /****************************************************************
  *                    Basic types follow                        *
  ****************************************************************/
+
+/**
+ * glade_standard_int_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing an int
+ */
 GParamSpec *
 glade_standard_int_spec (void)
 {
@@ -550,6 +584,11 @@ glade_standard_int_spec (void)
                            G_MININT, G_MAXINT, 0, G_PARAM_READWRITE);
 }
 
+/**
+ * glade_standard_uint_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing an uint
+ */
 GParamSpec *
 glade_standard_uint_spec (void)
 {
@@ -558,6 +597,11 @@ glade_standard_uint_spec (void)
                             0, G_MAXUINT, 0, G_PARAM_READWRITE);
 }
 
+/**
+ * glade_standard_string_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing a string
+ */
 GParamSpec *
 glade_standard_string_spec (void)
 {
@@ -565,6 +609,11 @@ glade_standard_string_spec (void)
                               _("An entry"), "", G_PARAM_READWRITE);
 }
 
+/**
+ * glade_standard_strv_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing an array of strings
+ */
 GParamSpec *
 glade_standard_strv_spec (void)
 {
@@ -572,6 +621,11 @@ glade_standard_strv_spec (void)
                              "String array", G_TYPE_STRV, G_PARAM_READWRITE);
 }
 
+/**
+ * glade_standard_float_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing a float
+ */
 GParamSpec *
 glade_standard_float_spec (void)
 {
@@ -580,6 +634,11 @@ glade_standard_float_spec (void)
                              0.0F, G_MAXFLOAT, 0.0F, G_PARAM_READWRITE);
 }
 
+/**
+ * glade_standard_boolean_spec:
+ *
+ * Returns: (transfer full): a #GParamSpec describing a boolean
+ */
 GParamSpec *
 glade_standard_boolean_spec (void)
 {
diff --git a/gladeui/glade-catalog.c b/gladeui/glade-catalog.c
index 78e68535..c0a27343 100644
--- a/gladeui/glade-catalog.c
+++ b/gladeui/glade-catalog.c
@@ -818,7 +818,7 @@ glade_catalog_get_minor_version (GladeCatalog *catalog)
  * glade_catalog_get_targets:
  * @catalog: a catalog object
  * 
- * Returns: the list of suitable version targets.
+ * Returns: (transfer none) (element-type GladeTargetableVersion): the list of suitable version targets.
  */
 GList *
 glade_catalog_get_targets (GladeCatalog *catalog)
@@ -832,7 +832,7 @@ glade_catalog_get_targets (GladeCatalog *catalog)
  * glade_catalog_get_widget_groups:
  * @catalog: a catalog object
  * 
- * Returns: the list of widget groups (palette)
+ * Returns: (transfer none) (element-type GladeWidgetGroup): the list of widget groups (palette)
  */
 GList *
 glade_catalog_get_widget_groups (GladeCatalog *catalog)
@@ -846,7 +846,7 @@ glade_catalog_get_widget_groups (GladeCatalog *catalog)
  * glade_catalog_get_adaptors:
  * @catalog: a catalog object
  * 
- * Returns: the list of widget class adaptors
+ * Returns: (transfer none) (element-type GladeWidgetAdaptor): the list of widget class adaptors
  */
 GList *
 glade_catalog_get_adaptors (GladeCatalog *catalog)
@@ -942,7 +942,7 @@ glade_widget_group_get_expanded (GladeWidgetGroup *group)
  * glade_widget_group_get_adaptors:
  * @group: a widget group
  * 
- * Returns: a list of class adaptors in the palette
+ * Returns: (transfer none) (element-type GladeWidgetAdaptor): a list of class adaptors in the palette
  */
 const GList *
 glade_widget_group_get_adaptors (GladeWidgetGroup *group)
diff --git a/gladeui/glade-clipboard.c b/gladeui/glade-clipboard.c
index 2ed4fc68..a77c72b5 100644
--- a/gladeui/glade-clipboard.c
+++ b/gladeui/glade-clipboard.c
@@ -131,6 +131,12 @@ glade_clipboard_get_has_selection (GladeClipboard *clipboard)
   return clipboard->priv->has_selection;
 }
 
+/**
+ * glade_clipboard_widgets:
+ * @clipboard: a #GladeClipboard
+ * 
+ * Returns: (element-type GladeWidget) (transfer none): a #GList of #GladeWidgets
+ */
 GList *
 glade_clipboard_widgets (GladeClipboard *clipboard)
 {
@@ -154,7 +160,7 @@ glade_clipboard_new (void)
 /**
  * glade_clipboard_add:
  * @clipboard: a #GladeClipboard
- * @widgets: a #GList of #GladeWidgets
+ * @widgets: (element-type GladeWidget): a #GList of #GladeWidgets
  * 
  * Adds @widgets to @clipboard.
  * This increases the reference count of each #GladeWidget in @widgets.
diff --git a/gladeui/glade-command.c b/gladeui/glade-command.c
index a664e3bb..b3469d18 100644
--- a/gladeui/glade-command.c
+++ b/gladeui/glade-command.c
@@ -1791,14 +1791,14 @@ glade_command_add_remove_collapse (GladeCommand *this_cmd,
 /**
  * glade_command_create:
  * @adaptor: A #GladeWidgetAdaptor
- * @parent: (allow-none): the parent #GladeWidget to add the new widget to.
- * @placeholder: (allow-none): the placeholder which will be substituted by the widget
+ * @parent: (nullable): the parent #GladeWidget to add the new widget to.
+ * @placeholder: (nullable): the placeholder which will be substituted by the widget
  * @project: the project his widget belongs to.
  *
  * Creates a new widget using @adaptor and put in place of the @placeholder
  * in the @project
  *
- * Returns: the newly created widget.
+ * Returns: (transfer full): the newly created widget.
  */
 GladeWidget *
 glade_command_create (GladeWidgetAdaptor *adaptor,
diff --git a/gladeui/glade-command.h b/gladeui/glade-command.h
index 8b2f0975..7012fb3e 100644
--- a/gladeui/glade-command.h
+++ b/gladeui/glade-command.h
@@ -50,10 +50,10 @@ struct _GladeCommandClass
 {
   GObjectClass parent_class;
 
-  gboolean (* execute)     (GladeCommand *this_cmd);
-  gboolean (* undo)        (GladeCommand *this_cmd);
-  gboolean (* unifies)     (GladeCommand *this_cmd, GladeCommand *other_cmd);
-  void     (* collapse)    (GladeCommand *this_cmd, GladeCommand *other_cmd);
+  gboolean (* execute)     (GladeCommand *command);
+  gboolean (* undo)        (GladeCommand *command);
+  gboolean (* unifies)     (GladeCommand *command, GladeCommand *other);
+  void     (* collapse)    (GladeCommand *command, GladeCommand *other);
 
   void   (* glade_reserved1)   (void);
   void   (* glade_reserved2)   (void);
diff --git a/gladeui/glade-design-view.c b/gladeui/glade-design-view.c
index a9995387..d6beede1 100644
--- a/gladeui/glade-design-view.c
+++ b/gladeui/glade-design-view.c
@@ -773,6 +773,12 @@ glade_design_view_class_init (GladeDesignViewClass *klass)
 
 /* Public API */
 
+/**
+ * glade_design_view_get_project:
+ * @view: A #GladeDesignView
+ *
+ * Returns: (transfer none): a #GladeProject
+ */
 GladeProject *
 glade_design_view_get_project (GladeDesignView *view)
 {
@@ -782,6 +788,12 @@ glade_design_view_get_project (GladeDesignView *view)
 
 }
 
+/**
+ * glade_design_view_new:
+ * @project: A #GladeProject
+ *
+ * Returns: (transfer full): a new #GladeDesignView
+ */
 GtkWidget *
 glade_design_view_new (GladeProject *project)
 {
@@ -794,6 +806,12 @@ glade_design_view_new (GladeProject *project)
   return GTK_WIDGET (view);
 }
 
+/**
+ * glade_design_view_get_from_project:
+ * @project: A #GladeProject
+ *
+ * Returns: (transfer none) (nullable): a #GladeDesignView
+ */
 GladeDesignView *
 glade_design_view_get_from_project (GladeProject *project)
 {
diff --git a/gladeui/glade-editable.c b/gladeui/glade-editable.c
index ecb603e5..dfad7aee 100644
--- a/gladeui/glade-editable.c
+++ b/gladeui/glade-editable.c
@@ -152,7 +152,6 @@ glade_editable_load (GladeEditable *editable, GladeWidget *widget)
   g_object_set_qdata (G_OBJECT (editable), glade_editable_loading_quark, GINT_TO_POINTER (FALSE));
 }
 
-
 /**
  * glade_editable_set_show_name:
  * @editable: A #GladeEditable
@@ -175,6 +174,12 @@ glade_editable_set_show_name (GladeEditable *editable, gboolean show_name)
     iface->set_show_name (editable, show_name);
 }
 
+/**
+ * glade_editable_loaded_widget:
+ * @editable: A #GladeEditable
+ *
+ * Returns: (transfer none) (nullable): a #GladeWidget or %NULL if the editable hasn't been loaded
+ */
 GladeWidget *
 glade_editable_loaded_widget (GladeEditable *editable)
 {
diff --git a/gladeui/glade-editor-property.c b/gladeui/glade-editor-property.c
index 2739e514..e4dc39d9 100644
--- a/gladeui/glade-editor-property.c
+++ b/gladeui/glade-editor-property.c
@@ -290,6 +290,12 @@ glade_editor_property_get_disable_check (GladeEditorProperty *eprop)
   return eprop->priv->disable_check;
 }
 
+/**
+ * glade_editor_property_get_item_label:
+ * @eprop: a #GladeEditorProperty
+ *
+ * Returns: (transfer none): the #GladePropertyLabel
+ */
 GtkWidget *
 glade_editor_property_get_item_label  (GladeEditorProperty *eprop)
 {
@@ -317,6 +323,12 @@ glade_editor_property_get_pclass (GladeEditorProperty *eprop)
   return eprop->priv->klass;
 }
 
+/**
+ * glade_editor_property_get_property:
+ * @eprop: a #GladeEditorProperty
+ *
+ * Returns: (transfer none): the #GladeProperty
+ */
 GladeProperty *
 glade_editor_property_get_property (GladeEditorProperty *eprop)
 {
diff --git a/gladeui/glade-editor-property.h b/gladeui/glade-editor-property.h
index 1f8f2b3b..a90a893b 100644
--- a/gladeui/glade-editor-property.h
+++ b/gladeui/glade-editor-property.h
@@ -83,10 +83,10 @@ struct _GladeEditorProperty
 struct _GladeEditorPropertyClass {
   GtkBoxClass  parent_class;
 
-  void        (* load)          (GladeEditorProperty *, GladeProperty *);
-  GtkWidget  *(* create_input)  (GladeEditorProperty *);
-  void        (* commit)        (GladeEditorProperty *, GValue *);
-  void       *(* changed)       (GladeEditorProperty *, GladeProperty *);
+  void        (* load)          (GladeEditorProperty *eprop, GladeProperty *property);
+  GtkWidget  *(* create_input)  (GladeEditorProperty *eprop);
+  void        (* commit)        (GladeEditorProperty *eprop, GValue *value);
+  void       *(* changed)       (GladeEditorProperty *eprop, GladeProperty *property);
 
   void   (* glade_reserved1)   (void);
   void   (* glade_reserved2)   (void);
diff --git a/gladeui/glade-editor.c b/gladeui/glade-editor.c
index 4032377a..450df1b1 100644
--- a/gladeui/glade-editor.c
+++ b/gladeui/glade-editor.c
@@ -1320,7 +1320,7 @@ editor_widget_name_changed (GladeWidget *widget,
  * This convenience function creates a new dialog window to edit @widget
  * specifically.
  *
- * Returns: the newly created dialog window
+ * Returns: (transfer full): the newly created dialog window
  */
 GtkWidget *
 glade_editor_dialog_for_widget (GladeWidget *widget)
diff --git a/gladeui/glade-inspector.c b/gladeui/glade-inspector.c
index f640c19e..e8b4a5a5 100644
--- a/gladeui/glade-inspector.c
+++ b/gladeui/glade-inspector.c
@@ -1064,9 +1064,9 @@ glade_inspector_set_project (GladeInspector *inspector, GladeProject *project)
  * glade_inspector_get_project:
  * @inspector: a #GladeInspector
  * 
- * Note that the method does not ref the returned #GladeProject. 
+ * Note that the method does not ref the returned #GladeProject.
  *
- * Returns: A #GladeProject
+ * Returns: (transfer none): A #GladeProject
  */
 GladeProject *
 glade_inspector_get_project (GladeInspector *inspector)
@@ -1082,7 +1082,7 @@ glade_inspector_get_project (GladeInspector *inspector)
  * 
  * Returns the selected items in the inspector. 
  *
- * Returns: A #GList
+ * Returns: (transfer container) (element-type GladeWidget): A #GList of #GladeWidget
  */
 GList *
 glade_inspector_get_selected_items (GladeInspector *inspector)
@@ -1123,7 +1123,7 @@ glade_inspector_get_selected_items (GladeInspector *inspector)
  * 
  * Creates a new #GladeInspector
  * 
- * Returns: a new #GladeInspector
+ * Returns: (transfer full): a new #GladeInspector
  */
 GtkWidget *
 glade_inspector_new (void)
@@ -1137,7 +1137,7 @@ glade_inspector_new (void)
  *
  * Creates a new #GladeInspector with @project
  * 
- * Returns: a new #GladeInspector
+ * Returns: (transfer full): a new #GladeInspector
  */
 GtkWidget *
 glade_inspector_new_with_project (GladeProject *project)
diff --git a/gladeui/glade-named-icon-chooser-dialog.c b/gladeui/glade-named-icon-chooser-dialog.c
index f95e9326..05ad8670 100644
--- a/gladeui/glade-named-icon-chooser-dialog.c
+++ b/gladeui/glade-named-icon-chooser-dialog.c
@@ -1729,10 +1729,10 @@ glade_named_icon_chooser_dialog_new_valist (const gchar *title,
 
 /**
  * glade_named_icon_chooser_dialog_new:
- * @title: Title of the dialog, or %NULL
- * @parent: Transient parent of the dialog, or %NULL,
- * @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)
+ * @title: (nullable): Title of the dialog, or %NULL
+ * @parent: (nullable): Transient parent of the dialog, or %NULL,
+ * @first_button_text: (nullable): stock ID or text to go in the first button, or %NULL
+ * @...: response ID for the first button, then additional (button, id)
  *   pairs, ending with %NULL
  *
  * Creates a new #GladeNamedIconChooserDialog.  This function is analogous to
diff --git a/gladeui/glade-object-stub.c b/gladeui/glade-object-stub.c
index c17177c2..b993652c 100644
--- a/gladeui/glade-object-stub.c
+++ b/gladeui/glade-object-stub.c
@@ -193,19 +193,6 @@ glade_object_stub_get_property (GObject    *object,
     }
 }
 
-static GType
-glade_xml_node_get_type (void)
-{
-  static GType type = 0;
-
-  if (type) return type;
-
-  type = g_boxed_type_register_static ("GladeXmlNode",
-                                       (GBoxedCopyFunc) glade_xml_node_copy,
-                                       (GBoxedFreeFunc) glade_xml_node_delete);
-  return type;
-}
-
 static void
 glade_object_stub_class_init (GladeObjectStubClass *klass)
 {
diff --git a/gladeui/glade-palette.c b/gladeui/glade-palette.c
index db41b2f3..6366a61e 100644
--- a/gladeui/glade-palette.c
+++ b/gladeui/glade-palette.c
@@ -686,7 +686,12 @@ glade_palette_new (void)
   return GTK_WIDGET (palette);
 }
 
-
+/**
+ * glade_palette_get_project:
+ * @palette: a #GladePalette
+ *
+ * Returns: (transfer none): a #GladeProject
+ */
 GladeProject *
 glade_palette_get_project (GladePalette *palette)
 {
@@ -884,7 +889,7 @@ glade_palette_get_show_selector_button (GladePalette *palette)
  * glade_palette_get_tool_palette:
  * @palette: a #GladePalette
  *
- * Returns: the GtkToolPalette associated to this palette.
+ * Returns: (transfer none): the GtkToolPalette associated to this palette.
  */
 GtkToolPalette *
 glade_palette_get_tool_palette (GladePalette *palette)
diff --git a/gladeui/glade-placeholder.c b/gladeui/glade-placeholder.c
index a26fc15b..ced5b92b 100644
--- a/gladeui/glade-placeholder.c
+++ b/gladeui/glade-placeholder.c
@@ -633,7 +633,7 @@ glade_placeholder_class_init (GladePlaceholderClass *klass)
 /**
  * glade_placeholder_new:
  * 
- * Returns: a new #GladePlaceholder cast as a #GtkWidget
+ * Returns: (transfer full): a new #GladePlaceholder
  */
 GtkWidget *
 glade_placeholder_new (void)
@@ -641,6 +641,12 @@ glade_placeholder_new (void)
   return g_object_new (GLADE_TYPE_PLACEHOLDER, NULL);
 }
 
+/**
+ * glade_placeholder_get_project:
+ * @placeholder: a #GladePlaceholder
+ * 
+ * Returns: (transfer none) (nullable): a #GladeProject
+ */
 GladeProject *
 glade_placeholder_get_project (GladePlaceholder *placeholder)
 {
@@ -649,6 +655,12 @@ glade_placeholder_get_project (GladePlaceholder *placeholder)
   return parent ? glade_widget_get_project (parent) : NULL;
 }
 
+/**
+ * glade_placeholder_get_parent:
+ * @placeholder: a #GladePlaceholder
+ * 
+ * Returns: (transfer none) (nullable): a #GladeProject
+ */
 GladeWidget *
 glade_placeholder_get_parent (GladePlaceholder *placeholder)
 {
@@ -666,6 +678,12 @@ glade_placeholder_get_parent (GladePlaceholder *placeholder)
   return parent;
 }
 
+/**
+ * glade_placeholder_packing_actions:
+ * @placeholder: a #GladePlaceholder
+ * 
+ * Returns: (transfer none) (element-type GladeWidgetAction): a list of #GladeWidgetAction
+ */
 GList *
 glade_placeholder_packing_actions (GladePlaceholder *placeholder)
 {
diff --git a/gladeui/glade-project.c b/gladeui/glade-project.c
index a5bf8fdb..987476fa 100644
--- a/gladeui/glade-project.c
+++ b/gladeui/glade-project.c
@@ -2250,8 +2250,8 @@ glade_project_load_from_file (GladeProject *project, const gchar *path)
  * 
  * Opens a project at the given path.
  *
- * Returns: a new #GladeProject for the opened project on success, %NULL on 
- *          failure
+ * Returns: (transfer full) (nullable): a new #GladeProject for the opened project on success,
+ *          %NULL on failure
  */
 GladeProject *
 glade_project_load (const gchar *path)
@@ -2897,7 +2897,7 @@ sync_project_resource_path (GladeProject *project)
 }
 
 /**
- * glade_project_save:
+ * glade_project_save_verify:
  * @project: a #GladeProject
  * @path: location to save glade file
  * @flags: the #GladeVerifyFlags to warn about
@@ -3681,7 +3681,8 @@ glade_project_verify_project_for_ui (GladeProject *project)
  * 
  * Searches under @ancestor in @project looking for a #GladeWidget named @name.
  * 
- * Returns: a pointer to the widget, %NULL if the widget does not exist
+ * Returns: (transfer none) (nullable): a pointer to the widget,
+ * %NULL if the widget does not exist
  */
 GladeWidget *
 glade_project_get_widget_by_name (GladeProject *project, const gchar *name)
@@ -3886,6 +3887,13 @@ glade_project_set_widget_name (GladeProject *project,
   glade_project_widget_changed (project, widget);
 }
 
+/**
+ * glade_project_check_reordered:
+ * @project: a #GladeProject
+ * @parent: the parent #GladeWidget
+ * @old_order: (element-type GObject): the old order to compare with
+ *
+ */
 void
 glade_project_check_reordered (GladeProject *project,
                                GladeWidget  *parent,
@@ -4265,6 +4273,12 @@ glade_project_set_template (GladeProject *project, GladeWidget *widget)
     }
 }
 
+/**
+ * glade_project_get_template:
+ * @project: a #GladeProject
+ * 
+ * Returns: (transfer none): a #GladeWidget
+ */
 GladeWidget *
 glade_project_get_template (GladeProject *project)
 {
@@ -4273,6 +4287,11 @@ glade_project_get_template (GladeProject *project)
   return project->priv->template;
 }
 
+/**
+ * glade_project_set_add_item:
+ * @project: a #GladeProject
+ * @adaptor: (transfer full): a #GladeWidgetAdaptor
+ */
 void
 glade_project_set_add_item (GladeProject *project, GladeWidgetAdaptor *adaptor)
 {
@@ -4290,6 +4309,12 @@ glade_project_set_add_item (GladeProject *project, GladeWidgetAdaptor *adaptor)
     }
 }
 
+/**
+ * glade_project_get_add_item:
+ * @project: a #GladeProject
+ * 
+ * Returns: (transfer none): a #GladeWidgetAdaptor
+ */
 GladeWidgetAdaptor *
 glade_project_get_add_item (GladeProject *project)
 {
@@ -4584,7 +4609,8 @@ glade_project_selection_set (GladeProject *project,
  * glade_project_selection_get:
  * @project: a #GladeProject
  *
- * Returns: a #GList containing the #GtkWidget items currently selected in @project
+ * Returns: (transfer none) (element-type GtkWidget): a #GList containing
+ * the #GtkWidget items currently selected in @project
  */
 GList *
 glade_project_selection_get (GladeProject *project)
@@ -4598,8 +4624,8 @@ glade_project_selection_get (GladeProject *project)
  * glade_project_required_libs:
  * @project: a #GladeProject
  *
- * Returns: a #GList of allocated strings which are the names
- * of the required catalogs for this project
+ * Returns: (transfer full) (element-type utf8): a #GList of allocated strings
+ * which are the names of the required catalogs for this project
  */
 GList *
 glade_project_required_libs (GladeProject *project)
@@ -4659,7 +4685,7 @@ glade_project_undo (GladeProject *project)
 }
 
 /**
- * glade_project_undo:
+ * glade_project_redo:
  * @project: a #GladeProject
  * 
  * Redoes a #GladeCommand in this project.
@@ -4677,7 +4703,7 @@ glade_project_redo (GladeProject *project)
  * 
  * Gets the next undo item on @project's command stack.
  *
- * Returns: the #GladeCommand
+ * Returns: (transfer none): the #GladeCommand
  */
 GladeCommand *
 glade_project_next_undo_item (GladeProject *project)
@@ -4692,7 +4718,7 @@ glade_project_next_undo_item (GladeProject *project)
  * 
  * Gets the next redo item on @project's command stack.
  *
- * Returns: the #GladeCommand
+ * Returns: (transfer none): the #GladeCommand
  */
 GladeCommand *
 glade_project_next_redo_item (GladeProject *project)
@@ -4795,7 +4821,7 @@ redo_item_activated (GtkMenuItem *item, GladeProject *project)
  *
  * Creates a menu of the undo items in the project stack
  *
- * Returns: A newly created menu
+ * Returns: (transfer full): A newly created menu
  */
 GtkWidget *
 glade_project_undo_items (GladeProject *project)
@@ -4833,7 +4859,7 @@ glade_project_undo_items (GladeProject *project)
  *
  * Creates a menu of the undo items in the project stack
  *
- * Returns: A newly created menu
+ * Returns: (transfer full): A newly created menu
  */
 GtkWidget *
 glade_project_redo_items (GladeProject *project)
@@ -4978,10 +5004,10 @@ glade_project_get_file_mtime (GladeProject *project)
 }
 
 /**
- * glade_projects_get_objects:
+ * glade_project_get_objects:
  * @project: a GladeProject
  *
- * Returns: List of all objects in this project
+ * Returns: (transfer none) (element-type GObject): List of all objects in this project
  */
 const GList *
 glade_project_get_objects (GladeProject *project)
@@ -5045,7 +5071,8 @@ glade_project_display_dependencies (GladeProject *project)
  * glade_project_toplevels:
  * @project: a #GladeProject
  *
- * Returns: a #GList containing the #GtkWidget toplevel items in @project
+ * Returns: (transfer none) (element-type GtkWidget): a #GList containing
+ * the #GtkWidget toplevel items in @project
  */
 GList *
 glade_project_toplevels (GladeProject *project)
diff --git a/gladeui/glade-project.h b/gladeui/glade-project.h
index 9ec350a4..6568b900 100644
--- a/gladeui/glade-project.h
+++ b/gladeui/glade-project.h
@@ -94,16 +94,16 @@ struct _GladeProjectClass
   GObjectClass parent_class;
 
   void          (*add_object)          (GladeProject *project,
-                                        GladeWidget  *widget);
+                                        GladeWidget  *object);
   void          (*remove_object)       (GladeProject *project,
-                                        GladeWidget  *widget);
+                                        GladeWidget  *object);
 
   void          (*undo)                (GladeProject *project);
   void          (*redo)                (GladeProject *project);
   GladeCommand *(*next_undo_item)      (GladeProject *project);
   GladeCommand *(*next_redo_item)      (GladeProject *project);
   void          (*push_undo)           (GladeProject *project,
-                                        GladeCommand *command);
+                                        GladeCommand *cmd);
 
   void          (*changed)             (GladeProject *project,
                                         GladeCommand *command,
diff --git a/gladeui/glade-property-class.c b/gladeui/glade-property-class.c
index caa62fd8..cd0369b7 100644
--- a/gladeui/glade-property-class.c
+++ b/gladeui/glade-property-class.c
@@ -1205,6 +1205,11 @@ glade_property_class_is_visible (GladePropertyClass *klass)
   return klass->visible;
 }
 
+/**
+ * glade_property_class_set_adaptor:
+ * @property_class: A #GladePropertyClass
+ * @adaptor: (transfer full): A #GladeWidgetAdaptor
+ */
 void
 glade_property_class_set_adaptor (GladePropertyClass *property_class,
                                   GladeWidgetAdaptor *adaptor)
@@ -1214,6 +1219,12 @@ glade_property_class_set_adaptor (GladePropertyClass *property_class,
   property_class->adaptor = adaptor;
 }
 
+/**
+ * glade_property_class_get_adaptor:
+ * @property_class: A #GladePropertyClass
+ *
+ * Returns: (transfer none): The #GladeWidgetAdaptor associated with the @property_class
+ */
 GladeWidgetAdaptor *
 glade_property_class_get_adaptor (GladePropertyClass *property_class)
 {
@@ -1222,6 +1233,12 @@ glade_property_class_get_adaptor (GladePropertyClass *property_class)
   return property_class->adaptor;
 }
 
+/**
+ * glade_property_class_get_pspec:
+ * @property_class: A #GladePropertyClass
+ *
+ * Returns: (transfer none): The #GParamSpec associated with the @property_class
+ */
 GParamSpec *
 glade_property_class_get_pspec (GladePropertyClass *property_class)
 {
@@ -1230,6 +1247,11 @@ glade_property_class_get_pspec (GladePropertyClass *property_class)
   return property_class->pspec;
 }
 
+/**
+ * glade_property_class_set_pspec:
+ * @property_class: A #GladePropertyClass
+ * @pspec: (transfer full): A #GParamSpec
+ */
 void
 glade_property_class_set_pspec (GladePropertyClass *property_class,
                                 GParamSpec         *pspec)
@@ -1666,7 +1688,7 @@ gpc_read_displayable_values_from_node (GladeXmlNode       *node,
  *
  * Creates and appropriate GtkAdjustment for use in the editor
  *
- * Returns: An appropriate #GtkAdjustment for use in the Property editor
+ * Returns: (transfer full): An appropriate #GtkAdjustment for use in the Property editor
  */
 GtkAdjustment *
 glade_property_class_make_adjustment (GladePropertyClass *property_class)
@@ -2301,11 +2323,15 @@ glade_property_class_compare (GladePropertyClass *klass,
   return retval;
 }
 
-/*
-  This function assignes "weight" to each property in its natural order staring from 1.
-  If parent is 0 weight will be set for every GladePropertyClass in the list.
-  This function will not override weight if it is already set (weight >= 0.0)
-*/
+/**
+ * glade_property_class_set_weights:
+ * @properties: (element-type GladePropertyClass): a list of #GladePropertyClass
+ * @parent: the #GType of the parent
+ *
+ * This function assignes "weight" to each property in its natural order staring from 1.
+ * If parent is 0 weight will be set for every #GladePropertyClass in the list.
+ * This function will not override weight if it is already set (weight >= 0.0)
+ */
 void
 glade_property_class_set_weights (GList **properties, GType parent)
 {
diff --git a/gladeui/glade-property-class.h b/gladeui/glade-property-class.h
index b87edcf7..6d9f4c52 100644
--- a/gladeui/glade-property-class.h
+++ b/gladeui/glade-property-class.h
@@ -19,8 +19,8 @@ G_BEGIN_DECLS
 
 /**
  * GLADE_PROPERTY_CLASS_IS_TYPE:
- * gpc: A #GladePropertyClass
- * type: The #GladeEditorPageType to query
+ * @gpc: A #GladePropertyClass
+ * @type: The #GladeEditorPageType to query
  *
  * Checks if @gpc is good to be loaded as @type
  */
diff --git a/gladeui/glade-property-label.c b/gladeui/glade-property-label.c
index cb4d24f4..5fb71789 100644
--- a/gladeui/glade-property-label.c
+++ b/gladeui/glade-property-label.c
@@ -708,6 +708,12 @@ glade_property_label_set_property (GladePropertyLabel *label,
     }
 }
 
+/**
+ * glade_property_label_get_property:
+ * @label: a #GladePropertyLabel
+ *
+ * Returns: (transfer none): A #GladeProperty
+ */
 GladeProperty *
 glade_property_label_get_property (GladePropertyLabel *label)
 {
diff --git a/gladeui/glade-property.c b/gladeui/glade-property.c
index ed061577..5c9aa73e 100644
--- a/gladeui/glade-property.c
+++ b/gladeui/glade-property.c
@@ -820,7 +820,7 @@ glade_property_new (GladePropertyClass *klass,
  * @template_prop: A #GladeProperty
  * @widget: A #GladeWidget
  *
- * Returns: A newly duplicated property based on the new widget
+ * Returns: (transfer full): A newly duplicated property based on the new widget
  */
 GladeProperty *
 glade_property_dup (GladeProperty *template_prop, GladeWidget *widget)
@@ -1607,6 +1607,11 @@ glade_property_make_string (GladeProperty *property)
                                                        property->priv->value);
 }
 
+/**
+ * glade_property_set_widget:
+ * @property: A #GladeProperty
+ * @widget: (transfer full): a #GladeWidget
+ */
 void
 glade_property_set_widget (GladeProperty *property,
                            GladeWidget   *widget)
@@ -1616,6 +1621,12 @@ glade_property_set_widget (GladeProperty *property,
   property->priv->widget = widget;
 }
 
+/**
+ * glade_property_get_widget:
+ * @property: A #GladeProperty
+ *
+ * Returns: (transfer none): a #GladeWidget
+ */
 GladeWidget *
 glade_property_get_widget (GladeProperty *property)
 {
diff --git a/gladeui/glade-property.h b/gladeui/glade-property.h
index 667f84a6..112f39d8 100644
--- a/gladeui/glade-property.h
+++ b/gladeui/glade-property.h
@@ -39,17 +39,17 @@ struct _GladePropertyKlass
   GObjectClass  parent_class;
 
   /* Class methods */
-  GladeProperty *         (* dup)                   (GladeProperty *, GladeWidget *);
-  gboolean                (* equals_value)          (GladeProperty *, const GValue *);
-  gboolean                (* set_value)             (GladeProperty *, const GValue *);
-  void                    (* get_value)             (GladeProperty *, GValue *);
-  void                    (* sync)                  (GladeProperty *);
-  void                    (* load)                  (GladeProperty *);
+  GladeProperty *         (* dup)                   (GladeProperty *template_prop, GladeWidget *widget);
+  gboolean                (* equals_value)          (GladeProperty *property, const GValue *value);
+  gboolean                (* set_value)             (GladeProperty *property, const GValue *value);
+  void                    (* get_value)             (GladeProperty *property, GValue *value);
+  void                    (* sync)                  (GladeProperty *property);
+  void                    (* load)                  (GladeProperty *property);
 
   /* Signals */
-  void             (* value_changed)         (GladeProperty *, GValue *, GValue *);
-  void             (* tooltip_changed)       (GladeProperty *, const gchar *, 
-                                              const gchar   *, const gchar *);
+  void             (* value_changed)         (GladeProperty *property, GValue *old_value, GValue *new_value);
+  void             (* tooltip_changed)       (GladeProperty *property, const gchar *tooltip, 
+                                              const gchar   *insensitive_tooltip, const gchar *support_warning);
   void   (* glade_reserved1)   (void);
   void   (* glade_reserved2)   (void);
   void   (* glade_reserved3)   (void);
diff --git a/gladeui/glade-signal-class.c b/gladeui/glade-signal-class.c
index af02908d..96cb1660 100644
--- a/gladeui/glade-signal-class.c
+++ b/gladeui/glade-signal-class.c
@@ -100,6 +100,12 @@ glade_signal_class_update_from_node (GladeSignalClass *signal_class,
                                     signal_class->deprecated);
 }
 
+/**
+ * glade_signal_class_get_adaptor:
+ * @signal_class: a #GladeSignalClass
+ *
+ * Returns: (transfer none): a #GladeWidgetAdaptor
+ */
 GladeWidgetAdaptor *
 glade_signal_class_get_adaptor (const GladeSignalClass *signal_class)
 {
diff --git a/gladeui/glade-signal-editor.c b/gladeui/glade-signal-editor.c
index 97b19a56..b02907f1 100644
--- a/gladeui/glade-signal-editor.c
+++ b/gladeui/glade-signal-editor.c
@@ -1198,6 +1198,12 @@ glade_signal_editor_devhelp_cell_data_func (GtkTreeViewColumn *column,
     }
 }
 
+/**
+ * glade_signal_editor_get_widget:
+ * @editor: a #GladeSignalEditor
+ *
+ * Returns: (transfer none): a #GladeWidget
+ */
 GladeWidget*
 glade_signal_editor_get_widget (GladeSignalEditor *editor)
 {
@@ -1475,6 +1481,7 @@ glade_signal_editor_class_init (GladeSignalEditorClass *klass)
   /**
    * GladeSignalEditor::signal-activated:
    * @signal_editor: the object which received the signal
+   * @signal: the #GladeSignal that is activated
    *
    * Emitted when a item is activated in the GladeInspector.
    */
@@ -1492,11 +1499,10 @@ glade_signal_editor_class_init (GladeSignalEditorClass *klass)
    * GladeSignalEditor::callback-suggestions:
    * @editor: the object which received the signal
    * @signal: the #GladeSignal that needs callbacks suggestions
-   * @suggestions: Return
    *
    * Emitted when the editor needs to show a list of callbacks suggestions to the user.
    * 
-   * Returns wheter or not the event was handled.
+   * Returns: (transfer full): an array of string suggestions
    */
   glade_signal_editor_signals[CALLBACK_SUGGESTIONS] =
     g_signal_new ("callback-suggestions",
@@ -1512,11 +1518,10 @@ glade_signal_editor_class_init (GladeSignalEditorClass *klass)
    * GladeSignalEditor::detail-suggestions:
    * @editor: the object which received the signal
    * @signal: the #GladeSignal that needs callbacks suggestions
-   * @suggestions: Return
    *
    * Emitted when the editor needs to show a list of detail suggestions to the user.
    * 
-   * Returns wheter or not the event was handled.
+   * Returns: (transfer full): an array of string suggestions
    */
   glade_signal_editor_signals[DETAIL_SUGGESTIONS] =
     g_signal_new ("detail-suggestions",
@@ -1526,8 +1531,7 @@ glade_signal_editor_class_init (GladeSignalEditorClass *klass)
                   _glade_strv_handled_accumulator,
                   NULL, _glade_marshal_BOXED__OBJECT,
                   G_TYPE_STRV, 1,
-                  GLADE_TYPE_SIGNAL);   
-  
+                  GLADE_TYPE_SIGNAL);
 
   g_object_class_install_property (object_class,
                                    PROP_GLADE_WIDGET,
diff --git a/gladeui/glade-signal-model.c b/gladeui/glade-signal-model.c
index 0fc13177..9e9b1b6a 100644
--- a/gladeui/glade-signal-model.c
+++ b/gladeui/glade-signal-model.c
@@ -190,13 +190,15 @@ glade_signal_model_class_init (GladeSignalModelClass *klass)
                                                          G_PARAM_CONSTRUCT_ONLY | G_PARAM_WRITABLE));
 }
 
-/*
+/**
  * glade_signal_model_new:
- * @widget: The GladeWidget the signals belong to
+ * @widget: The #GladeWidget the signals belong to
  * @signals: The signals of the #GladeWidget
  *
- * Creates a new GladeSignalModel object to show and edit the
+ * Creates a new #GladeSignalModel object to show and edit the
  * signals of a widgets in a GtkTreeView
+ *
+ * Returns: (transfer full): a new #GladeSignalModel
  */
 
 GtkTreeModel *
diff --git a/gladeui/glade-signal.c b/gladeui/glade-signal.c
index b56868a9..19d0c62c 100644
--- a/gladeui/glade-signal.c
+++ b/gladeui/glade-signal.c
@@ -284,7 +284,7 @@ glade_signal_equal (const GladeSignal *sig1, const GladeSignal *sig2)
  * glade_signal_clone:
  * @signal: a #GladeSignal
  *
- * Returns: a new #GladeSignal with the same attributes as @signal
+ * Returns: (transfer full): a new #GladeSignal with the same attributes as @signal
  */
 GladeSignal *
 glade_signal_clone (const GladeSignal *signal)
@@ -369,7 +369,7 @@ glade_signal_write (GladeSignal     *signal,
  *
  * Reads and creates a ner #GladeSignal based on @node
  *
- * Returns: A newly created #GladeSignal
+ * Returns: (transfer full): A newly created #GladeSignal
  */
 GladeSignal *
 glade_signal_read (GladeXmlNode *node, GladeWidgetAdaptor *adaptor)
diff --git a/gladeui/glade-utils.c b/gladeui/glade-utils.c
index c5111c5b..3d5cadfc 100644
--- a/gladeui/glade-utils.c
+++ b/gladeui/glade-utils.c
@@ -150,7 +150,7 @@ glade_util_get_type_from_name (const gchar *name, gboolean have_func)
  * glade_utils_get_pspec_from_funcname:
  * @funcname: the symbol name of a function to generate a #GParamSpec
  *
- * Returns: A #GParamSpec created by the delagate function
+ * Returns: (nullable) (transfer full): A #GParamSpec created by the delegate function
  *          specified by @funcname
  */
 GParamSpec *
@@ -461,8 +461,8 @@ G_GNUC_END_IGNORE_DEPRECATIONS
  * @parent: a parent #GtkWindow for the dialog
  * @action: a #GladeUtilFileDialogType to say if the dialog will open or save
  *
- * Returns: a "glade file" file chooser dialog. The caller is responsible 
- *          for showing the dialog
+ * Returns: (transfer full): a "glade file" file chooser dialog. The caller is
+ *          responsible for showing the dialog
  */
 GtkWidget *
 glade_util_file_dialog_new (const gchar *title,
@@ -645,7 +645,7 @@ gtk_container_children_callback (GtkWidget *widget, gpointer client_data)
  * as it used _forall() instead of _foreach() (and the GTK+ version
  * of this function is simply not exposed).
  *
- * Returns: a #GList giving the contents of @container
+ * Returns: (element-type GtkWidget) (transfer container): a #GList giving the contents of @container
  */
 GList *
 glade_util_container_get_all_children (GtkContainer *container)
@@ -774,10 +774,10 @@ glade_util_find_iter_by_widget (GtkTreeModel *model,
 }
 
 /**
- * glade_util_purify_list:
+ * glade_util_purify_list: (skip)
  * @list: A #GList
  *
- * Returns: A newly allocated version of @list with no 
+ * Returns: (transfer full): A newly allocated version of @list with no 
  *          duplicate data entries
  */
 GList *
@@ -795,11 +795,11 @@ glade_util_purify_list (GList * list)
 }
 
 /**
- * glade_util_added_in_list:
+ * glade_util_added_in_list: (skip)
  * @old_list: the old #GList
  * @new_list: the new #GList
  *
- * Returns: A newly allocated #GList of elements that
+ * Returns: (transfer full): A newly allocated #GList of elements that
  *          are in @new but not in @old
  *
  */
@@ -818,11 +818,11 @@ glade_util_added_in_list (GList *old_list, GList *new_list)
 }
 
 /**
- * glade_util_removed_from_list:
+ * glade_util_removed_from_list: (skip)
  * @old_list: the old #GList
  * @new_list: the new #GList
  *
- * Returns: A newly allocated #GList of elements that
+ * Returns: (transfer full): A newly allocated #GList of elements that
  *          are in @old no longer in @new
  *
  */
@@ -1069,7 +1069,7 @@ glade_util_have_devhelp (void)
  *
  * Creates an image displaying the devhelp icon.
  *
- * Returns: a #GtkImage
+ * Returns: (transfer full): a #GtkImage
  */
 GtkWidget *
 glade_util_get_devhelp_icon (GtkIconSize size)
@@ -1150,6 +1150,12 @@ glade_util_search_devhelp (const gchar *book,
     g_free (search_comm);
 }
 
+/**
+ * glade_util_get_placeholder_from_pointer:
+ * @container: a #GtkContainer
+ *
+ * Returns: (transfer none): a #GtkWidget
+ */
 GtkWidget *
 glade_util_get_placeholder_from_pointer (GtkContainer *container)
 {
@@ -1663,7 +1669,7 @@ glade_utils_string_from_value (const GValue *value)
  * Creates a liststore suitable for comboboxes and such to 
  * chose from a variety of types.
  *
- * Returns: A new #GtkListStore
+ * Returns: (transfer full): A new #GtkListStore
  */
 GtkListStore *
 glade_utils_liststore_from_enum_type (GType enum_type, gboolean include_empty)
@@ -1881,6 +1887,8 @@ draw_pointer (cairo_t *cr)
  *
  * Render an icon representing the pointer mode.
  * Best view with sizes bigger than GTK_ICON_SIZE_LARGE_TOOLBAR.
+ *
+ * Returns: (transfer full): the rendered #GdkPixbuf
  */ 
 GdkPixbuf *
 glade_utils_pointer_mode_render_icon (GladePointerMode mode, GtkIconSize size)
diff --git a/gladeui/glade-widget-action.c b/gladeui/glade-widget-action.c
index 5e2ee1f8..0484345c 100644
--- a/gladeui/glade-widget-action.c
+++ b/gladeui/glade-widget-action.c
@@ -54,6 +54,7 @@ struct _GladeWidgetActionPrivate
 static GParamSpec *properties[N_PROPERTIES];
 
 G_DEFINE_TYPE_WITH_PRIVATE (GladeWidgetAction, glade_widget_action, G_TYPE_OBJECT);
+G_DEFINE_BOXED_TYPE (GWActionClass, glade_widget_action_class, glade_widget_action_class_clone, glade_widget_action_class_free);
 
 static void
 glade_widget_action_init (GladeWidgetAction *object)
@@ -247,6 +248,12 @@ glade_widget_action_get_visible (GladeWidgetAction *action)
   return action->priv->visible;
 }
 
+/**
+ * glade_widget_action_get_children:
+ * @action: a #GladeWidgetAction
+ *
+ * Returns: (transfer none) (element-type GWActionClass): a list of #GWActionClass
+ */
 GList *
 glade_widget_action_get_children (GladeWidgetAction *action)
 {
diff --git a/gladeui/glade-widget-adaptor.c b/gladeui/glade-widget-adaptor.c
index a39b0dd0..91b052f4 100644
--- a/gladeui/glade-widget-adaptor.c
+++ b/gladeui/glade-widget-adaptor.c
@@ -290,7 +290,11 @@ glade_widget_adaptor_get_parent_adaptor_by_type (GType adaptor_type)
   return NULL;
 }
 
-/* XXX DOCME
+/**
+ * glade_widget_adaptor_get_parent_adaptor:
+ * @adaptor: a #GladeWidgetAdaptor
+ *
+ * Returns: (transfer none): the parent #GladeWidgetAdaptor according to @adaptor type
  */
 GladeWidgetAdaptor *
 glade_widget_adaptor_get_parent_adaptor (GladeWidgetAdaptor *adaptor)
@@ -1791,7 +1795,7 @@ glade_widget_adaptor_get_name (GladeWidgetAdaptor *adaptor)
  * glade_widget_adaptor_get_display_name
  * @adaptor: a #GladeWidgetAdaptor
  *
- * Returns the name of the adaptor without GWA_INSTANTIABLE_PREFIX
+ * Returns: the name of the adaptor without %GWA_INSTANTIABLE_PREFIX
  */
 G_CONST_RETURN gchar *
 glade_widget_adaptor_get_display_name (GladeWidgetAdaptor *adaptor)
@@ -1852,6 +1856,12 @@ glade_widget_adaptor_get_book (GladeWidgetAdaptor *adaptor)
   return adaptor->priv->book;
 }
 
+/**
+ * glade_widget_adaptor_get_properties:
+ * @adaptor: A #GladeWidgetAdaptor
+ *
+ * Returns: (transfer none) (element-type GladePropertyClass): a list of #GladePropertyClass
+ */
 G_CONST_RETURN GList *
 glade_widget_adaptor_get_properties (GladeWidgetAdaptor *adaptor)
 {
@@ -1860,6 +1870,12 @@ glade_widget_adaptor_get_properties (GladeWidgetAdaptor *adaptor)
   return adaptor->priv->properties;
 }
 
+/**
+ * glade_widget_adaptor_get_packing_props:
+ * @adaptor: A #GladeWidgetAdaptor
+ *
+ * Returns: (transfer none) (element-type GladePropertyClass): a list of #GladePropertyClass
+ */
 G_CONST_RETURN GList *
 glade_widget_adaptor_get_packing_props (GladeWidgetAdaptor *adaptor)
 {
@@ -1868,6 +1884,12 @@ glade_widget_adaptor_get_packing_props (GladeWidgetAdaptor *adaptor)
   return adaptor->priv->packing_props;
 }
 
+/**
+ * glade_widget_adaptor_get_signals:
+ * @adaptor: A #GladeWidgetAdaptor
+ *
+ * Returns: (transfer none) (element-type GladeSignalClass): a list of #GladeSignalClass
+ */
 G_CONST_RETURN GList *
 glade_widget_adaptor_get_signals (GladeWidgetAdaptor *adaptor)
 {
@@ -1887,7 +1909,8 @@ accum_adaptor (gpointer key, GladeWidgetAdaptor *adaptor, GList **list)
  *
  * Compiles a list of all registered adaptors.
  *
- * Returns: A newly allocated #GList which must be freed with g_list_free()
+ * Returns: (transfer container) (element-type GladeWidgetAdaptor): A newly allocated #GList which
+ * must be freed with g_list_free()
  */
 GList *
 glade_widget_adaptor_list_adaptors (void)
@@ -2686,6 +2709,8 @@ generate_deprecated_icon (const gchar *icon_name)
  * the closest parent adaptor (parent class adapters must be creates/registerd
  * prior to child classes, otherwise inheritance wont work) and parses in
  * the relevent catalog info.
+ *
+ * Returns: (transfer full): a newly allocated #GladeWidgetAdaptor
  */
 GladeWidgetAdaptor *
 glade_widget_adaptor_from_catalog (GladeCatalog *catalog,
@@ -2959,7 +2984,7 @@ glade_widget_adaptor_from_catalog (GladeCatalog *catalog,
  * A convenienve function to create a #GladeWidget of the prescribed type
  * for internal widgets.
  *
- * Returns: a freshly created #GladeWidget wrapper object for the
+ * Returns: (transfer full): a freshly created #GladeWidget wrapper object for the
  *          @internal_object of name @internal_name
  */
 GladeWidget *
@@ -3013,7 +3038,24 @@ glade_widget_adaptor_create_internal (GladeWidget      *parent,
  * Note that the widget class must be fed twice; once as the
  * leading arg... and also as the property for the #GladeWidget
  *
- * this macro returns the newly created #GladeWidget
+ * Returns: (transfer full): the newly created #GladeWidget
+ */
+
+/**
+ * glade_widget_adaptor_create_widget_real:
+ * @query: whether to display query dialogs if
+ *         applicable to the class
+ * @first_property: the first property of @...
+ * @...: a %NULL terminated list of string/value pairs of #GladeWidget 
+ *       properties
+ *
+ * The macro glade_widget_adaptor_create_widget() uses this function
+ * glade_widget_adaptor_create_widget_real(@query, "adaptor", adaptor, @...)
+ *
+ * Use glade_widget_adaptor_create_widget() in C as this function is mostly
+ * available for languages where macros are not available.
+ *
+ * Returns: (transfer full): the newly created #GladeWidget
  */
 GladeWidget *
 glade_widget_adaptor_create_widget_real (gboolean     query,
@@ -3065,8 +3107,8 @@ glade_widget_adaptor_create_widget_real (gboolean     query,
  * glade_widget_adaptor_get_by_name:
  * @name: name of the widget class (for instance: GtkButton)
  *
- * Returns: an existing #GladeWidgetAdaptor with the name equaling @name,
- *          or %NULL if such a class doesn't exist
+ * Returns: (transfer none) (nullable): an existing #GladeWidgetAdaptor with the
+ *          name equaling @name, or %NULL if such a class doesn't exist
  **/
 GladeWidgetAdaptor *
 glade_widget_adaptor_get_by_name (const gchar *name)
@@ -3084,8 +3126,8 @@ glade_widget_adaptor_get_by_name (const gchar *name)
  * glade_widget_adaptor_get_by_type:
  * @type: the #GType of an object class
  *
- * Returns: an existing #GladeWidgetAdaptor with the type equaling @type,
- *          or %NULL if such a class doesn't exist
+ * Returns: (transfer none) (nullable): an existing #GladeWidgetAdaptor with the
+ *          type equaling @type, or %NULL if such a class doesn't exist
  **/
 GladeWidgetAdaptor *
 glade_widget_adaptor_get_by_type (GType type)
@@ -3105,7 +3147,7 @@ glade_widget_adaptor_get_by_type (GType type)
  * this function will search for the specific parent adaptor class which
  * originally introduced @pspec.
  *
- * Returns: the closest #GladeWidgetAdaptor in the ancestry to @adaptor
+ * Returns: (transfer none): the closest #GladeWidgetAdaptor in the ancestry to @adaptor
  *          which is responsable for introducing @pspec.
  **/
 GladeWidgetAdaptor *
@@ -3273,7 +3315,7 @@ glade_widget_adaptor_default_params (GladeWidgetAdaptor *adaptor,
  * a #GladeWidget of the said @adaptor. (provided for language 
  * bindings that may need to construct a wrapper object).
  *
- * Returns: A newly created #GObject
+ * Returns: (transfer full): A newly created #GObject
  */
 GObject *
 glade_widget_adaptor_construct_object (GladeWidgetAdaptor *adaptor,
@@ -3381,7 +3423,7 @@ glade_widget_adaptor_post_create (GladeWidgetAdaptor *adaptor,
  *
  * Retrieves the internal object @internal_name from @object
  *
- * Returns: The internal #GObject
+ * Returns: (transfer none) (nullable): The internal #GObject
  */
 GObject *
 glade_widget_adaptor_get_internal_child (GladeWidgetAdaptor *adaptor,
@@ -3580,7 +3622,7 @@ glade_widget_adaptor_remove (GladeWidgetAdaptor *adaptor,
  *
  * Lists the children of @container.
  *
- * Returns: A #GList of children
+ * Returns: (transfer container) (element-type GObject): A #GList of children
  */
 GList *
 glade_widget_adaptor_get_children (GladeWidgetAdaptor *adaptor,
@@ -4057,7 +4099,7 @@ glade_widget_adaptor_pack_action_remove (GladeWidgetAdaptor *adaptor,
  *
  * Create a list of actions.
  *
- * Returns: a new list of GladeWidgetAction.
+ * Returns: (transfer full) (element-type GladeWidgetAction): a new list of GladeWidgetAction.
  */
 GList *
 glade_widget_adaptor_actions_new (GladeWidgetAdaptor *adaptor)
@@ -4083,7 +4125,7 @@ glade_widget_adaptor_actions_new (GladeWidgetAdaptor *adaptor)
  *
  * Create a list of packing actions.
  *
- * Returns: a new list of GladeWidgetAction.
+ * Returns: (transfer full) (element-type GladeWidgetAction): a new list of GladeWidgetAction.
  */
 GList *
 glade_widget_adaptor_pack_actions_new (GladeWidgetAdaptor *adaptor)
@@ -4159,7 +4201,7 @@ glade_widget_adaptor_child_action_activate (GladeWidgetAdaptor *adaptor,
  * This delagate function is used to create dynamically customized
  * submenus. Called only for actions that dont have children.
  *
- * Returns: A newly created #GtkMenu or %NULL
+ * Returns: (transfer full) (nullable): A newly created #GtkMenu or %NULL
  */
 GtkWidget *
 glade_widget_adaptor_action_submenu (GladeWidgetAdaptor *adaptor,
@@ -4331,7 +4373,7 @@ glade_widget_adaptor_write_child (GladeWidgetAdaptor *adaptor,
  * 
  * Creates a GladeEditorProperty to edit @klass
  *
- * Returns: A newly created #GladeEditorProperty
+ * Returns: (transfer full): A newly created #GladeEditorProperty
  */
 GladeEditorProperty *
 glade_widget_adaptor_create_eprop (GladeWidgetAdaptor *adaptor,
@@ -4364,7 +4406,7 @@ glade_widget_adaptor_create_eprop (GladeWidgetAdaptor *adaptor,
  * 
  * Creates a #GladeEditorProperty to edit #GladePropertyClass @name in @adaptor
  *
- * Returns: A newly created #GladeEditorProperty
+ * Returns: (transfer full): A newly created #GladeEditorProperty
  */
 GladeEditorProperty *
 glade_widget_adaptor_create_eprop_by_name (GladeWidgetAdaptor *adaptor,
@@ -4422,7 +4464,7 @@ glade_widget_adaptor_string_from_value (GladeWidgetAdaptor *adaptor,
  * 
  * Looks up signal class @name on @adaptor.
  *
- * Returns: a #GladeSignalClass or %NULL
+ * Returns: (nullable) (transfer none): a #GladeSignalClass or %NULL
  */
 GladeSignalClass *
 glade_widget_adaptor_get_signal_class (GladeWidgetAdaptor *adaptor,
@@ -4454,7 +4496,7 @@ glade_widget_adaptor_get_signal_class (GladeWidgetAdaptor *adaptor,
  * editor page is layed out (note that editor widgets are created
  * on demand and not at startup).
  *
- * Returns: A new #GladeEditable widget
+ * Returns: (transfer full): A new #GladeEditable widget
  */
 GladeEditable *
 glade_widget_adaptor_create_editable (GladeWidgetAdaptor *adaptor,
diff --git a/gladeui/glade-widget-adaptor.h b/gladeui/glade-widget-adaptor.h
index 359757ce..f42d071e 100644
--- a/gladeui/glade-widget-adaptor.h
+++ b/gladeui/glade-widget-adaptor.h
@@ -337,21 +337,21 @@ typedef gboolean (* GladeChildVerifyPropertyFunc) (GladeWidgetAdaptor *adaptor,
 /**
  * GladeAddChildVerifyFunc:
  * @adaptor: A #GladeWidgetAdaptor
- * @parent: A #GObject container
+ * @container: A #GObject container
  * @child: A #GObject child
  * @user_feedback: whether a notification dialog should be
  * presented in the case that the child cannot not be added.
  *
- * Checks whether @child can be added to @parent.
+ * Checks whether @child can be added to @container.
  *
  * If @user_feedback is %TRUE and @child cannot be
  * added then this shows a notification dialog to the user 
  * explaining why.
  *
- * Returns: whether @child can be added to @parent.
+ * Returns: whether @child can be added to @container.
  */
 typedef gboolean (* GladeAddChildVerifyFunc)      (GladeWidgetAdaptor *adaptor,
-                                                   GObject            *parent,
+                                                   GObject            *container,
                                                    GObject            *child,
                                                    gboolean            user_feedback);
 
@@ -370,25 +370,25 @@ typedef GList   *(* GladeGetChildrenFunc)         (GladeWidgetAdaptor *adaptor,
 /**
  * GladeAddChildFunc:
  * @adaptor: A #GladeWidgetAdaptor
- * @parent: A #GObject container
+ * @container: A #GObject parent container
  * @child: A #GObject child
  *
- * Called to add @child to @parent.
+ * Called to add @child to @container.
  */
 typedef void     (* GladeAddChildFunc)            (GladeWidgetAdaptor *adaptor,
-                                                   GObject            *parent,
+                                                   GObject            *container,
                                                    GObject            *child);
 
 /**
  * GladeRemoveChildFunc:
  * @adaptor: A #GladeWidgetAdaptor
- * @parent: A #GObject container
+ * @container: A #GObject parent container
  * @child: A #GObject child
  *
- * Called to remove @child from @parent.
+ * Called to remove @child from @container.
  */
 typedef void     (* GladeRemoveChildFunc)         (GladeWidgetAdaptor *adaptor,
-                                                   GObject            *parent,
+                                                   GObject            *container,
                                                    GObject            *child);
 
 /**
@@ -463,16 +463,16 @@ typedef void     (* GladePostCreateFunc)          (GladeWidgetAdaptor *adaptor,
 /**
  * GladeGetInternalFunc:
  * @adaptor: A #GladeWidgetAdaptor
- * @parent: A #GObject composite object
- * @name: A string identifier
+ * @object: A #GObject composite object
+ * @internal_name: A string identifier
  *
- * Called to lookup @child in composite object @parent by @name.
+ * Called to lookup child in composite @object parent by @internal_name.
  *
  * Returns: The specified internal widget.
  */
 typedef GObject *(* GladeGetInternalFunc)         (GladeWidgetAdaptor *adaptor,
-                                                   GObject            *parent,
-                                                   const gchar        *name);
+                                                   GObject            *object,
+                                                   const gchar        *internal_name);
 
 /**
  * GladeActionActivateFunc:
diff --git a/gladeui/glade-widget.c b/gladeui/glade-widget.c
index cd6e6ed8..00079f18 100644
--- a/gladeui/glade-widget.c
+++ b/gladeui/glade-widget.c
@@ -720,7 +720,8 @@ glade_widget_build_object (GladeWidget      *widget,
 /**
  * glade_widget_dup_properties:
  * @dest_widget: the widget we are copying properties for
- * @template_props: the #GladeProperty list to copy
+ * @template_props: (element-type GladeProperty): the
+ * #GladeProperty list to copy
  * @as_load: whether to behave as if loading the project
  * @copy_parentless: whether to copy reffed widgets at all
  * @exact: whether to copy reffed widgets exactly
@@ -728,7 +729,8 @@ glade_widget_build_object (GladeWidget      *widget,
  * Copies a list of properties, if @as_load is specified, then
  * properties that are not saved to the glade file are ignored.
  *
- * Returns: A newly allocated #GList of new #GladeProperty objects.
+ * Returns: (transfer full) (element-type GladeProperty): A newly
+ * allocated #GList of new #GladeProperty objects.
  */
 GList *
 glade_widget_dup_properties (GladeWidget *dest_widget,
@@ -2055,6 +2057,12 @@ _glade_widget_peek_prop_refs (GladeWidget *widget)
 /*******************************************************************************
                                      API
  *******************************************************************************/
+/**
+ * glade_widget_get_from_gobject:
+ * @object: A #GObject containing the widget
+ *
+ * Returns: (transfer none): a #GladeWidget
+ */
 GladeWidget *
 glade_widget_get_from_gobject (gpointer object)
 {
@@ -2189,6 +2197,12 @@ glade_widget_remove_prop_ref (GladeWidget *widget, GladeProperty *property)
     }
 }
 
+/**
+ * glade_widget_list_prop_refs:
+ * @widget: A #GladeWidget
+ *
+ * Returns: (transfer container) (element-type GladeProperty): a list of #GladeProperty
+ */
 GList *
 glade_widget_list_prop_refs (GladeWidget *widget)
 {
@@ -2205,6 +2219,12 @@ glade_widget_has_prop_refs (GladeWidget *widget)
   return widget->priv->prop_refs != NULL;
 }
 
+/**
+ * glade_widget_get_parentless_widget_ref:
+ * @widget: A #GladeWidget
+ *
+ * Returns: (transfer none): a #GladeProperty
+ */
 GladeProperty *
 glade_widget_get_parentless_widget_ref (GladeWidget *widget)
 {
@@ -2226,7 +2246,12 @@ glade_widget_get_parentless_widget_ref (GladeWidget *widget)
   return NULL;
 }
 
-
+/**
+ * glade_widget_get_parentless_reffed_widgets:
+ * @widget: A #GladeWidget
+ *
+ * Returns: (transfer container) (element-type GladeProperty): a list of #GladeProperty
+ */
 GList *
 glade_widget_get_parentless_reffed_widgets (GladeWidget *widget)
 {
@@ -2276,7 +2301,7 @@ glade_widget_accum_signal_foreach (const gchar *key,
  *
  * Compiles a list of #GladeSignal elements
  *
- * Returns: (transfer container) (element-type GladeSignal):a newly allocated #GList of
+ * Returns: (transfer container) (element-type GladeSignal): a newly allocated #GList of
  * #GladeSignal, the caller must call g_list_free() to free the list.
  */
 GList *
@@ -2466,7 +2491,7 @@ glade_widget_remove_child (GladeWidget *parent, GladeWidget *child)
  * (this is used to maintain names & signals in Cut/Paste context
  * as opposed to Copy/Paste contexts).
  *
- * Returns: The newly created #GladeWidget
+ * Returns: (transfer full): The newly created #GladeWidget
  */
 GladeWidget *
 glade_widget_dup (GladeWidget *template_widget, gboolean exact)
@@ -2683,7 +2708,7 @@ glade_widget_rebuild (GladeWidget *gwidget)
  * @widget: a #GladeWidget
  * @signal_name: the name of the signal
  *
- * Returns: A #GPtrArray of #GladeSignal for @signal_name
+ * Returns: (transfer none) (element-type GladeSignal): A #GPtrArray of #GladeSignal for @signal_name
  */
 GPtrArray *
 glade_widget_list_signal_handlers (GladeWidget *widget, const gchar *signal_name)     /* array of GladeSignal* */
@@ -2852,7 +2877,7 @@ glade_widget_get_internal (GladeWidget *widget)
  * glade_widget_get_adaptor:
  * @widget: a #GladeWidget
  *
- * Returns: the #GladeWidgetAdaptor of @widget
+ * Returns: (transfer none): the #GladeWidgetAdaptor of @widget
  */
 GladeWidgetAdaptor *
 glade_widget_get_adaptor (GladeWidget *widget)
@@ -2882,7 +2907,7 @@ glade_widget_set_project (GladeWidget *widget, GladeProject *project)
  * glade_widget_get_project:
  * @widget: a #GladeWidget
  * 
- * Returns: the #GladeProject that @widget belongs to
+ * Returns: (transfer none): the #GladeProject that @widget belongs to
  */
 GladeProject *
 glade_widget_get_project (GladeWidget *widget)
@@ -2912,7 +2937,7 @@ glade_widget_in_project (GladeWidget *widget)
  * @widget: a #GladeWidget
  * @id_property: a string naming a #GladeProperty
  *
- * Returns: the #GladeProperty in @widget named @id_property
+ * Returns: (transfer none) (nullable): the #GladeProperty in @widget named @id_property
  */
 GladeProperty *
 glade_widget_get_property (GladeWidget *widget, const gchar *id_property)
@@ -2934,7 +2959,7 @@ glade_widget_get_property (GladeWidget *widget, const gchar *id_property)
  * @widget: a #GladeWidget
  * @id_property: a string naming a #GladeProperty
  *
- * Returns: the #GladeProperty in @widget named @id_property
+ * Returns: (transfer none) (nullable): the #GladeProperty in @widget named @id_property
  */
 GladeProperty *
 glade_widget_get_pack_property (GladeWidget *widget, const gchar *id_property)
@@ -3656,7 +3681,7 @@ glade_widget_set_object (GladeWidget *gwidget, GObject *new_object)
  * glade_widget_get_object:
  * @widget: a #GladeWidget
  *
- * Returns: the #GObject associated with @widget
+ * Returns: (transfer none): the #GObject associated with @widget
  */
 GObject *
 glade_widget_get_object (GladeWidget *widget)
@@ -3669,7 +3694,7 @@ glade_widget_get_object (GladeWidget *widget)
  * glade_widget_get_parent:
  * @widget: A #GladeWidget
  *
- * Returns: The parenting #GladeWidget
+ * Returns: (transfer none): The parenting #GladeWidget
  */
 GladeWidget *
 glade_widget_get_parent (GladeWidget *widget)
@@ -3681,7 +3706,7 @@ glade_widget_get_parent (GladeWidget *widget)
 /**
  * glade_widget_set_parent:
  * @widget: A #GladeWidget
- * @parent: the parenting #GladeWidget (or %NULL)
+ * @parent: (nullable): the parenting #GladeWidget (or %NULL)
  *
  * sets the parenting #GladeWidget
  */
@@ -3722,7 +3747,7 @@ glade_widget_set_parent (GladeWidget *widget, GladeWidget *parent)
  *
  * Finds a child widget named @name.
  *
- * Returns: The child of widget or NULL if it was not found.
+ * Returns: (nullable) (transfer none): The child of widget or %NULL if it was not found.
  */
 GladeWidget *
 glade_widget_find_child (GladeWidget *widget, const gchar *name)
@@ -3760,7 +3785,7 @@ glade_widget_find_child (GladeWidget *widget, const gchar *name)
  *
  * Fetches any wrapped children of @widget.
  *
- * Returns: The children of widget
+ * Returns: (transfer container) (element-type GObject): The children of widget
  *
  * <note><para>This differs from a direct call to glade_widget_adaptor_get_children() as
  * it only returns children which have an associated GladeWidget. This function will
@@ -3797,7 +3822,7 @@ glade_widget_get_children (GladeWidget *widget)
  * glade_widget_get_toplevel:
  * @widget: A #GladeWidget
  *
- * Returns: The toplevel #GladeWidget in the hierarchy (or @widget)
+ * Returns: (transfer none): The toplevel #GladeWidget in the hierarchy (or @widget)
  */
 GladeWidget *
 glade_widget_get_toplevel (GladeWidget *widget)
@@ -4427,8 +4452,8 @@ glade_widget_write (GladeWidget     *widget,
  * Determines whether @widget is somewhere inside @ancestor, possibly with
  * intermediate containers.
  *
- * Return value: %TRUE if @ancestor contains @widget as a child,
- *    grandchild, great grandchild, etc.
+ * Returns: %TRUE if @ancestor contains @widget as a child, grandchild,
+ * great grandchild, etc.
  **/
 gboolean
 glade_widget_is_ancestor (GladeWidget *widget, GladeWidget *ancestor)
@@ -4457,7 +4482,7 @@ glade_widget_is_ancestor (GladeWidget *widget, GladeWidget *ancestor)
  * A widget is dependent on another widget.
  * It does not take into account for children dependencies.
  *
- * Return value: %TRUE if @widget depends on @other.
+ * Returns: %TRUE if @widget depends on @other.
  *
  * Deprecated: 3.18 
  **/
@@ -4473,7 +4498,7 @@ glade_widget_depends (GladeWidget *widget, GladeWidget *other)
  * 
  * Currently only motion and button events are handled (see IS_GLADE_WIDGET_EVENT)
  * 
- * Returns: the asociated GdkDevice for this glade widget event.
+ * Returns: (transfer none): the asociated #GdkDevice for this glade widget event.
  *
  * Deprecated: use gdk_event_get_device() instead.
  */
@@ -4590,7 +4615,7 @@ glade_widget_action_lookup (GList *actions, const gchar *path)
  *
  * Returns a #GladeWidgetAction object indentified by @action_path.
  *
- * Returns: the action or NULL if not found.
+ * Returns: (transfer none) (nullable): the action or %NULL if not found.
  */
 GladeWidgetAction *
 glade_widget_get_action (GladeWidget *widget, const gchar *action_path)
@@ -4608,7 +4633,7 @@ glade_widget_get_action (GladeWidget *widget, const gchar *action_path)
  *
  * Returns a #GladeWidgetAction object indentified by @action_path.
  *
- * Returns: the action or NULL if not found.
+ * Returns: (transfer none) (nullable): the action or %NULL if not found.
  */
 GladeWidgetAction *
 glade_widget_get_pack_action (GladeWidget *widget, const gchar *action_path)
@@ -4619,7 +4644,12 @@ glade_widget_get_pack_action (GladeWidget *widget, const gchar *action_path)
   return glade_widget_action_lookup (widget->priv->packing_actions, action_path);
 }
 
-
+/**
+ * glade_widget_get_actions:
+ * @widget: a #GladeWidget
+ *
+ * Returns: (transfer none) (element-type GladeWidgetAction): the list of #GladeWidgetAction
+ */
 GList *
 glade_widget_get_actions (GladeWidget *widget)
 {
@@ -4628,6 +4658,12 @@ glade_widget_get_actions (GladeWidget *widget)
   return widget->priv->actions;
 }
 
+/**
+ * glade_widget_get_pack_actions:
+ * @widget: a #GladeWidget
+ *
+ * Returns: (transfer none) (element-type GladeWidgetAction): the list of #GladeWidgetAction
+ */
 GList *
 glade_widget_get_pack_actions (GladeWidget *widget)
 {
@@ -4636,7 +4672,6 @@ glade_widget_get_pack_actions (GladeWidget *widget)
   return widget->priv->packing_actions;
 }
 
-
 /**
  * glade_widget_set_action_sensitive:
  * @widget: a #GladeWidget
@@ -4757,7 +4792,7 @@ glade_widget_set_pack_action_visible (GladeWidget *widget,
  * This is a convenience function to create a GladeEditorProperty corresponding
  * to @property
  *
- * Returns: A newly created and connected GladeEditorProperty
+ * Returns: (transfer full): A newly created and connected GladeEditorProperty
  */
 GladeEditorProperty *
 glade_widget_create_editor_property (GladeWidget *widget,
@@ -4984,7 +5019,6 @@ glade_widget_support_warning (GladeWidget *widget)
  * Sets @locked to be in a locked up state
  * spoken for by @widget, locked widgets cannot
  * be removed from the project until unlocked.
- *
  */
 void
 glade_widget_lock (GladeWidget *widget, GladeWidget *locked)
@@ -5003,7 +5037,6 @@ glade_widget_lock (GladeWidget *widget, GladeWidget *locked)
  *
  * Unlocks @widget so that it can be removed
  * from the project again
- *
  */
 void
 glade_widget_unlock (GladeWidget *widget)
@@ -5021,7 +5054,15 @@ glade_widget_unlock (GladeWidget *widget)
   widget->priv->lock = NULL;
 }
 
-
+/**
+ * glade_widget_get_locker:
+ * @widget: A #GladeWidget
+ *
+ * Get the current locked widget, locked widgets cannot
+ * be removed from the project until unlocked
+ *
+ * Returns: (transfer none) (nullable): a #GladeWidget or %NULL if none is locked
+ */
 GladeWidget *
 glade_widget_get_locker (GladeWidget *widget)
 {
@@ -5030,6 +5071,12 @@ glade_widget_get_locker (GladeWidget *widget)
   return widget->priv->lock;
 }
 
+/**
+ * glade_widget_list_locked_widgets:
+ * @widget: A #GladeWidget
+ *
+ * Returns: (transfer container) (element-type GladeWidget): the list of #GladeWidget
+ */
 GList *
 glade_widget_list_locked_widgets (GladeWidget *widget)
 {
@@ -5044,7 +5091,6 @@ glade_widget_list_locked_widgets (GladeWidget *widget)
  * @widget: A #GladeWidget
  *
  * Notifies that support metadata has changed on the widget.
- *
  */
 void
 glade_widget_support_changed (GladeWidget *widget)
@@ -5058,7 +5104,7 @@ glade_widget_support_changed (GladeWidget *widget)
  * glade_widget_get_signal_model:
  * @widget: A #GladeWidget
  * 
- * Returns: a GtkTreeModel that can be used to view the widget's signals.
+ * Returns: (transfer none): a GtkTreeModel that can be used to view the widget's signals.
  *          The signal model is owned by the #GladeWidget.
  */
 GtkTreeModel *
@@ -5072,6 +5118,12 @@ glade_widget_get_signal_model (GladeWidget *widget)
         return widget->priv->signal_model;
 }
 
+/**
+ * glade_widget_get_properties:
+ * @widget: A #GladeWidget
+ *
+ * Returns: (transfer none) (element-type GladeProperty): the list of #GladeProperty
+ */
 GList *
 glade_widget_get_properties (GladeWidget *widget)
 {
@@ -5080,6 +5132,12 @@ glade_widget_get_properties (GladeWidget *widget)
   return widget->priv->properties;
 }
 
+/**
+ * glade_widget_get_packing_properties:
+ * @widget: A #GladeWidget
+ *
+ * Returns: (transfer none) (element-type GladeProperty): the list of #GladeProperty
+ */
 GList *
 glade_widget_get_packing_properties (GladeWidget *widget)
 {
diff --git a/gladeui/glade-widget.h b/gladeui/glade-widget.h
index a0c46241..991482d7 100644
--- a/gladeui/glade-widget.h
+++ b/gladeui/glade-widget.h
@@ -32,19 +32,19 @@ struct _GladeWidgetClass
 {
   GInitiallyUnownedClass parent_class;
 
-  void         (*add_child)               (GladeWidget *, GladeWidget *, gboolean);
-  void         (*remove_child)            (GladeWidget *, GladeWidget *);
-  void         (*replace_child)           (GladeWidget *, GObject *, GObject *);
+  void         (*add_child)               (GladeWidget *parent, GladeWidget *child, gboolean at_mouse);
+  void         (*remove_child)            (GladeWidget *parent, GladeWidget *child);
+  void         (*replace_child)           (GladeWidget *parent, GObject *old_object, GObject *new_object);
 
-  void         (*add_signal_handler)      (GladeWidget *, GladeSignal *);
-  void         (*remove_signal_handler)   (GladeWidget *, GladeSignal *);
-  void         (*change_signal_handler)   (GladeWidget *, GladeSignal *);
+  void         (*add_signal_handler)      (GladeWidget *widget, GladeSignal *signal_handler);
+  void         (*remove_signal_handler)   (GladeWidget *widget, GladeSignal *signal_handler);
+  void         (*change_signal_handler)   (GladeWidget *widget, GladeSignal *new_signal_handler);
 
-  gint         (*button_press_event)      (GladeWidget *, GdkEvent *);
-  gint         (*button_release_event)    (GladeWidget *, GdkEvent *);
-  gint         (*motion_notify_event)     (GladeWidget *, GdkEvent *);
+  gint         (*button_press_event)      (GladeWidget *widget, GdkEvent *event);
+  gint         (*button_release_event)    (GladeWidget *widget, GdkEvent *event);
+  gint         (*motion_notify_event)     (GladeWidget *widget, GdkEvent *event);
 
-  gboolean     (*event)                   (GladeWidget *, GdkEvent *);
+  gboolean     (*event)                   (GladeWidget *gwidget, GdkEvent *event);
 
   void   (* glade_reserved1)   (void);
   void   (* glade_reserved2)   (void);
diff --git a/gladeui/glade-xml-utils.c b/gladeui/glade-xml-utils.c
index b692ef63..f980bf85 100644
--- a/gladeui/glade-xml-utils.c
+++ b/gladeui/glade-xml-utils.c
@@ -65,6 +65,7 @@ struct _GladeXmlContext
   xmlNsPtr ns;
 };
 
+G_DEFINE_BOXED_TYPE(GladeXmlNode, glade_xml_node, glade_xml_node_copy, glade_xml_node_delete);
 
 /* This is used inside for loops so that we skip xml comments 
  * <!-- i am a comment ->
@@ -508,6 +509,15 @@ glade_xml_get_property_version (GladeXmlNode *node_in,
   return TRUE;
 }
 
+/**
+ * glade_xml_get_property_targetable_versions:
+ * @node_in: a #GladeXmlNode
+ * @name: a property name
+ *
+ * Get the list of targetable versions for a property
+ *
+ * Returns: (element-type GladeTargetableVersion) (transfer full): a list of #GladeTargetableVersion
+ */
 GList *
 glade_xml_get_property_targetable_versions (GladeXmlNode *node_in,
                                             const gchar  *name)
diff --git a/gladeui/glade-xml-utils.h b/gladeui/glade-xml-utils.h
index 209cbefd..0b6fcdf2 100644
--- a/gladeui/glade-xml-utils.h
+++ b/gladeui/glade-xml-utils.h
@@ -3,6 +3,7 @@
 #define __GLADE_XML_UTILS_H__
 
 #include <glib.h>
+#include <glib-object.h>
 #include <gmodule.h>
 
 
@@ -241,6 +242,7 @@ GladeXmlNode * glade_xml_node_prev_with_comments (GladeXmlNode *node_in);
 GladeXmlNode * glade_xml_node_get_children_with_comments (GladeXmlNode *node);
 GladeXmlNode * glade_xml_node_add_prev_sibling (GladeXmlNode *node, GladeXmlNode *new_node);
 GladeXmlNode * glade_xml_node_add_next_sibling (GladeXmlNode *node, GladeXmlNode *new_node);
+GType          glade_xml_node_get_type (void) G_GNUC_CONST;
 
 /* Document Operatons */
 GladeXmlNode * glade_xml_doc_get_root (GladeXmlDoc *doc);