[glade/tintou/documentation-refresh: 3/4] docs: Make some changes to fix warnings with the documentation
- From: Alberto Fanjul <albfan src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glade/tintou/documentation-refresh: 3/4] docs: Make some changes to fix warnings with the documentation
- Date: Sat, 30 Mar 2019 09:20:39 +0000 (UTC)
commit e7043dbffa4ba084a4b3617439a9229f4a80ca6d
Author: Corentin Noël <corentin noel collabora com>
Date: Fri Mar 29 16:39:43 2019 +0100
docs: Make some changes to fix warnings with the documentation
gladeui/glade-base-editor.c | 6 +++---
gladeui/glade-catalog.c | 10 +++++-----
gladeui/glade-command.c | 32 +++++++++++++++++---------------
gladeui/glade-command.h | 4 ++--
gladeui/glade-id-allocator.c | 10 +++++-----
gladeui/glade-previewer.c | 12 ++++++------
gladeui/glade-project.c | 2 +-
gladeui/glade-property-class.c | 1 +
gladeui/glade-signal.c | 2 +-
gladeui/glade-utils.c | 13 ++++---------
gladeui/glade-widget-action.c | 2 +-
gladeui/glade-widget-adaptor.c | 11 ++++++-----
gladeui/glade-widget-adaptor.h | 3 ++-
gladeui/glade-widget.c | 17 ++++++++++-------
gladeui/glade-widget.h | 7 ++++---
gladeui/glade-xml-utils.c | 12 ++++++------
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
**/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
