[gtk+/wip/baseline2] Document gtk_widget_get_valign_with_baseline

[Alexander Larsson <alexl src gnome org>]

commit 95d5f0c33b20bb544ab47659c0fdb5554a7bef85
Author: Alexander Larsson <alexl redhat com>
Date:   Tue Mar 26 15:43:30 2013 +0100

    Document gtk_widget_get_valign_with_baseline

 gtk/gtkwidget.c |   16 +++++++++++++++-
 gtk/gtkwidget.h |    1 +
 2 files changed, 16 insertions(+), 1 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index d12159b..d9bba88 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -13367,6 +13367,15 @@ gtk_widget_set_halign (GtkWidget *widget,
   g_object_notify (G_OBJECT (widget), "halign");
 }
 
+/**
+ * gtk_widget_get_valign_with_baseline:
+ * @widget: a #GtkWidget
+ *
+ * Gets the value of the #GtkWidget:valign property, including
+ * %GTK_ALIGN_BASELINE.
+ *
+ * Returns: the vertical alignment of @widget
+ */
 GtkAlign
 gtk_widget_get_valign_with_baseline (GtkWidget *widget)
 {
@@ -13380,7 +13389,12 @@ gtk_widget_get_valign_with_baseline (GtkWidget *widget)
  *
  * Gets the value of the #GtkWidget:valign property.
  *
- * Returns: the vertical alignment of @widget
+ * For backwards compatibility reasons this method will never return
+ * %GTK_ALIGN_BASELINE, but instead it will convert it to
+ * %GTK_ALIGN_FILL. If your widget want to support baseline aligned
+ * children it must use gtk_widget_get_valign_with_baseline().
+ *
+ * Returns: the vertical alignment of @widget, ignoring baseline alignment
  */
 GtkAlign
 gtk_widget_get_valign (GtkWidget *widget)
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 748946c..a81fbe6 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -781,6 +781,7 @@ GtkAlign gtk_widget_get_halign        (GtkWidget *widget);
 void     gtk_widget_set_halign        (GtkWidget *widget,
                                        GtkAlign   align);
 GtkAlign gtk_widget_get_valign        (GtkWidget *widget);
+GDK_AVAILABLE_IN_3_10
 GtkAlign gtk_widget_get_valign_with_baseline (GtkWidget *widget);
 void     gtk_widget_set_valign        (GtkWidget *widget,
                                        GtkAlign   align);