docs: Make some changes to fix warnings with the documentation

16 files changed, 74 insertions, 70 deletions

diff --git a/gladeui/glade-base-editor.c b/gladeui/glade-base-editor.c
index 44e4d41c..486218a2 100644
--- a/gladeui/glade-base-editor.c
+++ b/gladeui/glade-base-editor.c
@@ -1724,7 +1724,7 @@ glade_base_editor_class_init (GladeBaseEditorClass *klass)
  * glade_base_editor_new:
  * @container: a container this new editor will edit.
  * @main_editable: the custom #GladeEditable for @container, or %NULL
- * @... A NULL terminated list of gchar *, GType
+ * @...: A NULL terminated list of gchar *, GType
  *
  * Creates a new GladeBaseEditor with @container toplevel
  * support for all the object types indicated in the variable argument list.
@@ -1805,7 +1805,7 @@ glade_base_editor_new (GObject *container, GladeEditable *main_editable, ...)
  * glade_base_editor_append_types:
  * @editor: A #GladeBaseEditor
  * @parent_type: the parent type these child types will apply to
- * @... A NULL terminated list of gchar *, GType
+ * @...: A NULL terminated list of gchar *, GType
  *
  * Appends support for all the object types indicated in the variable argument list.
  * Argument List:
@@ -2037,7 +2037,7 @@ glade_base_editor_add_label (GladeBaseEditor *editor, gchar *str)
 /**
  * glade_base_editor_set_show_signal_editor:
  * @editor: a #GladeBaseEditor
- * @val:
+ * @val: whether to show the signal editor
  *
  * Shows/hide @editor 's signal editor
  */
diff --git a/gladeui/glade-catalog.c b/gladeui/glade-catalog.c
index c1adbe5c..78e68535 100644
--- a/gladeui/glade-catalog.c
+++ b/gladeui/glade-catalog.c
@@ -568,7 +568,7 @@ catalogs_from_path (GList *catalogs, const gchar *path)
 
 /**
  * glade_catalog_add_path:
- * @path:
+ * @path: the new path containing catalogs
  * 
  * Adds a new path to the list of path to look catalogs for.
  */
@@ -583,10 +583,10 @@ glade_catalog_add_path (const gchar *path)
 
 /**
  * glade_catalog_remove_path:
- * @path:
+ * @path: (nullable): the new path containing catalogs or %NULL to remove all of them
  * 
  * Remove path from the list of path to look catalogs for.
- * NULL to remove all paths.
+ * %NULL to remove all paths.
  */
 void
 glade_catalog_remove_path (const gchar *path)
@@ -607,7 +607,7 @@ glade_catalog_remove_path (const gchar *path)
 /**
  * glade_catalog_get_extra_paths:
  *
- * Returns a list paths added by glade_catalog_add_path()
+ * Returns: (element-type utf8) (transfer none): a list paths added by glade_catalog_add_path()
  */
 const GList *
 glade_catalog_get_extra_paths (void)
@@ -623,7 +623,7 @@ glade_catalog_get_extra_paths (void)
  * then from glade_app_get_catalogs_dir() and finally from paths specified with
  * glade_catalog_add_path()
  *
- * Returns: the list of loaded GladeCatalog *
+ * Returns: (element-type GladeCatalog) (transfer none): the list of loaded GladeCatalog *
  */
 const GList *
 glade_catalog_load_all (void)
diff --git a/gladeui/glade-command.c b/gladeui/glade-command.c
index 9899d30d..a664e3bb 100644
--- a/gladeui/glade-command.c
+++ b/gladeui/glade-command.c
@@ -838,8 +838,8 @@ glade_command_set_property_description (GladeCommandSetProperty *me)
 
 /**
  * glade_command_set_properties_list:
- *
- * @props (element-type GladeProperty): List of #GladeProperty
+ * @project: a #GladeProject
+ * @props: (element-type GladeProperty): List of #GladeProperty
  */
 void
 glade_command_set_properties_list (GladeProject *project, GList *props)
@@ -1198,9 +1198,10 @@ get_all_parentless_reffed_widgets (GList *reffed, GladeWidget *widget)
 
 /**
  * glade_command_add:
- * @widgets (element-type GladeWidget): a #Glist
+ * @widgets: (element-type GladeWidget): a #GList
  * @parent: a #GladeWidget
  * @placeholder: a #GladePlaceholder
+ * @project: a #GladeProject
  * @pasting: whether we are pasting an existing widget or creating a new one.
  *
  * Performs an add command on all widgets in @widgets to @parent, possibly
@@ -1364,7 +1365,7 @@ glade_command_remove_locked (GladeWidget *widget, GList *reffed)
 
 /**
  * glade_command_remove:
- * @widgets (element-type GladeWidget): a #GList of #GladeWidgets
+ * @widgets: (element-type GladeWidget): a #GList of #GladeWidgets
  * @return_placeholders: whether or not to return a list of placehodlers
  *
  * Performs a remove command on all widgets in @widgets from @parent.
@@ -1790,9 +1791,9 @@ 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
- * @project:            the project his widget belongs to.
+ * @parent: (allow-none): the parent #GladeWidget to add the new widget to.
+ * @placeholder: (allow-none): 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
@@ -1842,7 +1843,7 @@ glade_command_create (GladeWidgetAdaptor *adaptor,
 
 /**
  * glade_command_delete:
- * @widgets (element-type GladeWidget): a #GList of #GladeWidgets
+ * @widgets: (element-type GladeWidget): a #GList of #GladeWidgets
  *
  * Performs a delete command on the list of widgets.
  */
@@ -1863,7 +1864,7 @@ glade_command_delete (GList *widgets)
 
 /**
  * glade_command_cut:
- * @widgets (element-type GladeWidget): a #GList of #GladeWidgets
+ * @widgets: (element-type GladeWidget): a #GList of #GladeWidgets
  *
  * Removes the list of widgets and adds them to the clipboard.
  */
@@ -1952,9 +1953,10 @@ glade_command_break_references (GladeProject *project, GList *widgets)
 
 /**
  * glade_command_paste:
- * @widgets (element-type GladeWidget): a #GList of #GladeWidget
- * @parent (allow-none): a #GladeWidget
- * @placeholder (allow-none): a #GladePlaceholder
+ * @widgets: (element-type GladeWidget): a #GList of #GladeWidget
+ * @parent: (allow-none): a #GladeWidget
+ * @placeholder: (allow-none): a #GladePlaceholder
+ * @project: a #GladeProject
  *
  * Performs a paste command on all widgets in @widgets to @parent, possibly
  * replacing @placeholder (note toplevels dont need a parent; the active project
@@ -1995,9 +1997,9 @@ glade_command_paste (GList *widgets,
 
 /**
  * glade_command_dnd:
- * @widgets (element-type GladeWidget): a #GList of #GladeWidget
- * @parent (allow-none): a #GladeWidget
- * @placeholder (allow-none): a #GladePlaceholder
+ * @widgets: (element-type GladeWidget): a #GList of #GladeWidget
+ * @parent: (allow-none): a #GladeWidget
+ * @placeholder: (allow-none): a #GladePlaceholder
  *
  * Performs a drag-n-drop command, i.e. removes the list of widgets and adds them 
  * to the new parent, possibly replacing @placeholder (note toplevels dont need a 
diff --git a/gladeui/glade-command.h b/gladeui/glade-command.h
index 9242d301..8b2f0975 100644
--- a/gladeui/glade-command.h
+++ b/gladeui/glade-command.h
@@ -29,7 +29,7 @@ typedef struct _GCSetPropData       GCSetPropData;
  * @new_value: The new #GValue to assign to @property
  * @old_value: The old #GValue of @property
  *
- * #GladeProperties can be set in a list as one command,
+ * #GladeProperty can be set in a list as one command,
  * for Undo purposes; we store the list of #GCSetPropData with
  * their old and new #GValue.
  */
@@ -124,7 +124,7 @@ void           glade_command_set_name      (GladeWidget       *glade_widget, con
 /************************ protection ******************************/
 
 void           glade_command_lock_widget   (GladeWidget   *widget, 
-                                            GladeWidget   *lock);
+                                            GladeWidget   *locked);
 
 void           glade_command_unlock_widget (GladeWidget   *widget);
 
diff --git a/gladeui/glade-id-allocator.c b/gladeui/glade-id-allocator.c
index 44e363b1..92611f98 100644
--- a/gladeui/glade-id-allocator.c
+++ b/gladeui/glade-id-allocator.c
@@ -103,11 +103,11 @@ first_set_bit (guint32 word)
 }
 
 /**
- * glade_id_allocator_alloc:
+ * glade_id_allocator_allocate:
  * @allocator: a #GladeIDAllocator
  *
  * TODO: write me
- * Returns:
+ * Returns: the id
  */
 guint
 glade_id_allocator_allocate (GladeIDAllocator *allocator)
@@ -142,8 +142,8 @@ glade_id_allocator_allocate (GladeIDAllocator *allocator)
 
 /**
  * glade_id_allocator_release:
- * @allocator:
- * @id:
+ * @allocator: a #GladeIDAllocator
+ * @id: the id given by glade_id_allocator_allocate()
  *
  * TODO: write me
  */
@@ -189,7 +189,7 @@ main (int argc, char **argv)
   for (iter = 0; iter < 10000; iter++)
     {
       for (i = 0; i < 1000; i++)
-        glade_id_allocator_alloc (allocator);
+        glade_id_allocator_allocate (allocator);
 
       for (i = 0; i < 1000; i++)
         glade_id_allocator_release (allocator, i);
diff --git a/gladeui/glade-previewer.c b/gladeui/glade-previewer.c
index 8472359d..8cdbe25e 100644
--- a/gladeui/glade-previewer.c
+++ b/gladeui/glade-previewer.c
@@ -810,12 +810,12 @@ on_handler_called (SignalData *data)
 
 /**
  * glade_previewer_connect_function:
- * @builder:
- * @object:
- * @signal_name:
- * @handler_name:
- * @connect_object:
- * @flags:
+ * @builder: a #GtkBuilder
+ * @object: the #GObject triggering the signal
+ * @signal_name: the name of the signal
+ * @handler_name: the name of the c function handling the signal
+ * @connect_object: the user_data #GObject to connect
+ * @flags: #GConnectFlags used in the connection
  * @window: a #GladePreviewer
  * 
  * Function that collects every signal handler in @builder and shows them
diff --git a/gladeui/glade-project.c b/gladeui/glade-project.c
index c8a1ddcb..a5bf8fdb 100644
--- a/gladeui/glade-project.c
+++ b/gladeui/glade-project.c
@@ -2246,7 +2246,7 @@ glade_project_load_from_file (GladeProject *project, const gchar *path)
 
 /**
  * glade_project_load:
- * @path:
+ * @path: the path of the project to load
  * 
  * Opens a project at the given path.
  *
diff --git a/gladeui/glade-property-class.c b/gladeui/glade-property-class.c
index 2de6b980..caa62fd8 100644
--- a/gladeui/glade-property-class.c
+++ b/gladeui/glade-property-class.c
@@ -2215,6 +2215,7 @@ glade_property_class_match (GladePropertyClass *klass,
 /**
  * glade_property_class_void_value:
  * @klass: a #GladePropertyClass
+ * @value: a GValue of correct type for @klass
  *
  * Returns: Whether @value for this @klass is voided; a voided value
  *          can be a %NULL value for boxed or object type param specs.
diff --git a/gladeui/glade-signal.c b/gladeui/glade-signal.c
index cfb2221d..b56868a9 100644
--- a/gladeui/glade-signal.c
+++ b/gladeui/glade-signal.c
@@ -222,7 +222,7 @@ glade_signal_klass_init (GladeSignalKlass *klass)
 
 /**
  * glade_signal_new:
- * @name: a name for the signal
+ * @sig_class: a #GladeSignalClass
  * @handler: a handler function for the signal
  * @userdata: the userdata for this signal
  * @after: whether this handler should be called after the default emission phase
diff --git a/gladeui/glade-utils.c b/gladeui/glade-utils.c
index 6d9fa226..c5111c5b 100644
--- a/gladeui/glade-utils.c
+++ b/gladeui/glade-utils.c
@@ -59,11 +59,11 @@
 
 /**
  * glade_util_compose_get_type_func:
- * @name:
+ * @name: the name of the #GType - like 'GtkWidget' or a "get-type" function.
  *
  * TODO: write me
  *
- * Returns:
+ * Returns: the type function getter
  */
 static gchar *
 glade_util_compose_get_type_func (const gchar *name)
@@ -645,9 +645,6 @@ 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).
  *
- * Note that glade_widget_class_get_children() is the high-level
- * abstraction and will usually end up calling this function.
- *
  * Returns: a #GList giving the contents of @container
  */
 GList *
@@ -1565,8 +1562,6 @@ pclass_from_gtype (GType type)
  * @type: a #GType to convert with
  * @string: the string to convert
  * @project: the #GladeProject to look for formats of object names when needed
- * @widget: if the value is a gobject, this #GladeWidget will be used to look
- *          for an object in the same widget tree.
  *
  * Allocates and sets a #GValue of type @type
  * set to @string (using glade conversion routines) 
@@ -1710,8 +1705,8 @@ glade_utils_liststore_from_enum_type (GType enum_type, gboolean include_empty)
 /**
  * glade_utils_hijack_key_press:
  * @win: a #GtkWindow
- * event: the GdkEventKey 
- * user_data: unused
+ * @event: the #GdkEventKey
+ * @user_data: unused
  *
  * This function is meant to be attached to key-press-event of a toplevel,
  * it simply allows the window contents to treat key events /before/ 
diff --git a/gladeui/glade-widget-action.c b/gladeui/glade-widget-action.c
index cf9f58bb..5e2ee1f8 100644
--- a/gladeui/glade-widget-action.c
+++ b/gladeui/glade-widget-action.c
@@ -206,7 +206,7 @@ glade_widget_action_class_init (GladeWidgetActionClass *klass)
 /**
  * glade_widget_action_set_sensitive:
  * @action: a #GladeWidgetAction
- * @sensitive:
+ * @sensitive: the sensitivity to set
  *
  * Set whether or not this action is sensitive.
  *
diff --git a/gladeui/glade-widget-adaptor.c b/gladeui/glade-widget-adaptor.c
index fb452009..a39b0dd0 100644
--- a/gladeui/glade-widget-adaptor.c
+++ b/gladeui/glade-widget-adaptor.c
@@ -3110,17 +3110,17 @@ glade_widget_adaptor_get_by_type (GType type)
  **/
 GladeWidgetAdaptor *
 glade_widget_adaptor_from_pspec (GladeWidgetAdaptor *adaptor,
-                                 GParamSpec         *spec)
+                                 GParamSpec         *pspec)
 {
   GladeWidgetAdaptor *spec_adaptor;
-  GType spec_type = spec->owner_type;
+  GType spec_type = pspec->owner_type;
 
   if (!spec_type)
     return adaptor;
 
-  spec_adaptor = glade_widget_adaptor_get_by_type (spec->owner_type);
+  spec_adaptor = glade_widget_adaptor_get_by_type (pspec->owner_type);
 
-  g_return_val_if_fail (g_type_is_a (adaptor->priv->type, spec->owner_type), NULL);
+  g_return_val_if_fail (g_type_is_a (adaptor->priv->type, pspec->owner_type), NULL);
 
   while (spec_type && !spec_adaptor && spec_type != adaptor->priv->type)
     {
@@ -3496,7 +3496,7 @@ glade_widget_adaptor_verify_property (GladeWidgetAdaptor *adaptor,
 /**
  * glade_widget_adaptor_add_verify:
  * @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.
@@ -4127,6 +4127,7 @@ glade_widget_adaptor_action_activate (GladeWidgetAdaptor *adaptor,
 /**
  * glade_widget_adaptor_child_action_activate:
  * @adaptor:   A #GladeWidgetAdaptor
+ * @container: The #GObject container
  * @object:    The #GObject
  * @action_path: The action identifier in the action tree
  *
diff --git a/gladeui/glade-widget-adaptor.h b/gladeui/glade-widget-adaptor.h
index 04797f19..359757ce 100644
--- a/gladeui/glade-widget-adaptor.h
+++ b/gladeui/glade-widget-adaptor.h
@@ -553,6 +553,7 @@ typedef void     (* GladeReadWidgetFunc) (GladeWidgetAdaptor *adaptor,
  * GladeWriteWidgetFunc:
  * @adaptor: A #GladeWidgetAdaptor
  * @widget: The #GladeWidget
+ * @context: The #GladeXmlContext
  * @node: The #GladeXmlNode
  *
  * This function is called to fill in @node from @widget.
@@ -775,7 +776,7 @@ GladeWidget          *glade_widget_adaptor_create_widget_real (gboolean
 GladeWidgetAdaptor   *glade_widget_adaptor_get_by_name        (const gchar        *name);
 GladeWidgetAdaptor   *glade_widget_adaptor_get_by_type        (GType               type);
 GladeWidgetAdaptor   *glade_widget_adaptor_from_pspec         (GladeWidgetAdaptor *adaptor,
-                                                               GParamSpec         *spec);
+                                                               GParamSpec         *pspec);
 
 GladePropertyClass   *glade_widget_adaptor_get_property_class (GladeWidgetAdaptor *adaptor,
                                                                const gchar        *name);
diff --git a/gladeui/glade-widget.c b/gladeui/glade-widget.c
index e3914614..cd6e6ed8 100644
--- a/gladeui/glade-widget.c
+++ b/gladeui/glade-widget.c
@@ -536,6 +536,7 @@ glade_widget_event_impl (GladeWidget *gwidget, GdkEvent *event)
 
 /**
  * glade_widget_event:
+ * @gwidget: A #GladeWidget
  * @event: A #GdkEvent
  *
  * Feed an event to be handled on the project GladeWidget
@@ -1608,7 +1609,7 @@ glade_widget_set_default_packing_properties (GladeWidget *container,
     }
 }
 
-/**
+/*
  * When looking for an internal child we have to walk up the hierarchy...
  */
 static GObject *
@@ -2275,8 +2276,8 @@ glade_widget_accum_signal_foreach (const gchar *key,
  *
  * Compiles a list of #GladeSignal elements
  *
- * Returns: a newly allocated #GList of #GladeSignals, the caller
- * must call g_list_free() to free the list.
+ * Returns: (transfer container) (element-type GladeSignal):a newly allocated #GList of
+ * #GladeSignal, the caller must call g_list_free() to free the list.
  */
 GList *
 glade_widget_get_signal_list (GladeWidget *widget)
@@ -3924,10 +3925,11 @@ glade_widget_has_decendant (GladeWidget *widget, GType type)
 
 /**
  * glade_widget_replace:
+ * @parent: A #GladeWidget
  * @old_object: a #GObject
  * @new_object: a #GObject
  * 
- * Replaces a GObject with another GObject inside a GObject which
+ * Replaces a GObject with another GObject inside a #GladeWidget which
  * behaves as a container.
  *
  * Note that both GObjects must be owned by a GladeWidget.
@@ -4012,8 +4014,9 @@ glade_widget_read_child (GladeWidget *widget, GladeXmlNode *node)
 /**
  * glade_widget_read:
  * @project: a #GladeProject
- * @parent: The parent #GladeWidget or %NULL
+ * @parent: (nullable): The parent #GladeWidget or %NULL
  * @node: a #GladeXmlNode
+ * @internal: (nullable): the name of an internal child name
  *
  * Creates a new #GladeWidget from a XML node.
  *
@@ -4022,7 +4025,7 @@ glade_widget_read_child (GladeWidget *widget, GladeXmlNode *node)
  *
  * For example, with a GtkBin template Glade will GladeInstantiableGtkBin class
  *
- * Returns: a new #GladeWidget for @project, based on @node
+ * Returns: (transfer full): a new #GladeWidget for @project, based on @node
  */
 GladeWidget *
 glade_widget_read (GladeProject *project,
@@ -4196,7 +4199,7 @@ glade_widget_write_child (GladeWidget     *widget,
 /**
  * glade_widget_write_placeholder:
  * @parent: The parent #GladeWidget
- * @object: A #GladePlaceHolder
+ * @object: A #GladePlaceholder
  * @context: A #GladeXmlContext
  * @node: A #GladeXmlNode
  *
diff --git a/gladeui/glade-widget.h b/gladeui/glade-widget.h
index 6ca09ea0..a0c46241 100644
--- a/gladeui/glade-widget.h
+++ b/gladeui/glade-widget.h
@@ -74,7 +74,7 @@ GType                   glade_widget_get_type               (void);
 
 GladeWidget            *glade_widget_get_from_gobject       (gpointer          object);
 
-gboolean                glade_widget_add_verify             (GladeWidget      *parent,
+gboolean                glade_widget_add_verify             (GladeWidget      *widget,
                                                              GladeWidget      *child,
                                                              gboolean          user_feedback);
 
@@ -169,11 +169,11 @@ gboolean                glade_widget_set_pack_action_sensitive (GladeWidget *wid
 
 gboolean                glade_widget_set_action_visible     (GladeWidget *widget,
                                                              const gchar *action_path,
-                                                             gboolean     sensitive);
+                                                             gboolean     visible);
 
 gboolean                glade_widget_set_pack_action_visible (GladeWidget *widget,
                                                               const gchar *action_path,
-                                                              gboolean     sensitive);
+                                                              gboolean     visible);
 
 void                    glade_widget_write                  (GladeWidget     *widget,
                                                              GladeXmlContext *context,
@@ -225,6 +225,7 @@ G_DEPRECATED
 gboolean                glade_widget_depends                (GladeWidget      *widget,
                                                              GladeWidget      *other);
 
+G_DEPRECATED
 GdkDevice              *glade_widget_get_device_from_event  (GdkEvent *event);
 
 void                    glade_widget_ensure_name            (GladeWidget      *widget,
diff --git a/gladeui/glade-xml-utils.c b/gladeui/glade-xml-utils.c
index c5e41432..b692ef63 100644
--- a/gladeui/glade-xml-utils.c
+++ b/gladeui/glade-xml-utils.c
@@ -255,9 +255,9 @@ glade_xml_get_value_int (GladeXmlNode *node_in, const gchar *name, gint *val)
  * @val: a pointer to an #int
  * 
  * This is a wrapper around glade_xml_get_value_int(), only it emits
- * a g_warning() if @node_in did not contain the requested tag
+ * a g_warning() if @node did not contain the requested tag
  * 
- * Returns:
+ * Returns: %FALSE if @name is not in @node
  **/
 gboolean
 glade_xml_get_value_int_required (GladeXmlNode *node,
@@ -579,13 +579,13 @@ glade_xml_search_child (GladeXmlNode *node_in, const gchar *name)
 
 /**
  * glade_xml_search_child_required:
- * @tree: 
- * @name: 
+ * @tree: A #GladeXmlNode
+ * @name: the name of the child
  * 
  * just a small wrapper arround glade_xml_search_child that displays
  * an error if the child was not found
  *
- * Return Value: 
+ * Returns: (nullable): the requested #GladeXmlNode
  **/
 GladeXmlNode *
 glade_xml_search_child_required (GladeXmlNode *node, const gchar *name)
@@ -686,7 +686,7 @@ glade_xml_context_new_from_path (const gchar *full_path,
 
 /**
  * glade_xml_context_free:
- * @context: 
+ * @context: An #GladeXmlContext
  * 
  * Similar to glade_xml_context_destroy but it also frees the document set in the context
  **/