Merge branch 'sophie-h/gtk-nullables-2'

Merge Sophie's nullable annotations, with some documentation
fixups on top.

gtk/gtkcenterlayout.c

@@ -619,9 +619,11 @@ gtk_center_layout_get_baseline_position (GtkCenterLayout *self)
 /**
  * gtk_center_layout_set_start_widget:
  * @self: a #GtkCenterLayout
- * @widget: the new start widget
+ * @widget (nullable): the new start widget
  *
  * Sets the new start widget of @self.
+ *
+ * To remove the existing start widget, pass %NULL.
  */
 void
 gtk_center_layout_set_start_widget (GtkCenterLayout *self,
@@ -636,7 +638,7 @@ gtk_center_layout_set_start_widget (GtkCenterLayout *self,
  *
  * Returns the start widget fo the layout.
  *
- * Returns: (transfer none): The current start widget of @self
+ * Returns: (nullable) (transfer none): The current start widget of @self
  */
 GtkWidget *
 gtk_center_layout_get_start_widget (GtkCenterLayout *self)
@@ -647,9 +649,11 @@ gtk_center_layout_get_start_widget (GtkCenterLayout *self)
 /**
  * gtk_center_layout_set_center_widget:
  * @self: a #GtkCenterLayout
- * @widget: the new center widget
+ * @widget (nullable): the new center widget
  *
- * Sets the new center widget of @self
+ * Sets the new center widget of @self.
+ *
+ * To remove the existing center widget, pass %NULL.
  */
 void
 gtk_center_layout_set_center_widget (GtkCenterLayout *self,
@@ -664,7 +668,7 @@ gtk_center_layout_set_center_widget (GtkCenterLayout *self,
  *
  * Returns the center widget of the layout.
  *
- * Returns: (transfer none): the current center widget of @self
+ * Returns: (nullable) (transfer none): the current center widget of @self
  */
 GtkWidget *
 gtk_center_layout_get_center_widget (GtkCenterLayout *self)
@@ -675,9 +679,11 @@ gtk_center_layout_get_center_widget (GtkCenterLayout *self)
 /**
  * gtk_center_layout_set_end_widget:
  * @self: a #GtkCenterLayout
- * @widget: (transfer none): the new end widget
+ * @widget: (nullable) (transfer none): the new end widget
  *
- * Sets the new end widget of @self
+ * Sets the new end widget of @self.
+ *
+ * To remove the existing center widget, pass %NULL.
  */
 void
 gtk_center_layout_set_end_widget (GtkCenterLayout *self,
@@ -692,7 +698,7 @@ gtk_center_layout_set_end_widget (GtkCenterLayout *self,
  *
  * Returns the end widget of the layout.
  *
- * Returns: (transfer none): the current end widget of @self
+ * Returns: (nullable) (transfer none): the current end widget of @self
  */
 GtkWidget *
 gtk_center_layout_get_end_widget (GtkCenterLayout *self)

gtk/gtkcolumnview.c

@@ -1661,7 +1661,7 @@ gtk_column_view_get_list_view (GtkColumnView *self)
  *   gtk_column_view_set_model (view, selection);
  * ]|
  *
- * Returns: (transfer none): the #GtkSorter of @self
+ * Returns: (nullable) (transfer none): the #GtkSorter of @self
  */
 GtkSorter *
 gtk_column_view_get_sorter (GtkColumnView *self)

gtk/gtkcolumnviewcolumn.c

@@ -742,6 +742,9 @@ gtk_column_view_column_remove_from_sorter (GtkColumnViewColumn *self)
  *
  * Associates a sorter with the column.
  *
+ * If @sorter is %NULL, the column will not let users change
+ * the sorting by clicking on its header.
+ *
  * This sorter can be made active by clicking on the column
  * header, or by calling gtk_column_view_sort_by_column().
  *
@@ -772,7 +775,7 @@ gtk_column_view_column_set_sorter (GtkColumnViewColumn *self,
  *
  * Returns the sorter that is associated with the column.
  *
- * Returns: (transfer none): the #GtkSorter of @self
+ * Returns: (nullable) (transfer none): the #GtkSorter of @self
  */
 GtkSorter *
 gtk_column_view_column_get_sorter (GtkColumnViewColumn *self)

gtk/gtkcombobox.c

@@ -2142,7 +2142,7 @@ out:
  *
  * Returns the #GtkTreeModel which is acting as data source for @combo_box.
  *
- * Returns: (transfer none): A #GtkTreeModel which was passed
+ * Returns: (nullable) (transfer none): A #GtkTreeModel which was passed
  *     during construction.
  */
 GtkTreeModel *
@@ -2541,7 +2541,7 @@ gtk_combo_box_get_popup_fixed_width (GtkComboBox *combo_box)
  *
  * Returns the current row separator function.
  *
- * Returns: the current row separator function.
+ * Returns: (nullable): the current row separator function.
  */
 GtkTreeViewRowSeparatorFunc
 gtk_combo_box_get_row_separator_func (GtkComboBox *combo_box)
@@ -2556,7 +2556,7 @@ gtk_combo_box_get_row_separator_func (GtkComboBox *combo_box)
 /**
  * gtk_combo_box_set_row_separator_func:
  * @combo_box: a #GtkComboBox
- * @func: a #GtkTreeViewRowSeparatorFunc
+ * @func: (nullable): a #GtkTreeViewRowSeparatorFunc
  * @data: (allow-none): user data to pass to @func, or %NULL
  * @destroy: (allow-none): destroy notifier for @data, or %NULL
  *

gtk/gtkdragsource.c

@@ -566,7 +566,7 @@ gtk_drag_source_new (void)
  *
  * Gets the current content provider of a #GtkDragSource.
  *
- * Returns: (transfer none): the #GdkContentProvider of @source
+ * Returns: (nullable) (transfer none): the #GdkContentProvider of @source
  */
 GdkContentProvider *
 gtk_drag_source_get_content (GtkDragSource *source)

gtk/gtkheaderbar.c

@@ -795,7 +795,7 @@ gtk_header_bar_set_decoration_layout (GtkHeaderBar *bar,
  * Gets the decoration layout set with
  * gtk_header_bar_set_decoration_layout().
  *
- * Returns: the decoration layout
+ * Returns: (nullable): the decoration layout
  */
 const char *
 gtk_header_bar_get_decoration_layout (GtkHeaderBar *bar)