[gtk+] docs: try to clarify widget_get_state_flags vs context_get_state

[Paolo Borelli <pborelli src gnome org>]

commit c4996873dc2814ca53767dbaa1ffe08b3f6063d1
Author: Paolo Borelli <pborelli gnome org>
Date:   Tue Jan 5 18:40:25 2016 +0100

    docs: try to clarify widget_get_state_flags vs context_get_state

 gtk/gtkstylecontext.c |    7 ++++++-
 gtk/gtkwidget.c       |    4 ++++
 2 files changed, 10 insertions(+), 1 deletions(-)
---
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 26b578f..dd242f1 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -959,7 +959,12 @@ gtk_style_context_set_state (GtkStyleContext *context,
  * gtk_style_context_get_state:
  * @context: a #GtkStyleContext
  *
- * Returns the state used when rendering.
+ * Returns the state used when rendering. This method should
+ * only be used to retrieve the #GtkStateFlags to pass to
+ * #GtkStyleContext methods, like gtk_style_context_get_padding().
+ *
+ * If you need to retrieve the current state of a #GtkWidget you
+ * should look at gtk_widget_get_state_flags().
  *
  * Returns: the state flags
  *
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 564f795..24a7249 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -8968,6 +8968,10 @@ gtk_widget_unset_state_flags (GtkWidget     *widget,
  * returned, that is, also based on parent insensitivity, even if
  * @widget itself is sensitive.
  *
+ * Also note that if you are looking for a way to obtain the
+ * #GtkStateFlags to pass to a #GtkStyleContext method, you
+ * should look at gtk_style_context_get_state().
+ *
  * Returns: The state flags for widget
  *
  * Since: 3.0