AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Documentation fixes

Browse Source 
Mostly making sure that return values and varargs don't loose
their docs.
This commit is contained in:
Matthias Clasen 2011-09-25 20:58:59 -04:00
parent a6151ebb95
commit 5ff8fe6971
33 changed files with 194 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gtk/gtk3-sections.txt
View File

@ -903,6 +903,7 @@ gtk_container_child_get_property
gtk_container_child_set_property
gtk_container_child_get_valist
gtk_container_child_set_valist
gtk_container_child_notify
gtk_container_forall
gtk_container_get_border_width
gtk_container_set_border_width

9
gdk/gdkscreen.c
View File

@ -287,13 +287,14 @@ gdk_screen_get_monitor_at_point (GdkScreen *screen,
* gdk_screen_get_monitor_at_window:
* @screen: a #GdkScreen.
* @window: a #GdkWindow
* @returns: the monitor number in which most of @window is located,
* or if @window does not intersect any monitors, a monitor,
* close to @window.
*
* Returns the number of the monitor in which the largest area of the
* Returns the number of the monitor in which the largest area of the
* bounding rectangle of @window resides.
*
* Returns: the monitor number in which most of @window is located,
* or if @window does not intersect any monitors, a monitor,
* close to @window.
*
* Since: 2.2
**/
gint

2
gtk/gtkaboutdialog.c
View File

@ -2483,7 +2483,7 @@ close_cb (GtkAboutDialog *about)
* gtk_show_about_dialog:
* @parent: (allow-none): transient parent, or %NULL for none
* @first_property_name: the name of the first property
* @Varargs: value of first property, followed by more properties, %NULL-terminated
* @...: value of first property, followed by more properties, %NULL-terminated
*
* This is a convenience function for showing an application's about box.
* The constructed dialog is associated with the parent window and

34
gtk/gtkaccelgroup.c
View File

@ -242,9 +242,10 @@ gtk_accel_group_init (GtkAccelGroup *accel_group)
/**
* gtk_accel_group_new:
* @returns: a new #GtkAccelGroup object
*
* Creates a new #GtkAccelGroup.
*
* Returns: a new #GtkAccelGroup object
*/
GtkAccelGroup*
gtk_accel_group_new (void)
@ -380,11 +381,12 @@ gtk_accel_groups_from_object (GObject *object)
* @find_func: (scope call): a function to filter the entries
* of @accel_group with
* @data: data to pass to @find_func
* @returns: (transfer none): the key of the first entry passing
* @find_func. The key is owned by GTK+ and must not be freed.
*
* Finds the first entry in an accelerator group for which
* @find_func returns %TRUE and returns its #GtkAccelKey.
*
* Returns: (transfer none): the key of the first entry passing
* @find_func. The key is owned by GTK+ and must not be freed.
*/
GtkAccelKey*
gtk_accel_group_find (GtkAccelGroup *accel_group,
@ -702,12 +704,13 @@ gtk_accel_group_connect_by_path (GtkAccelGroup *accel_group,
* @accel_group: the accelerator group to remove an accelerator from
* @closure: (allow-none): the closure to remove from this accelerator
* group, or %NULL to remove all closures
* @returns: %TRUE if the closure was found and got disconnected
*
* Removes an accelerator previously installed through
* gtk_accel_group_connect().
*
* Since 2.20 @closure can be %NULL.
*
* Returns: %TRUE if the closure was found and got disconnected
*/
gboolean
gtk_accel_group_disconnect (GtkAccelGroup *accel_group,
@ -733,11 +736,12 @@ gtk_accel_group_disconnect (GtkAccelGroup *accel_group,
* @accel_group: the accelerator group to install an accelerator in
* @accel_key: key value of the accelerator
* @accel_mods: modifier combination of the accelerator
* @returns: %TRUE if there was an accelerator which could be
* removed, %FALSE otherwise
*
* Removes an accelerator previously installed through
* gtk_accel_group_connect().
*
* Returns: %TRUE if there was an accelerator which could be
* removed, %FALSE otherwise
*/
gboolean
gtk_accel_group_disconnect_key (GtkAccelGroup *accel_group,
@ -823,12 +827,13 @@ _gtk_accel_group_get_accelerables (GtkAccelGroup *accel_group)
* @accel_mods: modifier combination of the accelerator
* @n_entries: (allow-none): location to return the number
* of entries found, or %NULL
* @returns: (transfer none) (array length=n_entries): an array of
* @n_entries #GtkAccelGroupEntry elements, or %NULL. The array
* is owned by GTK+ and must not be freed.
*
* Queries an accelerator group for all entries matching @accel_key
* and @accel_mods.
*
* Returns: (transfer none) (array length=n_entries): an array of
* @n_entries #GtkAccelGroupEntry elements, or %NULL. The array
* is owned by GTK+ and must not be freed.
*/
GtkAccelGroupEntry*
gtk_accel_group_query (GtkAccelGroup *accel_group,
@ -852,11 +857,12 @@ gtk_accel_group_query (GtkAccelGroup *accel_group,
/**
* gtk_accel_group_from_accel_closure:
* @closure: a #GClosure
* @returns: (transfer none): the #GtkAccelGroup to which @closure
* is connected, or %NULL
*
* Finds the #GtkAccelGroup to which @closure is connected;
* see gtk_accel_group_connect().
*
* Returns: (transfer none): the #GtkAccelGroup to which @closure
* is connected, or %NULL
*/
GtkAccelGroup*
gtk_accel_group_from_accel_closure (GClosure *closure)
@ -957,13 +963,14 @@ gtk_accel_groups_activate (GObject *object,
* gtk_accelerator_valid:
* @keyval: a GDK keyval
* @modifiers: modifier mask
* @returns: %TRUE if the accelerator is valid
*
* Determines whether a given keyval and modifier mask constitute
* a valid keyboard accelerator. For example, the #GDK_KEY_a keyval
* plus #GDK_CONTROL_MASK is valid - this is a "Ctrl+a" accelerator.
* But, you can't, for instance, use the #GDK_KEY_Control_L keyval
* as an accelerator.
*
* Returns: %TRUE if the accelerator is valid
*/
gboolean
gtk_accelerator_valid (guint keyval,
@ -1469,9 +1476,10 @@ gtk_accelerator_set_default_mod_mask (GdkModifierType default_mod_mask)
/**
* gtk_accelerator_get_default_mod_mask:
* @returns: the default accelerator modifier mask
*
* Gets the value set by gtk_accelerator_set_default_mod_mask().
*
* Returns: the default accelerator modifier mask
*/
GdkModifierType
gtk_accelerator_get_default_mod_mask (void)

10
gtk/gtkaccelmap.c
View File

@ -260,9 +260,10 @@ gtk_accel_map_add_entry (const gchar *accel_path,
* gtk_accel_map_lookup_entry:
* @accel_path: a valid accelerator path
* @key: (allow-none) (out): the accelerator key to be filled in (optional)
* @returns: %TRUE if @accel_path is known, %FALSE otherwise
*
* Looks up the accelerator entry for @accel_path and fills in @key.
*
* Returns: %TRUE if @accel_path is known, %FALSE otherwise
*/
gboolean
gtk_accel_map_lookup_entry (const gchar *accel_path,
@ -485,7 +486,6 @@ internal_change_entry (const gchar *accel_path,
* @accel_key: the new accelerator key
* @accel_mods: the new accelerator modifiers
* @replace: %TRUE if other accelerators may be deleted upon conflicts
* @returns: %TRUE if the accelerator could be changed, %FALSE otherwise
*
* Changes the @accel_key and @accel_mods currently associated with @accel_path.
* Due to conflicts with other accelerators, a change may not always be possible,
@ -493,10 +493,12 @@ internal_change_entry (const gchar *accel_path,
* conflicts. A change will only occur if all conflicts could be resolved (which
* might not be the case if conflicting accelerators are locked). Successful
* changes are indicated by a %TRUE return value.
*
*
* Note that @accel_path string will be stored in a #GQuark. Therefore, if you
* pass a static string, you can save some memory by interning it first with
* pass a static string, you can save some memory by interning it first with
* g_intern_static_string().
*
* Returns: %TRUE if the accelerator could be changed, %FALSE otherwise
*/
gboolean
gtk_accel_map_change_entry (const gchar *accel_path,

2
gtk/gtkbindings.c
View File

@ -993,7 +993,7 @@ _gtk_binding_entry_add_signall (GtkBindingSet *binding_set,
* @modifiers: key modifier of binding to install
* @signal_name: signal to execute upon activation
* @n_args: number of arguments to @signal_name
* @Varargs: arguments to @signal_name
* @...: arguments to @signal_name
*
* Override or install a new key binding for @keyval with @modifiers on
* @binding_set. When the binding is activated, @signal_name will be

7
gtk/gtkbutton.c
View File

@ -1135,14 +1135,15 @@ gtk_button_new_from_stock (const gchar *stock_id)
* gtk_button_new_with_mnemonic:
* @label: The text of the button, with an underscore in front of the
* mnemonic character
* @returns: a new #GtkButton
*
* Creates a new #GtkButton containing a label.
* If characters in @label are preceded by an underscore, they are underlined.
* If you need a literal underscore character in a label, use '__' (two
* underscores). The first underlined character represents a keyboard
* If you need a literal underscore character in a label, use '__' (two
* underscores). The first underlined character represents a keyboard
* accelerator called a mnemonic.
* Pressing Alt and that key activates the button.
*
* Returns: a new #GtkButton
**/
GtkWidget*
gtk_button_new_with_mnemonic (const gchar *label)

8
gtk/gtkcellarea.c
View File

@ -2493,8 +2493,8 @@ gtk_cell_area_class_list_cell_properties (GtkCellAreaClass *aclass,
* @area: a #GtkCellArea
* @renderer: a #GtkCellRenderer to be placed inside @area
* @first_prop_name: the name of the first cell property to set
* @Varargs: a %NULL-terminated list of property names and values, starting
* with @first_prop_name
* @...: a %NULL-terminated list of property names and values, starting
* with @first_prop_name
*
* Adds @renderer to @area, setting cell properties at the same time.
* See gtk_cell_area_add() and gtk_cell_area_cell_set() for more details.
@ -2534,7 +2534,7 @@ gtk_cell_area_add_with_properties (GtkCellArea *area,
* @area: a #GtkCellArea
* @renderer: a #GtkCellRenderer which is a cell inside @area
* @first_prop_name: the name of the first cell property to set
* @Varargs: a %NULL-terminated list of property names and values, starting
* @...: a %NULL-terminated list of property names and values, starting
* with @first_prop_name
*
* Sets one or more cell properties for @cell in @area.
@ -2562,7 +2562,7 @@ gtk_cell_area_cell_set (GtkCellArea *area,
* @area: a #GtkCellArea
* @renderer: a #GtkCellRenderer which is inside @area
* @first_prop_name: the name of the first cell property to get
* @Varargs: return location for the first cell property, followed
* @...: return location for the first cell property, followed
* optionally by more name/return location pairs, followed by %NULL
*
* Gets the values of one or more cell properties for @renderer in @area.

2
gtk/gtkcelllayout.c
View File

@ -449,7 +449,7 @@ gtk_cell_layout_set_attributesv (GtkCellLayout *cell_layout,
* gtk_cell_layout_set_attributes:
* @cell_layout: a #GtkCellLayout
* @cell: a #GtkCellRenderer
* @Varargs: a %NULL-terminated list of attributes
* @...: a %NULL-terminated list of attributes
*
* Sets the attributes in list as the attributes of @cell_layout.
*

5
gtk/gtkcheckbutton.c
View File

@ -147,12 +147,13 @@ gtk_check_button_new_with_label (const gchar *label)
* gtk_check_button_new_with_mnemonic:
* @label: The text of the button, with an underscore in front of the
* mnemonic character
* @returns: a new #GtkCheckButton
*
* Creates a new #GtkCheckButton containing a label. The label
* will be created using gtk_label_new_with_mnemonic(), so underscores
* in @label indicate the mnemonic for the check button.
**/
*
* Returns: a new #GtkCheckButton
*/
GtkWidget*
gtk_check_button_new_with_mnemonic (const gchar *label)
{

7
gtk/gtkcheckmenuitem.c
View File

@ -272,13 +272,14 @@ gtk_check_menu_item_new_with_label (const gchar *label)
/**
* gtk_check_menu_item_new_with_mnemonic:
* @label: The text of the button, with an underscore in front of the
* mnemonic character
* @returns: a new #GtkCheckMenuItem
* character
*
* Creates a new #GtkCheckMenuItem containing a label. The label
* will be created using gtk_label_new_with_mnemonic(), so underscores
* in @label indicate the mnemonic for the menu item.
**/
*
* Returns: a new #GtkCheckMenuItem
*/
GtkWidget*
gtk_check_menu_item_new_with_mnemonic (const gchar *label)
{

24
gtk/gtkcontainer.c
View File

@ -1145,8 +1145,8 @@ gtk_container_child_set_property (GtkContainer *container,
* @container: a #GtkContainer
* @widget: a widget to be placed inside @container
* @first_prop_name: the name of the first child property to set
* @Varargs: a %NULL-terminated list of property names and values, starting
* with @first_prop_name
* @...: a %NULL-terminated list of property names and values, starting
* with @first_prop_name
*
* Adds @widget to @container, setting child properties at the same time.
* See gtk_container_add() and gtk_container_child_set() for more details.
@ -1185,8 +1185,8 @@ gtk_container_add_with_properties (GtkContainer *container,
* @container: a #GtkContainer
* @child: a widget which is a child of @container
* @first_prop_name: the name of the first property to set
* @Varargs: a %NULL-terminated list of property names and values, starting
* with @first_prop_name
* @...: a %NULL-terminated list of property names and values, starting
* with @first_prop_name
*
* Sets one or more child properties for @child and @container.
*/
@ -1208,11 +1208,11 @@ gtk_container_child_set (GtkContainer *container,
* @container: a #GtkContainer
* @child: a widget which is a child of @container
* @first_prop_name: the name of the first property to get
* @Varargs: return location for the first property, followed
* @...: return location for the first property, followed
* optionally by more name/return location pairs, followed by %NULL
*
* Gets the values of one or more child properties for @child and @container.
**/
*/
void
gtk_container_child_get (GtkContainer *container,
GtkWidget *child,
@ -1267,10 +1267,11 @@ gtk_container_class_install_child_property (GtkContainerClass *cclass,
* gtk_container_class_find_child_property:
* @cclass: (type GtkContainerClass): a #GtkContainerClass
* @property_name: the name of the child property to find
* @returns: (transfer none): the #GParamSpec of the child property or
* %NULL if @class has no child property with that name.
*
* Finds a child property of a container class by name.
*
* Returns: (transfer none): the #GParamSpec of the child property
* or %NULL if @class has no child property with that name.
*/
GParamSpec*
gtk_container_class_find_child_property (GObjectClass *cclass,
@ -1289,11 +1290,12 @@ gtk_container_class_find_child_property (GObjectClass *cclass,
* gtk_container_class_list_child_properties:
* @cclass: (type GtkContainerClass): a #GtkContainerClass
* @n_properties: location to return the number of child properties found
* @returns: (array length=n_properties) (transfer container): a newly
* allocated %NULL-terminated array of #GParamSpec*. The
* array must be freed with g_free().
*
* Returns all child properties of a container class.
*
* Returns: (array length=n_properties) (transfer container):
* a newly allocated %NULL-terminated array of #GParamSpec*.
* The array must be freed with g_free().
*/
GParamSpec**
gtk_container_class_list_child_properties (GObjectClass *cclass,

10
gtk/gtkdialog.c
View File

@ -607,7 +607,7 @@ gtk_dialog_new_empty (const gchar *title,
* @parent: (allow-none): Transient parent of the dialog, or %NULL
* @flags: from #GtkDialogFlags
* @first_button_text: (allow-none): stock ID or text to go in first button, or %NULL
* @Varargs: response ID for first button, then additional buttons, ending with %NULL
* @...: response ID for first button, then additional buttons, ending with %NULL
*
* Creates a new #GtkDialog with title @title (or %NULL for the default
* title; see gtk_window_set_title()) and transient parent @parent (or
@ -641,7 +641,7 @@ gtk_dialog_new_empty (const gchar *title,
* ]|
*
* Return value: a new #GtkDialog
**/
*/
GtkWidget*
gtk_dialog_new_with_buttons (const gchar *title,
GtkWindow *parent,
@ -828,13 +828,13 @@ gtk_dialog_add_buttons_valist (GtkDialog *dialog,
* gtk_dialog_add_buttons:
* @dialog: a #GtkDialog
* @first_button_text: button text or stock ID
* @Varargs: response ID for first button, then more text-response_id pairs
* @...: response ID for first button, then more text-response_id pairs
*
* Adds more buttons, same as calling gtk_dialog_add_button()
* repeatedly. The variable argument list should be %NULL-terminated
* as with gtk_dialog_new_with_buttons(). Each button must have both
* text and response ID.
**/
*/
void
gtk_dialog_add_buttons (GtkDialog *dialog,
const gchar *first_button_text,
@ -1265,7 +1265,7 @@ gtk_dialog_set_alternative_button_order_valist (GtkDialog *dialog,
* gtk_dialog_set_alternative_button_order:
* @dialog: a #GtkDialog
* @first_response_id: a response id used by one @dialog's buttons
* @Varargs: a list of more response ids of @dialog's buttons, terminated by -1
* @...: a list of more response ids of @dialog's buttons, terminated by -1
*
* Sets an alternative button order. If the
* #GtkSettings:gtk-alternative-button-order setting is set to %TRUE,

2
gtk/gtkfilechooserdialog.c
View File

@ -592,7 +592,7 @@ gtk_file_chooser_dialog_new_valist (const gchar *title,
* @parent: (allow-none): Transient parent of the dialog, or %NULL
* @action: Open or save mode for the dialog
* @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
* @Varargs: response ID for the first button, then additional (button, id) pairs, ending with %NULL
* @...: response ID for the first button, then additional (button, id) pairs, ending with %NULL
*
* Creates a new #GtkFileChooserDialog. This function is analogous to
* gtk_dialog_new_with_buttons().

1
gtk/gtkfontchooserwidget.c
View File

@ -532,6 +532,7 @@ gtk_font_chooser_widget_init (GtkFontChooserWidget *fontchooser)
/* Creating fundamental widgets for the private struct */
priv->search_entry = gtk_entry_new ();
priv->family_face_list = gtk_tree_view_new ();
gtk_tree_view_set_enable_search (GTK_TREE_VIEW (priv->family_face_list), FALSE);
priv->preview = gtk_entry_new ();
priv->size_slider = gtk_scale_new_with_range (GTK_ORIENTATION_HORIZONTAL,
0.0,

3
gtk/gtkiconfactory.c
View File

@ -1166,10 +1166,11 @@ gtk_icon_size_from_name (const gchar *name)
/**
* gtk_icon_size_get_name:
* @size: (type int): a #GtkIconSize.
* @returns: the name of the given icon size.
*
* Gets the canonical name of the given icon size. The returned string
* is statically allocated and should not be freed.
*
* Returns: the name of the given icon size.
*/
const gchar*
gtk_icon_size_get_name (GtkIconSize size)

15
gtk/gtkimagemenuitem.c
View File

@ -774,10 +774,11 @@ gtk_image_menu_item_sync_action_properties (GtkActivatable *activatable,
/**
* gtk_image_menu_item_new:
* @returns: a new #GtkImageMenuItem.
*
* Creates a new #GtkImageMenuItem with an empty label.
**/
*
* Returns: a new #GtkImageMenuItem
*/
GtkWidget*
gtk_image_menu_item_new (void)
{
@ -787,9 +788,10 @@ gtk_image_menu_item_new (void)
/**
* gtk_image_menu_item_new_with_label:
* @label: the text of the menu item.
* @returns: a new #GtkImageMenuItem.
*
* Creates a new #GtkImageMenuItem containing a label.
*
* Returns: a new #GtkImageMenuItem.
*/
GtkWidget*
gtk_image_menu_item_new_with_label (const gchar *label)
@ -799,16 +801,16 @@ gtk_image_menu_item_new_with_label (const gchar *label)
NULL);
}
/**
* gtk_image_menu_item_new_with_mnemonic:
* @label: the text of the menu item, with an underscore in front of the
* mnemonic character
* @returns: a new #GtkImageMenuItem
*
* Creates a new #GtkImageMenuItem containing a label. The label
* will be created using gtk_label_new_with_mnemonic(), so underscores
* in @label indicate the mnemonic for the menu item.
*
* Returns: a new #GtkImageMenuItem
*/
GtkWidget*
gtk_image_menu_item_new_with_mnemonic (const gchar *label)
@ -824,7 +826,6 @@ gtk_image_menu_item_new_with_mnemonic (const gchar *label)
* @stock_id: the name of the stock item.
* @accel_group: (allow-none): the #GtkAccelGroup to add the menu items
* accelerator to, or %NULL.
* @returns: a new #GtkImageMenuItem.
*
* Creates a new #GtkImageMenuItem containing the image and text from a
* stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK
@ -835,6 +836,8 @@ gtk_image_menu_item_new_with_mnemonic (const gchar *label)
* appropriate path for the menu item, use gtk_stock_lookup() to look up the
* standard accelerator for the stock item, and if one is found, call
* gtk_accel_map_add_entry() to register it.
*
* Returns: a new #GtkImageMenuItem.
*/
GtkWidget*
gtk_image_menu_item_new_from_stock (const gchar *stock_id,

32
gtk/gtkliststore.c
View File

@ -414,18 +414,18 @@ iter_is_valid (GtkTreeIter *iter,
/**
* gtk_list_store_new:
* @n_columns: number of columns in the list store
* @Varargs: all #GType types for the columns, from first to last
* @...: all #GType types for the columns, from first to last
*
* Creates a new list store as with @n_columns columns each of the types passed
* in. Note that only types derived from standard GObject fundamental types
* are supported.
* in. Note that only types derived from standard GObject fundamental types
* are supported.
*
* As an example, <literal>gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
* GDK_TYPE_PIXBUF);</literal> will create a new #GtkListStore with three columns, of type
* int, string and #GdkPixbuf respectively.
*
* Return value: a new #GtkListStore
**/
*/
GtkListStore *
gtk_list_store_new (gint n_columns,
...)
@ -1172,7 +1172,7 @@ gtk_list_store_set_valist (GtkListStore *list_store,
* gtk_list_store_set:
* @list_store: a #GtkListStore
* @iter: row iterator
* @Varargs: pairs of column number and value, terminated with -1
* @...: pairs of column number and value, terminated with -1
*
* Sets the value of one or more cells in the row referenced by @iter.
* The variable argument list should contain integer column numbers,
@ -1183,7 +1183,7 @@ gtk_list_store_set_valist (GtkListStore *list_store,
*
* The value will be referenced by the store if it is a %G_TYPE_OBJECT, and it
* will be copied if it is a %G_TYPE_STRING or %G_TYPE_BOXED.
**/
*/
void
gtk_list_store_set (GtkListStore *list_store,
GtkTreeIter *iter,
@ -2170,18 +2170,18 @@ gtk_list_store_has_default_sort_func (GtkTreeSortable *sortable)
/**
* gtk_list_store_insert_with_values:
* @list_store: A #GtkListStore
* @iter: (out) (allow-none): An unset #GtkTreeIter to set to the new row, or %NULL.
* @iter: (out) (allow-none): An unset #GtkTreeIter to set to the new row, or %NULL
* @position: position to insert the new row
* @Varargs: pairs of column number and value, terminated with -1
* @...: pairs of column number and value, terminated with -1
*
* Creates a new row at @position. @iter will be changed to point to this new
* row. If @position is larger than the number of rows on the list, then the
* new row will be appended to the list. The row will be filled with the
* values given to this function.
*
* Creates a new row at @position. @iter will be changed to point to this new
* row. If @position is larger than the number of rows on the list, then the
* new row will be appended to the list. The row will be filled with the
* values given to this function.
*
* Calling
* <literal>gtk_list_store_insert_with_values(list_store, iter, position...)</literal>
* has the same effect as calling
* <literal>gtk_list_store_insert_with_values (list_store, iter, position...)</literal>
* has the same effect as calling
* |[
* gtk_list_store_insert (list_store, iter, position);
* gtk_list_store_set (list_store, iter, ...);
@ -2189,7 +2189,7 @@ gtk_list_store_has_default_sort_func (GtkTreeSortable *sortable)
* with the difference that the former will only emit a row_inserted signal,
* while the latter will emit row_inserted, row_changed and, if the list store
* is sorted, rows_reordered. Since emitting the rows_reordered signal
* repeatedly can affect the performance of the program,
* repeatedly can affect the performance of the program,
* gtk_list_store_insert_with_values() should generally be preferred when
* inserting rows in a sorted list store.
*

34
gtk/gtkmessagedialog.c
View File

@ -582,7 +582,7 @@ gtk_message_dialog_get_property (GObject *object,
* @type: type of message
* @buttons: set of buttons to use
* @message_format: (allow-none): printf()-style format string, or %NULL
* @Varargs: arguments for @message_format
* @...: arguments for @message_format
*
* Creates a new message dialog, which is a simple dialog with an icon
* indicating the dialog type (error, warning, etc.) and some text the
@ -591,7 +591,7 @@ gtk_message_dialog_get_property (GObject *object,
* #GtkDialog for more details.
*
* Return value: (transfer none): a new #GtkMessageDialog
**/
*/
GtkWidget*
gtk_message_dialog_new (GtkWindow *parent,
GtkDialogFlags flags,
@ -640,13 +640,13 @@ gtk_message_dialog_new (GtkWindow *parent,
/**
* gtk_message_dialog_new_with_markup:
* @parent: (allow-none): transient parent, or %NULL for none
* @parent: (allow-none): transient parent, or %NULL for none
* @flags: flags
* @type: type of message
* @buttons: set of buttons to use
* @message_format: (allow-none): printf()-style format string, or %NULL
* @Varargs: arguments for @message_format
*
* @...: arguments for @message_format
*
* Creates a new message dialog, which is a simple dialog with an icon
* indicating the dialog type (error, warning, etc.) and some text which
* is marked up with the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
@ -794,16 +794,16 @@ gtk_message_dialog_set_markup (GtkMessageDialog *message_dialog,
* gtk_message_dialog_format_secondary_text:
* @message_dialog: a #GtkMessageDialog
* @message_format: (allow-none): printf()-style format string, or %NULL
* @Varargs: arguments for @message_format
*
* Sets the secondary text of the message dialog to be @message_format
* @...: arguments for @message_format
*
* Sets the secondary text of the message dialog to be @message_format
* (with printf()-style).
*
* Note that setting a secondary text makes the primary text become
* bold, unless you have provided explicit markup.
*
* Since: 2.6
**/
*/
void
gtk_message_dialog_format_secondary_text (GtkMessageDialog *message_dialog,
const gchar *message_format,
@ -842,32 +842,32 @@ gtk_message_dialog_format_secondary_text (GtkMessageDialog *message_dialog,
/**
* gtk_message_dialog_format_secondary_markup:
* @message_dialog: a #GtkMessageDialog
* @message_format: printf()-style markup string (see
* @message_format: printf()-style markup string (see
<link linkend="PangoMarkupFormat">Pango markup format</link>), or %NULL
* @Varargs: arguments for @message_format
*
* Sets the secondary text of the message dialog to be @message_format (with
* printf()-style), which is marked up with the
* @...: arguments for @message_format
*
* Sets the secondary text of the message dialog to be @message_format (with
* printf()-style), which is marked up with the
* <link linkend="PangoMarkupFormat">Pango text markup language</link>.
*
* Note that setting a secondary text makes the primary text become
* bold, unless you have provided explicit markup.
*
* Due to an oversight, this function does not escape special XML characters
* like gtk_message_dialog_new_with_markup() does. Thus, if the arguments
* like gtk_message_dialog_new_with_markup() does. Thus, if the arguments
* may contain special XML characters, you should use g_markup_printf_escaped()
* to escape it.
* <informalexample><programlisting>
* gchar *msg;
*
*
* msg = g_markup_printf_escaped (message_format, ...);
* gtk_message_dialog_format_secondary_markup (message_dialog, "&percnt;s", msg);
* g_free (msg);
* </programlisting></informalexample>
*
* Since: 2.6
**/
*/
void
gtk_message_dialog_format_secondary_markup (GtkMessageDialog *message_dialog,
const gchar *message_format,

5
gtk/gtkradiomenuitem.c
View File

@ -270,12 +270,13 @@ gtk_radio_menu_item_new_with_label (GSList *group,
* @group: group the radio menu item is inside
* @label: the text of the button, with an underscore in front of the
* mnemonic character
* @returns: a new #GtkRadioMenuItem
*
* Creates a new #GtkRadioMenuItem containing a label. The label
* will be created using gtk_label_new_with_mnemonic(), so underscores
* in @label indicate the mnemonic for the menu item.
**/
*
* Returns: a new #GtkRadioMenuItem
*/
GtkWidget*
gtk_radio_menu_item_new_with_mnemonic (GSList *group,
const gchar *label)

10
gtk/gtkrc.c
View File

@ -912,8 +912,6 @@ gtk_rc_make_default_dir (const gchar *type)
/**
* gtk_rc_get_im_module_path:
* @returns: (type filename): a newly-allocated string containing the
* path in which to look for IM modules.
*
* Obtains the path in which to look for IM modules. See the documentation
* of the <link linkend="im-module-path"><envar>GTK_PATH</envar></link>
@ -921,6 +919,9 @@ gtk_rc_make_default_dir (const gchar *type)
* function is useful solely for utilities supplied with GTK+ and should
* not be used by applications under normal circumstances.
*
* Returns: (type filename): a newly-allocated string containing the
* path in which to look for IM modules.
*
* Deprecated: 3.0: Use #GtkCssProvider instead.
*/
gchar *
@ -935,13 +936,14 @@ gtk_rc_get_im_module_path (void)
/**
* gtk_rc_get_im_module_file:
* @returns: (type filename): a newly-allocated string containing the
* name of the file listing the IM modules available for loading
*
* Obtains the path to the IM modules file. See the documentation
* of the <link linkend="im-module-file"><envar>GTK_IM_MODULE_FILE</envar></link>
* environment variable for more details.
*
* Returns: (type filename): a newly-allocated string containing the
* name of the file listing the IM modules available for loading
*
* Deprecated: 3.0: Use #GtkCssProvider instead.
*/
gchar *

4
gtk/gtkrecentchooserdialog.c
View File

@ -337,7 +337,7 @@ gtk_recent_chooser_dialog_new_valist (const gchar *title,
* @title: (allow-none): Title of the dialog, or %NULL
* @parent: (allow-none): Transient parent of the dialog, or %NULL,
* @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
* @Varargs: response ID for the first button, then additional (button, id)
* @...: response ID for the first button, then additional (button, id)
* pairs, ending with %NULL
*
* Creates a new #GtkRecentChooserDialog. This function is analogous to
@ -373,7 +373,7 @@ gtk_recent_chooser_dialog_new (const gchar *title,
* @parent: (allow-none): Transient parent of the dialog, or %NULL,
* @manager: a #GtkRecentManager
* @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
* @Varargs: response ID for the first button, then additional (button, id)
* @...: response ID for the first button, then additional (button, id)
* pairs, ending with %NULL
*
* Creates a new #GtkRecentChooserDialog with a specified recent manager.

2
gtk/gtksettings.c
View File

@ -1903,7 +1903,7 @@ gtk_settings_install_property (GParamSpec *pspec)
/**
* gtk_settings_install_property_parser:
* @psepc:
* @pspec:
* @parser: (scope call):
*/
void

10
gtk/gtkstyle.c
View File

@ -831,12 +831,13 @@ _gtk_style_new_for_path (GdkScreen *screen,
/**
* gtk_style_new:
* @returns: a new #GtkStyle.
*
* Creates a new #GtkStyle.
*
* Returns: a new #GtkStyle.
*
* Deprecated: 3.0: Use #GtkStyleContext
**/
*/
GtkStyle*
gtk_style_new (void)
{
@ -1203,7 +1204,7 @@ gtk_style_get_valist (GtkStyle *style,
* @style: a #GtkStyle
* @widget_type: the #GType of a descendant of #GtkWidget
* @first_property_name: the name of the first style property to get
* @Varargs: pairs of property names and locations to
* @...: pairs of property names and locations to
* return the property values, starting with the location for
* @first_property_name, terminated by %NULL.
*
@ -1291,9 +1292,8 @@ gtk_style_render_icon (GtkStyle *style,
/**
* gtk_style_apply_default_background:
* @style:
* @cr:
* @cr:
* @window:
* @set_bg:
* @state_type:
* @x:
* @y:

8
gtk/gtktextbuffer.c
View File

@ -1489,10 +1489,10 @@ gtk_text_buffer_insert_range_interactive (GtkTextBuffer *buffer,
* @text: UTF-8 text
* @len: length of @text, or -1
* @first_tag: first tag to apply to @text
* @Varargs: NULL-terminated list of tags to apply
* @...: %NULL-terminated list of tags to apply
*
* Inserts @text into @buffer at @iter, applying the list of tags to
* the newly-inserted text. The last tag specified must be NULL to
* the newly-inserted text. The last tag specified must be %NULL to
* terminate the list. Equivalent to calling gtk_text_buffer_insert(),
* then gtk_text_buffer_apply_tag() on the inserted text;
* gtk_text_buffer_insert_with_tags() is just a convenience function.
@ -1543,7 +1543,7 @@ gtk_text_buffer_insert_with_tags (GtkTextBuffer *buffer,
* @text: UTF-8 text
* @len: length of @text, or -1
* @first_tag_name: name of a tag to apply to @text
* @Varargs: more tag names
* @...: more tag names
*
* Same as gtk_text_buffer_insert_with_tags(), but allows you
* to pass in tag names instead of tag objects.
@ -2466,7 +2466,7 @@ gtk_text_buffer_select_range (GtkTextBuffer *buffer,
* @buffer: a #GtkTextBuffer
* @tag_name: (allow-none): name of the new tag, or %NULL
* @first_property_name: (allow-none): name of first property to set, or %NULL
* @Varargs: %NULL-terminated list of property names and values
* @...: %NULL-terminated list of property names and values
*
* Creates a tag and adds it to the tag table for @buffer.
* Equivalent to calling gtk_text_tag_new() and then adding the

5
gtk/gtktogglebutton.c
View File

@ -309,12 +309,13 @@ gtk_toggle_button_new_with_label (const gchar *label)
* gtk_toggle_button_new_with_mnemonic:
* @label: the text of the button, with an underscore in front of the
* mnemonic character
* @returns: a new #GtkToggleButton
*
* Creates a new #GtkToggleButton containing a label. The label
* will be created using gtk_label_new_with_mnemonic(), so underscores
* in @label indicate the mnemonic for the button.
**/
*
* Returns: a new #GtkToggleButton
*/
GtkWidget*
gtk_toggle_button_new_with_mnemonic (const gchar *label)
{

4
gtk/gtktreemodel.c
View File

@ -652,7 +652,7 @@ gtk_tree_path_new_from_string (const gchar *path)
/**
* gtk_tree_path_new_from_indices:
* @first_index: first integer
* @varargs: list of integers terminated by -1
* @...: list of integers terminated by -1
*
* Creates a new path with @first_index and @varargs as indices.
*
@ -1700,7 +1700,7 @@ gtk_tree_model_unref_node (GtkTreeModel *tree_model,
* gtk_tree_model_get:
* @tree_model: a #GtkTreeModel
* @iter: a row in @tree_model
* @Varargs: pairs of column number and value return locations,
* @...: pairs of column number and value return locations,
* terminated by -1
*
* Gets the value of one or more cells in the row referenced by @iter.

20
gtk/gtktreestore.c
View File

@ -304,11 +304,11 @@ gtk_tree_store_init (GtkTreeStore *tree_store)
/**
* gtk_tree_store_new:
* @n_columns: number of columns in the tree store
* @Varargs: all #GType types for the columns, from first to last
* @...: all #GType types for the columns, from first to last
*
* Creates a new tree store as with @n_columns columns each of the types passed
* in. Note that only types derived from standard GObject fundamental types
* are supported.
* in. Note that only types derived from standard GObject fundamental types
* are supported.
*
* As an example, <literal>gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
* GDK_TYPE_PIXBUF);</literal> will create a new #GtkTreeStore with three columns, of type
@ -1170,13 +1170,13 @@ gtk_tree_store_set_valist (GtkTreeStore *tree_store,
* gtk_tree_store_set:
* @tree_store: A #GtkTreeStore
* @iter: A valid #GtkTreeIter for the row being modified
* @Varargs: pairs of column number and value, terminated with -1
* @...: pairs of column number and value, terminated with -1
*
* Sets the value of one or more cells in the row referenced by @iter.
* The variable argument list should contain integer column numbers,
* each column number followed by the value to be set.
* each column number followed by the value to be set.
* The list is terminated by a -1. For example, to set column 0 with type
* %G_TYPE_STRING to "Foo", you would write
* %G_TYPE_STRING to "Foo", you would write
* <literal>gtk_tree_store_set (store, iter, 0, "Foo", -1)</literal>.
*
* The value will be referenced by the store if it is a %G_TYPE_OBJECT, and it
@ -1493,11 +1493,11 @@ gtk_tree_store_insert_after (GtkTreeStore *tree_store,
* @iter: (out) (allow-none): An unset #GtkTreeIter to set the new row, or %NULL.
* @parent: (allow-none): A valid #GtkTreeIter, or %NULL
* @position: position to insert the new row
* @Varargs: pairs of column number and value, terminated with -1
* @...: pairs of column number and value, terminated with -1
*
* Creates a new row at @position. @iter will be changed to point to this
* new row. If @position is larger than the number of rows on the list, then
* the new row will be appended to the list. The row will be filled with
* Creates a new row at @position. @iter will be changed to point to this
* new row. If @position is larger than the number of rows on the list, then
* the new row will be appended to the list. The row will be filled with
* the values given to this function.
*
* Calling

8
gtk/gtktreeview.c
View File

@ -11988,10 +11988,10 @@ gtk_tree_view_insert_column (GtkTreeView *tree_view,
/**
* gtk_tree_view_insert_column_with_attributes:
* @tree_view: A #GtkTreeView
* @position: The position to insert the new column in.
* @title: The title to set the header to.
* @cell: The #GtkCellRenderer.
* @Varargs: A %NULL-terminated list of attributes.
* @position: The position to insert the new column in
* @title: The title to set the header to
* @cell: The #GtkCellRenderer
* @...: A %NULL-terminated list of attributes
*
* Creates a new #GtkTreeViewColumn and inserts it into the @tree_view at
* @position. If @position is -1, then the newly created column is inserted at

20
gtk/gtktreeviewcolumn.c
View File

@ -1643,12 +1643,12 @@ gtk_tree_view_column_new_with_area (GtkCellArea *area)
/**
* gtk_tree_view_column_new_with_attributes:
* @title: The title to set the header to.
* @cell: The #GtkCellRenderer.
* @Varargs: A %NULL-terminated list of attributes.
*
* Creates a new #GtkTreeViewColumn with a number of default values. This is
* equivalent to calling gtk_tree_view_column_set_title(),
* @title: The title to set the header to
* @cell: The #GtkCellRenderer
* @...: A %NULL-terminated list of attributes
*
* Creates a new #GtkTreeViewColumn with a number of default values.
* This is equivalent to calling gtk_tree_view_column_set_title(),
* gtk_tree_view_column_pack_start(), and
* gtk_tree_view_column_set_attributes() on the newly created #GtkTreeViewColumn.
*
@ -1787,15 +1787,15 @@ gtk_tree_view_column_set_attributesv (GtkTreeViewColumn *tree_column,
/**
* gtk_tree_view_column_set_attributes:
* @tree_column: A #GtkTreeViewColumn.
* @tree_column: A #GtkTreeViewColumn
* @cell_renderer: the #GtkCellRenderer we're setting the attributes of
* @Varargs: A %NULL-terminated list of attributes.
*
* @...: A %NULL-terminated list of attributes
*
* Sets the attributes in the list as the attributes of @tree_column.
* The attributes should be in attribute/column order, as in
* gtk_tree_view_column_add_attribute(). All existing attributes
* are removed, and replaced with the new attributes.
**/
*/
void
gtk_tree_view_column_set_attributes (GtkTreeViewColumn *tree_column,
GtkCellRenderer *cell_renderer,

8
gtk/gtkviewport.c
View File

@ -252,13 +252,13 @@ gtk_viewport_init (GtkViewport *viewport)
/**
* gtk_viewport_new:
* @hadjustment: horizontal adjustment.
* @vadjustment: vertical adjustment.
* @returns: a new #GtkViewport.
* @hadjustment: horizontal adjustment
* @vadjustment: vertical adjustment
*
* Creates a new #GtkViewport with the given adjustments.
*
**/
* Returns: a new #GtkViewport
*/
GtkWidget*
gtk_viewport_new (GtkAdjustment *hadjustment,
GtkAdjustment *vadjustment)

39
gtk/gtkwidget.c
View File

@ -3656,8 +3656,8 @@ gtk_widget_thaw_child_notify (GtkWidget *widget)
* gtk_widget_new:
* @type: type ID of the widget to create
* @first_property_name: name of first property to set
* @Varargs: value of first property, followed by more properties,
* %NULL-terminated
* @...: value of first property, followed by more properties,
* %NULL-terminated
*
* This is a convenience function for creating a widget and setting
* its properties in one go. For example you might write:
@ -5406,10 +5406,11 @@ gtk_widget_add_accelerator (GtkWidget *widget,
* @accel_group: accel group for this widget
* @accel_key: GDK keyval of the accelerator
* @accel_mods: modifier key combination of the accelerator
* @returns: whether an accelerator was installed and could be removed
*
* Removes an accelerator from @widget, previously installed with
* gtk_widget_add_accelerator().
*
* Returns: whether an accelerator was installed and could be removed
*/
gboolean
gtk_widget_remove_accelerator (GtkWidget *widget,
@ -6342,16 +6343,16 @@ gtk_widget_intersect (GtkWidget *widget,
* @widget->allocation. That is, relative to @widget->window
* for %NO_WINDOW widgets; relative to the parent window
* of @widget->window for widgets with their own window.
* @returns: A newly allocated region holding the intersection of @widget
* and @region. The coordinates of the return value are
* relative to @widget->window for %NO_WINDOW widgets, and
* relative to the parent window of @widget->window for
* widgets with their own window.
*
* Computes the intersection of a @widget's area and @region, returning
* the intersection. The result may be empty, use cairo_region_is_empty() to
* check.
**/
*
* Returns: A newly allocated region holding the intersection of @widget
* and @region. The coordinates of the return value are relative to
* @widget->window for %NO_WINDOW widgets, and relative to the parent
* window of @widget->window for widgets with their own window.
*/
cairo_region_t *
gtk_widget_region_intersect (GtkWidget *widget,
const cairo_region_t *region)
@ -11579,11 +11580,12 @@ gtk_widget_class_install_style_property (GtkWidgetClass *klass,
* gtk_widget_class_find_style_property:
* @klass: a #GtkWidgetClass
* @property_name: the name of the style property to find
* @returns: (transfer none): the #GParamSpec of the style property or
* %NULL if @class has no style property with that name.
*
* Finds a style property of a widget class by name.
*
* Returns: (transfer none): the #GParamSpec of the style property or
* %NULL if @class has no style property with that name.
*
* Since: 2.2
*/
GParamSpec*
@ -11602,12 +11604,13 @@ gtk_widget_class_find_style_property (GtkWidgetClass *klass,
* gtk_widget_class_list_style_properties:
* @klass: a #GtkWidgetClass
* @n_properties: location to return the number of style properties found
* @returns: (array length=n_properties) (transfer container): an
* newly allocated array of #GParamSpec*. The array must be
* freed with g_free().
*
* Returns all style properties of a widget class.
*
* Returns: (array length=n_properties) (transfer container): a
* newly allocated array of #GParamSpec*. The array must be
* freed with g_free().
*
* Since: 2.2
*/
GParamSpec**
@ -11752,9 +11755,9 @@ gtk_widget_style_get_valist (GtkWidget *widget,
* gtk_widget_style_get:
* @widget: a #GtkWidget
* @first_property_name: the name of the first property to get
* @Varargs: pairs of property names and locations to
* return the property values, starting with the location for
* @first_property_name, terminated by %NULL.
* @...: pairs of property names and locations to return the
* property values, starting with the location for
* @first_property_name, terminated by %NULL.
*
* Gets the values of a multiple style properties of @widget.
*/
@ -14388,7 +14391,7 @@ _gtk_widget_get_sizegroups (GtkWidget *widget)
* Returns: the position where the data was inserted
*
* Since: 3.2
**/
*/
gint
gtk_widget_path_append_for_widget (GtkWidgetPath *path,
GtkWidget *widget)

7
gtk/gtkwindow.c
View File

@ -2075,10 +2075,11 @@ gtk_window_remove_mnemonic (GtkWindow *window,
* gtk_window_mnemonic_activate:
* @window: a #GtkWindow
* @keyval: the mnemonic
* @modifier: the modifiers
* @returns: %TRUE if the activation is done.
*
* @modifier: the modifiers
*
* Activates the targets associated with the mnemonic.
*
* Returns: %TRUE if the activation is done.
*/
gboolean
gtk_window_mnemonic_activate (GtkWindow *window,