From 9269fc82b16ff55b163a600ec7aaae3b94b15a87 Mon Sep 17 00:00:00 2001
From: Alexander Larsson <alexl@redhat.com>
Date: Tue, 26 Mar 2013 15:43:04 +0100
Subject: [PATCH] Document gtk_widget_size_allocate_with_baseline

---
 gtk/gtkwidget.c | 25 +++++++++++++++++++++++++
 gtk/gtkwidget.h |  1 +
 2 files changed, 26 insertions(+)

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index a018862d01..d12159b552 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -5224,6 +5224,28 @@ gtk_widget_invalidate_widget_windows (GtkWidget *widget,
 				       invalidate_predicate, widget);
 }
 
+/**
+ * gtk_widget_size_allocate_with_baseline:
+ * @widget: a #GtkWidget
+ * @allocation: position and size to be allocated to @widget
+ * @baseline: The baseline of the child, or -1
+ *
+ * This function is only used by #GtkContainer subclasses, to assign a size,
+ * position and (optionally) baseline to their child widgets.
+ *
+ * In this function, the allocation and baseline may be adjusted. It
+ * will be forced to a 1x1 minimum size, and the
+ * adjust_size_allocation virtual and adjust_baseline_allocation
+ * methods on the child will be used to adjust the allocation and
+ * baseline. Standard adjustments include removing the widget's
+ * margins, and applying the widget's #GtkWidget:halign and
+ * #GtkWidget:valign properties.
+ *
+ * If the child widget does not have a valign of %GTK_ALIGN_BASELINE the
+ * baseline argument is ignored and -1 is used instead.
+ *
+ * Since: 3.10
+ **/
 void
 gtk_widget_size_allocate_with_baseline (GtkWidget     *widget,
 					GtkAllocation *allocation,
@@ -5437,6 +5459,9 @@ out:
  * method on the child will be used to adjust the allocation. Standard
  * adjustments include removing the widget's margins, and applying the
  * widget's #GtkWidget:halign and #GtkWidget:valign properties.
+ *
+ * For baseline support in containers you need to use gtk_widget_size_allocate_with_baseline()
+ * instead.
  **/
 void
 gtk_widget_size_allocate (GtkWidget	*widget,
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 4a1202cc91..748946c46b 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -507,6 +507,7 @@ void       gtk_widget_size_request        (GtkWidget           *widget,
                                            GtkRequisition      *requisition);
 void	   gtk_widget_size_allocate	  (GtkWidget	       *widget,
 					   GtkAllocation       *allocation);
+GDK_AVAILABLE_IN_3_10
 void	   gtk_widget_size_allocate_with_baseline	  (GtkWidget	       *widget,
 							   GtkAllocation       *allocation,
 							   gint                 baseline);