[gtk+/wip/baseline2] Document gtk_widget_size_allocate_with_baseline

[Alexander Larsson <alexl src gnome org>]

commit 9269fc82b16ff55b163a600ec7aaae3b94b15a87
Author: Alexander Larsson <alexl redhat com>
Date:   Tue Mar 26 15:43:04 2013 +0100

    Document gtk_widget_size_allocate_with_baseline

 gtk/gtkwidget.c |   25 +++++++++++++++++++++++++
 gtk/gtkwidget.h |    1 +
 2 files changed, 26 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index a018862..d12159b 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 4a1202c..748946c 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);