[gtk/gtk-3-24: 1/2] docs: improve doc of gtk_style_context_get()

[Matthias Clasen <matthiasc src gnome org>]

commit fea466c13cd882053f563176e1386d2acc52c9a1
Author: Sébastien Wilmet <swilmet informatique-libre be>
Date:   Wed Jul 13 17:12:42 2022 +0200

    docs: improve doc of gtk_style_context_get()
    
    When using this function in GtkSourceView (for GTK 3), there was a
    mistake for retrieving a GdkRGBA value.
    
    So, better document the function to avoid further mistakes.

 gtk/gtkstylecontext.c | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)
---
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index a96395ca46..11625d16c0 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -896,13 +896,36 @@ gtk_style_context_get_valist (GtkStyleContext *context,
  * gtk_style_context_get:
  * @context: a #GtkStyleContext
  * @state: state to retrieve the property values for
- * @...: property name /return value pairs, followed by %NULL
+ * @...: property name / return value pairs, followed by %NULL
  *
  * Retrieves several style property values from @context for a
  * given state.
  *
  * See gtk_style_context_get_property() for details.
  *
+ * For the property name / return value pairs, it works similarly as
+ * g_object_get(). Example:
+ *
+ * |[<!-- language="C" -->
+ * GdkRGBA *background_color = NULL;
+ * PangoFontDescription *font_desc = NULL;
+ * gint border_radius = 0;
+ *
+ * gtk_style_context_get (style_context,
+ *                        gtk_style_context_get_state (style_context),
+ *                        GTK_STYLE_PROPERTY_BACKGROUND_COLOR, &background_color,
+ *                        GTK_STYLE_PROPERTY_FONT, &font_desc,
+ *                        GTK_STYLE_PROPERTY_BORDER_RADIUS, &border_radius,
+ *                        NULL);
+ *
+ * // Do something with the property values.
+ *
+ * if (background_color != NULL)
+ *   gdk_rgba_free (background_color);
+ * if (font_desc != NULL)
+ *   pango_font_description_free (font_desc);
+ * ]|
+ *
  * Since: 3.0
  */
 void