GNOME.org
 

[gtk+/gi-annotations: 11/12] Update GI annotations in 'Tree, List and Icon Grid Widgets'

commit 151424c58404de896cb01a6ee63bfe313c5871d2
Author: Pavel Holejsovsky <pavel holejsovsky gmail com>
Date:   Tue Jan 11 15:20:45 2011 +0100

    Update GI annotations in 'Tree, List and Icon Grid Widgets'
    
    'Tree, List and Icon Grid Widgets' group from GTK+ manual is:
    GtkTreeModel, GtkTreeSelection, GtkTreeViewColumn, GtkTreeView,
    GtkTreeView drag-and-drop, GtkCellView, GtkIconView, GtkTreeSortable,
    GtkTreeModelSort, GtkTreeModelFilter, GtkCellLayout, GtkCellArea,
    GtkCellAreaBox, GtkCellAreaContext, GtkCellRenderer, GtkCellEditable,
    GtkCellRendererXxxx, GtkListStore, GtkTreeStore.

 gtk/gtkcellarea.c        |   24 ++++++++++---------
 gtk/gtkcellarea.h        |    4 +-
 gtk/gtkcellareacontext.c |    2 +-
 gtk/gtkcellrenderer.c    |   40 ++++++++++++++++----------------
 gtk/gtkcellview.c        |    2 +-
 gtk/gtkiconview.c        |   40 +++++++++++++++++++--------------
 gtk/gtkliststore.c       |    8 ++++--
 gtk/gtktreednd.c         |    7 +++--
 gtk/gtktreemodel.c       |   14 +++++-----
 gtk/gtktreemodelfilter.c |   10 ++++----
 gtk/gtktreemodelfilter.h |    4 +-
 gtk/gtktreeselection.h   |    4 +-
 gtk/gtktreesortable.c    |    8 +++---
 gtk/gtktreestore.c       |    9 +++++--
 gtk/gtktreeview.c        |   56 +++++++++++++++++++++++----------------------
 gtk/gtktreeview.h        |    6 ++--
 gtk/gtktreeviewcolumn.c  |   17 +++++++------
 17 files changed, 136 insertions(+), 119 deletions(-)
---
diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c
index 0a94ca5..7ae3555 100644
--- a/gtk/gtkcellarea.c
+++ b/gtk/gtkcellarea.c
@@ -1623,7 +1623,7 @@ gtk_cell_area_has_renderer (GtkCellArea     *area,
 /**
  * gtk_cell_area_foreach:
  * @area: a #GtkCellArea
- * @callback: the #GtkCellCallback to call
+ * @callback: (scope call): the #GtkCellCallback to call
  * @callback_data: user provided data pointer
  *
  * Calls @callback for every #GtkCellRenderer in @area.
@@ -1656,7 +1656,7 @@ gtk_cell_area_foreach (GtkCellArea        *area,
  * @widget: the #GtkWidget that @area is rendering to
  * @cell_area: the @widget relative coordinates and size for @area
  * @background_area: the @widget relative coordinates of the background area
- * @callback: the #GtkCellAllocCallback to call
+ * @callback: (scope call): the #GtkCellAllocCallback to call
  * @callback_data: user provided data pointer
  *
  * Calls @callback for every #GtkCellRenderer in @area with the
@@ -1906,7 +1906,7 @@ get_cell_by_position (GtkCellRenderer     *renderer,
  * Gets the #GtkCellRenderer at @x and @y coordinates inside @area and optionally
  * returns the full cell allocation for it inside @cell_area.
  *
- * Return value: the #GtkCellRenderer at @x and @y.
+ * Return value: (transfer none): the #GtkCellRenderer at @x and @y.
  *
  * Since: 3.0
  */
@@ -2432,8 +2432,8 @@ gtk_cell_area_class_install_cell_property (GtkCellAreaClass   *aclass,
  *
  * Finds a cell property of a cell area class by name.
  *
- * Return value: (allow-none): the #GParamSpec of the child property or %NULL if @aclass has no
- *   child property with that name.
+ * Return value: (transfer none): the #GParamSpec of the child property
+ *   or %NULL if @aclass has no child property with that name.
  *
  * Since: 3.0
  */
@@ -2457,8 +2457,9 @@ gtk_cell_area_class_find_cell_property (GtkCellAreaClass   *aclass,
  *
  * Returns all cell properties of a cell area class.
  *
- * Return value: a newly allocated %NULL-terminated array of #GParamSpec*.
- *           The array must be freed with g_free().
+ * Return value: (array length=n_properties) (transfer container): a newly
+ *     allocated %NULL-terminated array of #GParamSpec*.  The array
+ *     must be freed with g_free().
  *
  * Since: 3.0
  */
@@ -2992,7 +2993,7 @@ gtk_cell_area_set_focus_cell (GtkCellArea     *area,
  *
  * Retrieves the currently focused cell for @area
  *
- * Return value: the currently focused cell in @area.
+ * Return value: (transfer none): the currently focused cell in @area.
  *
  * Since: 3.0
  */
@@ -3176,7 +3177,8 @@ gtk_cell_area_get_focus_siblings (GtkCellArea     *area,
  * then chose to activate the focus cell for which the event
  * cell may have been a sibling.
  *
- * Return value: the #GtkCellRenderer for which @renderer is a sibling, or %NULL.
+ * Return value: (transfer none): the #GtkCellRenderer for which @renderer
+ *    is a sibling, or %NULL.
  *
  * Since: 3.0
  */
@@ -3319,7 +3321,7 @@ gtk_cell_area_set_edit_widget (GtkCellArea     *area,
  * Gets the #GtkCellRenderer in @area that is currently
  * being edited.
  *
- * Return value: The currently edited #GtkCellRenderer
+ * Return value: (transfer none): The currently edited #GtkCellRenderer
  *
  * Since: 3.0
  */
@@ -3342,7 +3344,7 @@ gtk_cell_area_get_edited_cell (GtkCellArea *area)
  * Gets the #GtkCellEditable widget currently used
  * to edit the currently edited cell.
  *
- * Return value: The currently active #GtkCellEditable widget
+ * Return value: (transfer none): The currently active #GtkCellEditable widget
  *
  * Since: 3.0
  */
diff --git a/gtk/gtkcellarea.h b/gtk/gtkcellarea.h
index 78d5e95..2b0f707 100644
--- a/gtk/gtkcellarea.h
+++ b/gtk/gtkcellarea.h
@@ -62,7 +62,7 @@ typedef struct _GtkCellAreaContext       GtkCellAreaContext;
 /**
  * GtkCellCallback:
  * @renderer: the cell renderer to operate on
- * @data: user-supplied data
+ * @data: (closure): user-supplied data
  *
  * The type of the callback functions used for iterating over
  * the cell renderers of a #GtkCellArea, see gtk_cell_area_foreach().
@@ -79,7 +79,7 @@ typedef gboolean    (*GtkCellCallback) (GtkCellRenderer  *renderer,
  *     provided to gtk_cell_area_foreach_alloc().
  * @cell_background: the background area for @renderer inside the
  *     background area provided to gtk_cell_area_foreach_alloc().
- * @data: user-supplied data
+ * @data: (closure): user-supplied data
  *
  * The type of the callback functions used for iterating over the
  * cell renderers and their allocated areas inside a #GtkCellArea,
diff --git a/gtk/gtkcellareacontext.c b/gtk/gtkcellareacontext.c
index ca1ac3a..d085494 100644
--- a/gtk/gtkcellareacontext.c
+++ b/gtk/gtkcellareacontext.c
@@ -348,7 +348,7 @@ gtk_cell_area_context_real_allocate (GtkCellAreaContext *context,
  * that the #GtkCellArea is configured with in order to
  * compute a proper allocation.
  *
- * Return value: the #GtkCellArea this context was created by.
+ * Return value: (transfer none): the #GtkCellArea this context was created by.
  *
  * Since: 3.0
  */
diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c
index b2ef07b..a121622 100644
--- a/gtk/gtkcellrenderer.c
+++ b/gtk/gtkcellrenderer.c
@@ -613,10 +613,10 @@ set_cell_bg_color (GtkCellRenderer *cell,
  * @cell: a #GtkCellRenderer
  * @widget: the widget the renderer is rendering to
  * @cell_area: (allow-none): The area a cell will be allocated, or %NULL
- * @x_offset: (allow-none): location to return x offset of cell relative to @cell_area, or %NULL
- * @y_offset: (allow-none): location to return y offset of cell relative to @cell_area, or %NULL
- * @width: (allow-none): location to return width needed to render a cell, or %NULL
- * @height: (allow-none): location to return height needed to render a cell, or %NULL
+ * @x_offset: (out) (allow-none): location to return x offset of cell relative to @cell_area, or %NULL
+ * @y_offset: (out) (allow-none): location to return y offset of cell relative to @cell_area, or %NULL
+ * @width: (out) (allow-none): location to return width needed to render a cell, or %NULL
+ * @height: (out) (allow-none): location to return height needed to render a cell, or %NULL
  *
  * Obtains the width and height needed to render the cell. Used by view 
  * widgets to determine the appropriate size for the cell_area passed to
@@ -857,8 +857,8 @@ gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell,
 /**
  * gtk_cell_renderer_get_fixed_size:
  * @cell: A #GtkCellRenderer
- * @width: (allow-none): location to fill in with the fixed width of the cell, or %NULL
- * @height: (allow-none): location to fill in with the fixed height of the cell, or %NULL
+ * @width: (out) (allow-none): location to fill in with the fixed width of the cell, or %NULL
+ * @height: (out) (allow-none): location to fill in with the fixed height of the cell, or %NULL
  *
  * Fills in @width and @height with the appropriate size of @cell.
  **/
@@ -925,8 +925,8 @@ gtk_cell_renderer_set_alignment (GtkCellRenderer *cell,
 /**
  * gtk_cell_renderer_get_alignment:
  * @cell: A #GtkCellRenderer
- * @xalign: (allow-none): location to fill in with the x alignment of the cell, or %NULL
- * @yalign: (allow-none): location to fill in with the y alignment of the cell, or %NULL
+ * @xalign: (out) (allow-none): location to fill in with the x alignment of the cell, or %NULL
+ * @yalign: (out) (allow-none): location to fill in with the y alignment of the cell, or %NULL
  *
  * Fills in @xalign and @yalign with the appropriate values of @cell.
  *
@@ -994,8 +994,8 @@ gtk_cell_renderer_set_padding (GtkCellRenderer *cell,
 /**
  * gtk_cell_renderer_get_padding:
  * @cell: A #GtkCellRenderer
- * @xpad: (allow-none): location to fill in with the x padding of the cell, or %NULL
- * @ypad: (allow-none): location to fill in with the y padding of the cell, or %NULL
+ * @xpad: (out) (allow-none): location to fill in with the x padding of the cell, or %NULL
+ * @ypad: (out) (allow-none): location to fill in with the y padding of the cell, or %NULL
  *
  * Fills in @xpad and @ypad with the appropriate values of @cell.
  *
@@ -1374,8 +1374,8 @@ gtk_cell_renderer_get_request_mode (GtkCellRenderer *cell)
  * gtk_cell_renderer_get_preferred_width:
  * @cell: a #GtkCellRenderer instance
  * @widget: the #GtkWidget this cell will be rendering to
- * @minimum_size: location to store the minimum size, or %NULL
- * @natural_size: location to store the natural size, or %NULL
+ * @minimum_size: (out) (allow-none): location to store the minimum size, or %NULL
+ * @natural_size: (out) (allow-none): location to store the natural size, or %NULL
  *
  * Retreives a renderer's natural size when rendered to @widget.
  *
@@ -1422,8 +1422,8 @@ gtk_cell_renderer_get_preferred_width (GtkCellRenderer *cell,
  * gtk_cell_renderer_get_preferred_height:
  * @cell: a #GtkCellRenderer instance
  * @widget: the #GtkWidget this cell will be rendering to
- * @minimum_size: location to store the minimum size, or %NULL
- * @natural_size: location to store the natural size, or %NULL
+ * @minimum_size: (out) (allow-none): location to store the minimum size, or %NULL
+ * @natural_size: (out) (allow-none): location to store the natural size, or %NULL
  *
  * Retreives a renderer's natural size when rendered to @widget.
  *
@@ -1471,8 +1471,8 @@ gtk_cell_renderer_get_preferred_height (GtkCellRenderer *cell,
  * @cell: a #GtkCellRenderer instance
  * @widget: the #GtkWidget this cell will be rendering to
  * @height: the size which is available for allocation
- * @minimum_width: location for storing the minimum size, or %NULL
- * @natural_width: location for storing the preferred size, or %NULL
+ * @minimum_width: (out) (allow-none): location for storing the minimum size, or %NULL
+ * @natural_width: (out) (allow-none): location for storing the preferred size, or %NULL
  *
  * Retreives a cell renderers's minimum and natural width if it were rendered to 
  * @widget with the specified @height.
@@ -1521,8 +1521,8 @@ gtk_cell_renderer_get_preferred_width_for_height (GtkCellRenderer *cell,
  * @cell: a #GtkCellRenderer instance
  * @widget: the #GtkWidget this cell will be rendering to
  * @width: the size which is available for allocation
- * @minimum_height: location for storing the minimum size, or %NULL
- * @natural_height: location for storing the preferred size, or %NULL
+ * @minimum_height: (out) (allow-none): location for storing the minimum size, or %NULL
+ * @natural_height: (out) (allow-none): location for storing the preferred size, or %NULL
  *
  * Retreives a cell renderers's minimum and natural height if it were rendered to 
  * @widget with the specified @width.
@@ -1633,8 +1633,8 @@ gtk_cell_renderer_get_preferred_size (GtkCellRenderer *cell,
  * @widget: the #GtkWidget this cell will be rendering to
  * @flags: render flags
  * @cell_area: cell area which would be passed to gtk_cell_renderer_render()
- * @aligned_area: the return location for the space inside @cell_area that
- *                would acually be used to render.
+ * @aligned_area: (out): the return location for the space inside @cell_area
+ *                that would acually be used to render.
  *
  * Gets the aligned area used by @cell inside @cell_area. Used for finding
  * the appropriate edit and focus rectangle.
diff --git a/gtk/gtkcellview.c b/gtk/gtkcellview.c
index 168bf04..3d11c88 100644
--- a/gtk/gtkcellview.c
+++ b/gtk/gtkcellview.c
@@ -1177,7 +1177,7 @@ gtk_cell_view_get_displayed_row (GtkCellView *cell_view)
  * gtk_cell_view_get_size_of_row:
  * @cell_view: a #GtkCellView
  * @path: a #GtkTreePath 
- * @requisition: return location for the size 
+ * @requisition: (out): return location for the size 
  *
  * Sets @requisition to the size needed by @cell_view to display 
  * the model row pointed to by @path.
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index 47dc4c7..5bd16dc 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -1934,8 +1934,9 @@ gtk_icon_view_set_cursor (GtkIconView     *icon_view,
 /**
  * gtk_icon_view_get_cursor:
  * @icon_view: A #GtkIconView
- * @path: (allow-none): Return location for the current cursor path, or %NULL
- * @cell: (allow-none): Return location the current focus cell, or %NULL
+ * @path: (out) (allow-none): Return location for the current cursor path,
+ *        or %NULL
+ * @cell: (out) (allow-none): Return location the current focus cell, or %NULL
  *
  * Fills in @path and @cell with the current cursor path and cell. 
  * If the cursor isn't currently set, then * path will be %NULL.  
@@ -4202,8 +4203,8 @@ gtk_icon_view_new_with_model (GtkTreeModel *model)
  * @icon_view: a #GtkIconView 
  * @wx: X coordinate relative to the widget
  * @wy: Y coordinate relative to the widget
- * @bx: return location for bin_window X coordinate
- * @by: return location for bin_window Y coordinate
+ * @bx: (out): return location for bin_window X coordinate
+ * @by: (out): return location for bin_window Y coordinate
  * 
  * Converts widget coordinates to coordinates for the bin_window,
  * as expected by e.g. gtk_icon_view_get_path_at_pos(). 
@@ -4274,9 +4275,9 @@ gtk_icon_view_get_path_at_pos (GtkIconView *icon_view,
  * @icon_view: A #GtkIconView.
  * @x: The x position to be identified
  * @y: The y position to be identified
- * @path: (allow-none): Return location for the path, or %NULL
- * @cell: Return location for the renderer responsible for the cell
- *   at (@x, @y), or %NULL
+ * @path: (out) (allow-none): Return location for the path, or %NULL
+ * @cell: (out) (allow-none): Return location for the renderer
+ *   responsible for the cell at (@x, @y), or %NULL
  * 
  * Finds the path at the point (@x, @y), relative to bin_window coordinates.
  * In contrast to gtk_icon_view_get_path_at_pos(), this function also 
@@ -4562,7 +4563,7 @@ gtk_icon_view_set_tooltip_column (GtkIconView *icon_view,
   g_object_notify (G_OBJECT (icon_view), "tooltip-column");
 }
 
-/** 
+/**
  * gtk_icon_view_get_tooltip_column:
  * @icon_view: a #GtkIconView
  *
@@ -4585,8 +4586,9 @@ gtk_icon_view_get_tooltip_column (GtkIconView *icon_view)
 /**
  * gtk_icon_view_get_visible_range:
  * @icon_view: A #GtkIconView
- * @start_path: (allow-none): Return location for start of region, or %NULL
- * @end_path: (allow-none): Return location for end of region, or %NULL
+ * @start_path: (out) (allow-none): Return location for start of region,
+ *              or %NULL
+ * @end_path: (out) (allow-none): Return location for end of region, or %NULL
  * 
  * Sets @start_path and @end_path to be the first and last visible path. 
  * Note that there may be invisible paths in between.
@@ -6548,7 +6550,8 @@ gtk_icon_view_drag_data_received (GtkWidget        *widget,
  * gtk_icon_view_enable_model_drag_source:
  * @icon_view: a #GtkIconTreeView
  * @start_button_mask: Mask of allowed buttons to start drag
- * @targets: the table of targets that the drag will support
+ * @targets: (array length=n_targets): the table of targets that
+ *    the drag will support
  * @n_targets: the number of items in @targets
  * @actions: the bitmask of possible actions for a drag from this
  *    widget
@@ -6580,7 +6583,8 @@ gtk_icon_view_enable_model_drag_source (GtkIconView              *icon_view,
 /**
  * gtk_icon_view_enable_model_drag_dest:
  * @icon_view: a #GtkIconView
- * @targets: the table of targets that the drag will support
+ * @targets: (array length=n_targets): the table of targets that
+ *    the drag will support
  * @n_targets: the number of items in @targets
  * @actions: the bitmask of possible actions for a drag to this
  *    widget
@@ -6716,8 +6720,9 @@ gtk_icon_view_set_drag_dest_item (GtkIconView              *icon_view,
 /**
  * gtk_icon_view_get_drag_dest_item:
  * @icon_view: a #GtkIconView
- * @path: (allow-none): Return location for the path of the highlighted item, or %NULL.
- * @pos: (allow-none): Return location for the drop position, or %NULL
+ * @path: (out) (allow-none): Return location for the path of
+ *        the highlighted item, or %NULL.
+ * @pos: (out) (allow-none): Return location for the drop position, or %NULL
  * 
  * Gets information about the item that is highlighted for feedback.
  *
@@ -6747,8 +6752,9 @@ gtk_icon_view_get_drag_dest_item (GtkIconView              *icon_view,
  * @icon_view: a #GtkIconView
  * @drag_x: the position to determine the destination item for
  * @drag_y: the position to determine the destination item for
- * @path: (allow-none): Return location for the path of the item, or %NULL.
- * @pos: (allow-none): Return location for the drop position, or %NULL
+ * @path: (out) (allow-none): Return location for the path of the item,
+ *    or %NULL.
+ * @pos: (out) (allow-none): Return location for the drop position, or %NULL
  * 
  * Determines the destination item for a given position.
  * 
@@ -6814,7 +6820,7 @@ gtk_icon_view_get_dest_item_at_pos (GtkIconView              *icon_view,
  * Creates a #cairo_surface_t representation of the item at @path.  
  * This image is used for a drag icon.
  *
- * Return value: (transfer full) a newly-allocated surface of the drag icon.
+ * Return value: (transfer full): a newly-allocated surface of the drag icon.
  * 
  * Since: 2.8
  **/
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 4d9c1dd..8311b3d 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -304,6 +304,7 @@ gtk_list_store_new (gint n_columns,
  * Non-vararg creation function.  Used primarily by language bindings.
  *
  * Return value: (transfer none): a new #GtkListStore
+ * Rename to: gtk_list_store_new
  **/
 GtkListStore *
 gtk_list_store_newv (gint   n_columns,
@@ -920,6 +921,7 @@ gtk_list_store_set_valist_internal (GtkListStore *list_store,
  * change is not known until run-time.
  *
  * Since: 2.12
+ * Rename to: gtk_list_store_set
  */
 void
 gtk_list_store_set_valuesv (GtkListStore *list_store,
@@ -1531,7 +1533,7 @@ gtk_list_store_reorder_func (GSequenceIter *a,
 }
   
 /**
- * gtk_list_store_reorder:
+ * gtk_list_store_reorder: (skip)
  * @store: A #GtkListStore.
  * @new_order: an array of integers mapping the new position of each child
  *      to its old position before the re-ordering,
@@ -2100,8 +2102,8 @@ gtk_list_store_insert_with_values (GtkListStore *list_store,
  * @list_store: A #GtkListStore
  * @iter: (out) (allow-none): An unset #GtkTreeIter to set to the new row, or %NULL.
  * @position: position to insert the new row
- * @columns: an array of column numbers
- * @values: an array of GValues 
+ * @columns: (array length=n_values): an array of column numbers
+ * @values: (array length=n_values): an array of GValues 
  * @n_values: the length of the @columns and @values arrays
  * 
  * A variant of gtk_list_store_insert_with_values() which
diff --git a/gtk/gtktreednd.c b/gtk/gtktreednd.c
index 68cc171..367fbd6 100644
--- a/gtk/gtktreednd.c
+++ b/gtk/gtktreednd.c
@@ -159,7 +159,8 @@ gtk_tree_drag_source_drag_data_delete (GtkTreeDragSource *drag_source,
  * gtk_tree_drag_source_drag_data_get:
  * @drag_source: a #GtkTreeDragSource
  * @path: row that was dragged
- * @selection_data: a #GtkSelectionData to fill with data from the dragged row
+ * @selection_data: (out): a #GtkSelectionData to fill with data
+ *                  from the dragged row
  * 
  * Asks the #GtkTreeDragSource to fill in @selection_data with a
  * representation of the row at @path. @selection_data->target gives
@@ -306,8 +307,8 @@ gtk_tree_set_row_drag_data (GtkSelectionData *selection_data,
 /**
  * gtk_tree_get_row_drag_data:
  * @selection_data: a #GtkSelectionData
- * @tree_model: a #GtkTreeModel
- * @path: row in @tree_model
+ * @tree_model: (out): a #GtkTreeModel
+ * @path: (out): row in @tree_model
  * 
  * Obtains a @tree_model and @path from selection data of target type
  * %GTK_TREE_MODEL_ROW. Normally called from a drag_data_received handler.
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index 7b6622f..5456199 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -251,7 +251,7 @@ gtk_tree_model_base_init (gpointer g_class)
                        row_deleted_params);
 
       /**
-       * GtkTreeModel::rows-reordered:
+       * GtkTreeModel::rows-reordered: (skip)
        * @tree_model: the #GtkTreeModel on which the signal is emitted
        * @path: a #GtkTreePath identifying the tree node whose children
        *        have been reordered
@@ -961,7 +961,7 @@ gtk_tree_model_get_n_columns (GtkTreeModel *tree_model)
  *
  * Returns the type of the column.
  *
- * Return value: (transfer none): The type of the column.
+ * Return value: The type of the column.
  **/
 GType
 gtk_tree_model_get_column_type (GtkTreeModel *tree_model,
@@ -1131,7 +1131,7 @@ gtk_tree_model_get_path (GtkTreeModel *tree_model,
  * @tree_model: A #GtkTreeModel.
  * @iter: The #GtkTreeIter.
  * @column: The column to lookup the value at.
- * @value: (out) (transfer none): An empty #GValue to set.
+ * @value: (out): An empty #GValue to set.
  *
  * Initializes and sets @value to that at @column.
  * When done with @value, g_value_unset() needs to be called 
@@ -1158,7 +1158,7 @@ gtk_tree_model_get_value (GtkTreeModel *tree_model,
 /**
  * gtk_tree_model_iter_next:
  * @tree_model: A #GtkTreeModel.
- * @iter: (in): The #GtkTreeIter.
+ * @iter: The #GtkTreeIter.
  *
  * Sets @iter to point to the node following it at the current level.  If there
  * is no next @iter, %FALSE is returned and @iter is set to be invalid.
@@ -1204,7 +1204,7 @@ gtk_tree_model_iter_previous_default (GtkTreeModel *tree_model,
 /**
  * gtk_tree_model_iter_previous:
  * @tree_model: a #GtkTreeModel
- * @iter: (inout): the #GtkTreeIter
+ * @iter: the #GtkTreeIter
  *
  * Sets @iter to point to the previous node at the current level. If there
  * is no previous @iter, %FALSE is returned and @iter is set to be invalid.
@@ -1606,7 +1606,7 @@ gtk_tree_model_row_deleted (GtkTreeModel *tree_model,
 }
 
 /**
- * gtk_tree_model_rows_reordered:
+ * gtk_tree_model_rows_reordered: (skip)
  * @tree_model: A #GtkTreeModel
  * @path: A #GtkTreePath pointing to the tree node whose children have been 
  *      reordered
@@ -2199,7 +2199,7 @@ gtk_tree_row_reference_deleted (GObject     *proxy,
 }
 
 /**
- * gtk_tree_row_reference_reordered:
+ * gtk_tree_row_reference_reordered: (skip)
  * @proxy: A #GObject
  * @path: The parent path of the reordered signal
  * @iter: The iter pointing to the parent of the reordered
diff --git a/gtk/gtktreemodelfilter.c b/gtk/gtktreemodelfilter.c
index 18e0d59..f8431b9 100644
--- a/gtk/gtktreemodelfilter.c
+++ b/gtk/gtktreemodelfilter.c
@@ -3113,8 +3113,8 @@ gtk_tree_model_filter_get_model (GtkTreeModelFilter *filter)
  * gtk_tree_model_filter_set_visible_func:
  * @filter: A #GtkTreeModelFilter.
  * @func: A #GtkTreeModelFilterVisibleFunc, the visible function.
- * @data: (allow-none): User data to pass to the visible function, or %NULL.
- * @destroy: (allow-none): Destroy notifier of @data, or %NULL.
+ * @data: User data to pass to the visible function, or %NULL.
+ * @destroy: Destroy notifier of @data, or %NULL.
  *
  * Sets the visible function used when filtering the @filter to be @func. The
  * function should return %TRUE if the given row should be visible and
@@ -3171,10 +3171,10 @@ gtk_tree_model_filter_set_visible_func (GtkTreeModelFilter            *filter,
  * gtk_tree_model_filter_set_modify_func:
  * @filter: A #GtkTreeModelFilter.
  * @n_columns: The number of columns in the filter model.
- * @types: The #GType<!-- -->s of the columns.
+ * @types: (array length=n_columns): The #GType<!-- -->s of the columns.
  * @func: A #GtkTreeModelFilterModifyFunc
- * @data: (allow-none): User data to pass to the modify function, or %NULL.
- * @destroy: (allow-none): Destroy notifier of @data, or %NULL.
+ * @data: User data to pass to the modify function, or %NULL.
+ * @destroy: Destroy notifier of @data, or %NULL.
  *
  * With the @n_columns and @types parameters, you give an array of column
  * types for this model (which will be exposed to the parent model/view).
diff --git a/gtk/gtktreemodelfilter.h b/gtk/gtktreemodelfilter.h
index b8c3376..b887a0a 100644
--- a/gtk/gtktreemodelfilter.h
+++ b/gtk/gtktreemodelfilter.h
@@ -41,7 +41,7 @@ G_BEGIN_DECLS
  * @model: the child model of the #GtkTreeModelFilter
  * @iter: a #GtkTreeIter pointing to the row in @model whose visibility
  *   is determined
- * @data: user data given to gtk_tree_model_filter_set_visible_func()
+ * @data: (closure): user data given to gtk_tree_model_filter_set_visible_func()
  *
  * A function which decides whether the row indicated by @iter is visible.
  *
@@ -58,7 +58,7 @@ typedef gboolean (* GtkTreeModelFilterVisibleFunc) (GtkTreeModel *model,
  * @value: A #GValue which is already initialized for with the correct type for
  *  the column @column.
  * @column: the column whose display value is determined
- * @data: user data given to gtk_tree_model_filter_set_modify_func()
+ * @data: (closure): user data given to gtk_tree_model_filter_set_modify_func()
  *
  * A function which calculates display values from raw values in the model.
  * It must fill @value with the display value for the column @column in the
diff --git a/gtk/gtktreeselection.h b/gtk/gtktreeselection.h
index 36cfafa..9dfdb9f 100644
--- a/gtk/gtktreeselection.h
+++ b/gtk/gtktreeselection.h
@@ -44,7 +44,7 @@ typedef struct _GtkTreeSelectionPrivate      GtkTreeSelectionPrivate;
  * @model: A #GtkTreeModel being viewed
  * @path: The #GtkTreePath of the row in question
  * @path_currently_selected: %TRUE, if the path is currently selected
- * @data: user data
+ * @data: (closure): user data
  *
  * A function used by gtk_tree_selection_set_select_function() to filter
  * whether or not a row may be selected.  It is called whenever a row's
@@ -64,7 +64,7 @@ typedef gboolean (* GtkTreeSelectionFunc)    (GtkTreeSelection  *selection,
  * @model: The #GtkTreeModel being viewed
  * @path: The #GtkTreePath of a selected row
  * @iter: A #GtkTreeIter pointing to a selected row
- * @data: user data
+ * @data: (closure): user data
  *
  * A function used by gtk_tree_selection_selected_foreach() to map all
  * selected rows.  It will be called on every selected row in the view.
diff --git a/gtk/gtktreesortable.c b/gtk/gtktreesortable.c
index 111a3e5..f8b09a0 100644
--- a/gtk/gtktreesortable.c
+++ b/gtk/gtktreesortable.c
@@ -182,8 +182,8 @@ gtk_tree_sortable_set_sort_column_id (GtkTreeSortable  *sortable,
  * @sortable: A #GtkTreeSortable
  * @sort_column_id: the sort column id to set the function for
  * @sort_func: The comparison function
- * @user_data: (allow-none): User data to pass to @sort_func, or %NULL
- * @destroy: (allow-none): Destroy notifier of @user_data, or %NULL
+ * @user_data: User data to pass to @sort_func, or %NULL
+ * @destroy: Destroy notifier of @user_data, or %NULL
  * 
  * Sets the comparison function used when sorting to be @sort_func. If the
  * current sort column id of @sortable is the same as @sort_column_id, then 
@@ -214,8 +214,8 @@ gtk_tree_sortable_set_sort_func (GtkTreeSortable        *sortable,
  * gtk_tree_sortable_set_default_sort_func:
  * @sortable: A #GtkTreeSortable
  * @sort_func: The comparison function
- * @user_data: (allow-none): User data to pass to @sort_func, or %NULL
- * @destroy: (allow-none): Destroy notifier of @user_data, or %NULL
+ * @user_data: User data to pass to @sort_func, or %NULL
+ * @destroy: Destroy notifier of @user_data, or %NULL
  * 
  * Sets the default comparison function used when sorting to be @sort_func.  
  * If the current sort column id of @sortable is
diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index d9a76a9..ec43c38 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -354,6 +354,7 @@ gtk_tree_store_new (gint n_columns,
  * Non vararg creation function.  Used primarily by language bindings.
  *
  * Return value: (transfer full): a new #GtkTreeStore
+ * Rename to: gtk_tree_store_new
  **/
 GtkTreeStore *
 gtk_tree_store_newv (gint   n_columns,
@@ -1084,6 +1085,7 @@ gtk_tree_store_set_valist_internal (GtkTreeStore *tree_store,
  * the number of columns to change is not known until run-time.
  *
  * Since: 2.12
+ * Rename to: gtk_tree_store_set
  **/
 void
 gtk_tree_store_set_valuesv (GtkTreeStore *tree_store,
@@ -1576,8 +1578,8 @@ gtk_tree_store_insert_with_values (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
- * @columns: an array of column numbers
- * @values: an array of GValues
+ * @columns: (array length=n_values): an array of column numbers
+ * @values: (array length=n_values): an array of GValues
  * @n_values: the length of the @columns and @values arrays
  *
  * A variant of gtk_tree_store_insert_with_values() which takes
@@ -1585,6 +1587,7 @@ gtk_tree_store_insert_with_values (GtkTreeStore *tree_store,
  * function is mainly intended for language bindings.
  *
  * Since: 2.10
+ * Rename to: gtk_tree_store_insert_with_values
  */
 void
 gtk_tree_store_insert_with_valuesv (GtkTreeStore *tree_store,
@@ -2245,7 +2248,7 @@ gtk_tree_store_reorder_func (gconstpointer a,
 }
 
 /**
- * gtk_tree_store_reorder:
+ * gtk_tree_store_reorder: (skip)
  * @tree_store: A #GtkTreeStore.
  * @parent: A #GtkTreeIter.
  * @new_order: an array of integers mapping the new position of each child
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index 76b748f..1b22266 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -13583,7 +13583,7 @@ gtk_tree_view_get_cell_area_y_offset (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @path: (allow-none): a #GtkTreePath for the row, or %NULL to get only horizontal coordinates
  * @column: (allow-none): a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordinates
- * @rect: rectangle to fill with cell rect
+ * @rect: (out): rectangle to fill with cell rect
  *
  * Fills the bounding rectangle in bin_window coordinates for the cell at the
  * row specified by @path and the column specified by @column.  If @path is
@@ -13716,7 +13716,7 @@ gtk_tree_view_get_row_y_offset (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @path: (allow-none): a #GtkTreePath for the row, or %NULL to get only horizontal coordinates
  * @column: (allow-none): a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordiantes
- * @rect: rectangle to fill with cell background rect
+ * @rect: (out): rectangle to fill with cell background rect
  *
  * Fills the bounding rectangle in bin_window coordinates for the cell at the
  * row specified by @path and the column specified by @column.  If @path is
@@ -13771,7 +13771,7 @@ gtk_tree_view_get_background_area (GtkTreeView        *tree_view,
 /**
  * gtk_tree_view_get_visible_rect:
  * @tree_view: a #GtkTreeView
- * @visible_rect: rectangle to fill
+ * @visible_rect: (out): rectangle to fill
  *
  * Fills @visible_rect with the currently-visible region of the
  * buffer, in tree coordinates. Convert to bin_window coordinates with
@@ -13805,8 +13805,8 @@ gtk_tree_view_get_visible_rect (GtkTreeView  *tree_view,
  * @tree_view: a #GtkTreeView
  * @wx: X coordinate relative to the widget
  * @wy: Y coordinate relative to the widget
- * @tx: return location for tree X coordinate
- * @ty: return location for tree Y coordinate
+ * @tx: (out): return location for tree X coordinate
+ * @ty: (out): return location for tree Y coordinate
  *
  * Converts widget coordinates to coordinates for the
  * tree (the full scrollable area of the tree).
@@ -13837,8 +13837,8 @@ gtk_tree_view_convert_widget_to_tree_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @tx: X coordinate relative to the tree
  * @ty: Y coordinate relative to the tree
- * @wx: return location for widget X coordinate
- * @wy: return location for widget Y coordinate
+ * @wx: (out): return location for widget X coordinate
+ * @wy: (out): return location for widget Y coordinate
  *
  * Converts tree coordinates (coordinates in full scrollable area of the tree)
  * to widget coordinates.
@@ -13869,8 +13869,8 @@ gtk_tree_view_convert_tree_to_widget_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @wx: X coordinate relative to the widget
  * @wy: Y coordinate relative to the widget
- * @bx: return location for bin_window X coordinate
- * @by: return location for bin_window Y coordinate
+ * @bx: (out): return location for bin_window X coordinate
+ * @by: (out): return location for bin_window Y coordinate
  *
  * Converts widget coordinates to coordinates for the bin_window
  * (see gtk_tree_view_get_bin_window()).
@@ -13897,8 +13897,8 @@ gtk_tree_view_convert_widget_to_bin_window_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @bx: bin_window X coordinate
  * @by: bin_window Y coordinate
- * @wx: return location for widget X coordinate
- * @wy: return location for widget Y coordinate
+ * @wx: (out): return location for widget X coordinate
+ * @wy: (out): return location for widget Y coordinate
  *
  * Converts bin_window coordinates (see gtk_tree_view_get_bin_window())
  * to widget relative coordinates.
@@ -13925,8 +13925,8 @@ gtk_tree_view_convert_bin_window_to_widget_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @tx: tree X coordinate
  * @ty: tree Y coordinate
- * @bx: return location for X coordinate relative to bin_window
- * @by: return location for Y coordinate relative to bin_window
+ * @bx: (out): return location for X coordinate relative to bin_window
+ * @by: (out): return location for Y coordinate relative to bin_window
  *
  * Converts tree coordinates (coordinates in full scrollable area of the tree)
  * to bin_window coordinates.
@@ -13953,8 +13953,8 @@ gtk_tree_view_convert_tree_to_bin_window_coords (GtkTreeView *tree_view,
  * @tree_view: a #GtkTreeView
  * @bx: X coordinate relative to bin_window
  * @by: Y coordinate relative to bin_window
- * @tx: return location for tree X coordinate
- * @ty: return location for tree Y coordinate
+ * @tx: (out): return location for tree X coordinate
+ * @ty: (out): return location for tree Y coordinate
  *
  * Converts bin_window coordinates to coordinates for the
  * tree (the full scrollable area of the tree).
@@ -13981,8 +13981,9 @@ gtk_tree_view_convert_bin_window_to_tree_coords (GtkTreeView *tree_view,
 /**
  * gtk_tree_view_get_visible_range:
  * @tree_view: A #GtkTreeView
- * @start_path: (allow-none): Return location for start of region, or %NULL.
- * @end_path: (allow-none): Return location for end of region, or %NULL.
+ * @start_path: (out) (allow-none): Return location for start of region,
+ *              or %NULL.
+ * @end_path: (out) (allow-none): Return location for end of region, or %NULL.
  *
  * Sets @start_path and @end_path to be the first and last visible path.
  * Note that there may be invisible paths in between.
@@ -14193,7 +14194,8 @@ gtk_tree_view_enable_model_drag_source (GtkTreeView              *tree_view,
 /**
  * gtk_tree_view_enable_model_drag_dest:
  * @tree_view: a #GtkTreeView
- * @targets: (array): the table of targets that the drag will support
+ * @targets: (array length=n_targets): the table of targets that
+ *           the drag will support
  * @n_targets: the number of items in @targets
  * @actions: the bitmask of possible actions for a drag from this
  *    widget
@@ -14777,7 +14779,7 @@ gtk_tree_view_set_search_column (GtkTreeView *tree_view,
 }
 
 /**
- * gtk_tree_view_get_search_equal_func:
+ * gtk_tree_view_get_search_equal_func: (skip)
  * @tree_view: A #GtkTreeView
  *
  * Returns the compare function currently in use.
@@ -14797,8 +14799,8 @@ gtk_tree_view_get_search_equal_func (GtkTreeView *tree_view)
  * gtk_tree_view_set_search_equal_func:
  * @tree_view: A #GtkTreeView
  * @search_equal_func: the compare function to use during the search
- * @search_user_data: (allow-none): user data to pass to @search_equal_func, or %NULL
- * @search_destroy: (allow-none): Destroy notifier for @search_user_data, or %NULL
+ * @search_user_data: user data to pass to @search_equal_func, or %NULL
+ * @search_destroy: Destroy notifier for @search_user_data, or %NULL
  *
  * Sets the compare function for the interactive search capabilities; note
  * that somewhat like strcmp() returning 0 for equality
@@ -14918,8 +14920,8 @@ gtk_tree_view_set_search_entry (GtkTreeView *tree_view,
  * @tree_view: A #GtkTreeView
  * @func: (allow-none): the function to use to position the search dialog, or %NULL
  *    to use the default search position function
- * @data: (allow-none): user data to pass to @func, or %NULL
- * @destroy: (allow-none): Destroy notifier for @data, or %NULL
+ * @data: user data to pass to @func, or %NULL
+ * @destroy: Destroy notifier for @data, or %NULL
  *
  * Sets the function to use when positioning the search dialog.
  *
@@ -14944,7 +14946,7 @@ gtk_tree_view_set_search_position_func (GtkTreeView                   *tree_view
 }
 
 /**
- * gtk_tree_view_get_search_position_func:
+ * gtk_tree_view_get_search_position_func: (skip)
  * @tree_view: A #GtkTreeView
  *
  * Returns the positioning function currently in use.
@@ -15794,7 +15796,7 @@ gtk_tree_view_is_rubber_banding_active (GtkTreeView *tree_view)
 }
 
 /**
- * gtk_tree_view_get_row_separator_func:
+ * gtk_tree_view_get_row_separator_func: (skip)
  * @tree_view: a #GtkTreeView
  * 
  * Returns the current row separator function.
@@ -15815,8 +15817,8 @@ gtk_tree_view_get_row_separator_func (GtkTreeView *tree_view)
  * gtk_tree_view_set_row_separator_func:
  * @tree_view: a #GtkTreeView
  * @func: (allow-none): a #GtkTreeViewRowSeparatorFunc
- * @data: (allow-none): user data to pass to @func, or %NULL
- * @destroy: (allow-none): destroy notifier for @data, or %NULL
+ * @data: user data to pass to @func, or %NULL
+ * @destroy: destroy notifier for @data, or %NULL
  * 
  * Sets the row separator function, which is used to determine
  * whether a row should be drawn as a separator. If the row separator
diff --git a/gtk/gtktreeview.h b/gtk/gtktreeview.h
index 9e2227b..80aa134 100644
--- a/gtk/gtktreeview.h
+++ b/gtk/gtktreeview.h
@@ -129,7 +129,7 @@ struct _GtkTreeViewClass
  * @column: The #GtkTreeViewColumn being dragged
  * @prev_column: A #GtkTreeViewColumn on one side of @column
  * @next_column: A #GtkTreeViewColumn on the other side of @column
- * @data: user data
+ * @data: (closure): user data
  *
  * Function type for determining whether @column can be dropped in a
  * particular spot (as determined by @prev_column and @next_column).  In
@@ -167,7 +167,7 @@ typedef void     (* GtkTreeViewMappingFunc)    (GtkTreeView             *tree_vi
  * @key: the key string to compare with
  * @iter: a #GtkTreeIter pointing the row of @model that should be compared
  *  with @key.
- * @search_data: user data from gtk_tree_view_set_search_equal_func()
+ * @search_data: (closure): user data from gtk_tree_view_set_search_equal_func()
  *
  * A function used for checking whether a row in @model matches
  * a search key string entered by the user. Note the return value
@@ -186,7 +186,7 @@ typedef gboolean (*GtkTreeViewSearchEqualFunc) (GtkTreeModel            *model,
  * GtkTreeViewRowSeparatorFunc:
  * @model: the #GtkTreeModel
  * @iter: a #GtkTreeIter pointing at a row in @model
- * @data: user data
+ * @data: (closure): user data
  *
  * Function type for determining whether the row pointed to by @iter should
  * be rendered as a separator. A common way to implement this is to have a
diff --git a/gtk/gtktreeviewcolumn.c b/gtk/gtktreeviewcolumn.c
index eebcf5e..ad338e8 100644
--- a/gtk/gtktreeviewcolumn.c
+++ b/gtk/gtktreeviewcolumn.c
@@ -1770,7 +1770,7 @@ gtk_tree_view_column_set_attributes (GtkTreeViewColumn *tree_column,
  * gtk_tree_view_column_set_cell_data_func:
  * @tree_column: A #GtkTreeViewColumn
  * @cell_renderer: A #GtkCellRenderer
- * @func: The #GtkTreeViewColumnFunc to use. 
+ * @func: (allow-none): The #GtkTreeViewColumnFunc to use. 
  * @func_data: The user data for @func.
  * @destroy: The destroy notification for @func_data
  * 
@@ -2792,10 +2792,10 @@ gtk_tree_view_column_cell_set_cell_data (GtkTreeViewColumn *tree_column,
  * gtk_tree_view_column_cell_get_size:
  * @tree_column: A #GtkTreeViewColumn.
  * @cell_area: (allow-none): The area a cell in the column will be allocated, or %NULL
- * @x_offset: (allow-none): location to return x offset of a cell relative to @cell_area, or %NULL
- * @y_offset: (allow-none): location to return y offset of a cell relative to @cell_area, or %NULL
- * @width: (allow-none): location to return width needed to render a cell, or %NULL
- * @height: (allow-none): location to return height needed to render a cell, or %NULL
+ * @x_offset: (out) (allow-none): location to return x offset of a cell relative to @cell_area, or %NULL
+ * @y_offset: (out) (allow-none): location to return y offset of a cell relative to @cell_area, or %NULL
+ * @width: (out) (allow-none): location to return width needed to render a cell, or %NULL
+ * @height: (out) (allow-none): location to return height needed to render a cell, or %NULL
  * 
  * Obtains the width and height needed to render the column.  This is used
  * primarily by the #GtkTreeView.
@@ -2994,9 +2994,10 @@ _gtk_tree_view_column_cell_get_dirty (GtkTreeViewColumn  *tree_column)
  * gtk_tree_view_column_cell_get_position:
  * @tree_column: a #GtkTreeViewColumn
  * @cell_renderer: a #GtkCellRenderer
- * @x_offset: return location for the horizontal position of @cell within
- *            @tree_column, may be %NULL
- * @width: return location for the width of @cell, may be %NULL
+ * @x_offset: (out) (allow-none): return location for the horizontal
+ *            position of @cell within @tree_column, may be %NULL
+ * @width: (out) (allow-none): return location for the width of @cell,
+ *         may be %NULL
  *
  * Obtains the horizontal position and size of a cell in a column. If the
  * cell is not found in the column, @start_pos and @width are not changed and
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]