[gtk+/wip/baseline2] Add docs for gtk_widget_get_preferred_size_and_baseline

[Alexander Larsson <alexl src gnome org>]

commit 1c2393cc73c2d22096453f395f58671110deee37
Author: Alexander Larsson <alexl redhat com>
Date:   Tue Mar 26 15:49:43 2013 +0100

    Add docs for gtk_widget_get_preferred_size_and_baseline

 gtk/gtksizerequest.c |   25 +++++++++++++++++++++++++
 gtk/gtkwidget.h      |    1 +
 2 files changed, 26 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtksizerequest.c b/gtk/gtksizerequest.c
index ed03f3c..c9c0fce 100644
--- a/gtk/gtksizerequest.c
+++ b/gtk/gtksizerequest.c
@@ -597,6 +597,28 @@ gtk_widget_get_preferred_height_and_baseline_for_width (GtkWidget *widget,
                                            natural_baseline);
 }
 
+/**
+ * gtk_widget_get_preferred_size_and_baseline:
+ * @widget: a #GtkWidget instance
+ * @minimum_size: (out) (allow-none): location for storing the minimum size, or %NULL
+ * @natural_size: (out) (allow-none): location for storing the natural size, or %NULL
+ *
+ * Retrieves the minimum and natural size  and the corresponding baselines of a widget, taking
+ * into account the widget's preference for height-for-width management. The baselines may
+ * be -1 which means that no baseline is requested for this widget.
+ *
+ * This is used to retrieve a suitable size by container widgets which do
+ * not impose any restrictions on the child placement. It can be used
+ * to deduce toplevel window and menu sizes as well as child widgets in
+ * free-form containers such as GtkLayout.
+ *
+ * <note><para>Handle with care. Note that the natural height of a height-for-width
+ * widget will generally be a smaller size than the minimum height, since the required
+ * height for the natural width is generally smaller than the required height for
+ * the minimum width.</para></note>
+ *
+ * Since: 3.10
+ */
 void
 gtk_widget_get_preferred_size_and_baseline (GtkWidget      *widget,
                                            GtkRequisition *minimum_size,
@@ -666,6 +688,9 @@ gtk_widget_get_preferred_size_and_baseline (GtkWidget      *widget,
  * height for the natural width is generally smaller than the required height for
  * the minimum width.</para></note>
  *
+ * Use gtk_widget_get_preferred_size_and_baseline() if you want to support
+ * baseline alignment.
+ *
  * Since: 3.0
  */
 void
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index f143fce..ccab812 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -537,6 +537,7 @@ void   gtk_widget_get_preferred_height_and_baseline_for_width (GtkWidget     *wi
 void                gtk_widget_get_preferred_size             (GtkWidget      *widget,
                                                                GtkRequisition *minimum_size,
                                                                GtkRequisition *natural_size);
+GDK_AVAILABLE_IN_3_10
 void                gtk_widget_get_preferred_size_and_baseline (GtkWidget      *widget,
                                                                GtkRequisition *minimum_size,
                                                                GtkRequisition *natural_size,