docs: Note the side effects of GtkLabel setters

The gtk_label_set_text() and gtk_label_set_markup() functions have
various side effects that ought to be documented, especially for
non-C developers using properties directly.

https://bugzilla.gnome.org/show_bug.cgi?id=747121

diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 396ae9755fe8890c71c93db9c4a065edb878b163..4b980b25d17dd0a6cb8c2fdc2b203d6fce89f003 100644 (file)
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -725,6 +725,21 @@ gtk_label_class_init (GtkLabelClass *class)
                     _gtk_marshal_BOOLEAN__STRING,
                     G_TYPE_BOOLEAN, 1, G_TYPE_STRING);
 
+  /**
+   * GtkLabel:label:
+   *
+   * The contents of the label.
+   *
+   * If the string contains [Pango XML markup][PangoMarkupFormat], you will
+   * have to set the #GtkLabel:use-markup property to %TRUE in order for the
+   * label to display the markup attributes. See also gtk_label_set_markup()
+   * for a convenience function that sets both this property and the
+   * #GtkLabel:use-markup property at the same time.
+   *
+   * If the string contains underlines acting as mnemonics, you will have to
+   * set the #GtkLabel:use-underline property to %TRUE in order for the label
+   * to display them.
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_LABEL,
                                    g_param_spec_string ("label",
@@ -2210,7 +2225,13 @@ gtk_label_recalculate (GtkLabel *label)
  * Sets the text within the #GtkLabel widget. It overwrites any text that
  * was there before.  
  *
- * This will also clear any previously set mnemonic accelerators.
+ * This function will clear any previously set mnemonic accelerators, and
+ * set the #GtkLabel:use-underline property to %FALSE as a side effect.
+ *
+ * This function will set the #GtkLabel:use-markup property to %FALSE
+ * as a side effect.
+ *
+ * See also: gtk_label_set_markup()
  **/
 void
 gtk_label_set_text (GtkLabel    *label,
@@ -2294,7 +2315,7 @@ gtk_label_get_attributes (GtkLabel *label)
  *
  * Sets the text of the label. The label is interpreted as
  * including embedded underlines and/or Pango markup depending
- * on the values of the #GtkLabel:use-underline" and
+ * on the values of the #GtkLabel:use-underline and
  * #GtkLabel:use-markup properties.
  **/
 void
@@ -2706,9 +2727,11 @@ gtk_label_set_markup_internal (GtkLabel    *label,
  *
  * Parses @str which is marked up with the
  * [Pango text markup language][PangoMarkupFormat], setting the
- * label’s text and attribute list based on the parse results. If the @str is
- * external data, you may need to escape it with g_markup_escape_text() or
- * g_markup_printf_escaped():
+ * label’s text and attribute list based on the parse results.
+ *
+ * If the @str is external data, you may need to escape it with
+ * g_markup_escape_text() or g_markup_printf_escaped():
+ *
  * |[<!-- language="C" -->
  * const char *format = "<span style=\"italic\">\%s</span>";
  * char *markup;
@@ -2717,6 +2740,15 @@ gtk_label_set_markup_internal (GtkLabel    *label,
  * gtk_label_set_markup (GTK_LABEL (label), markup);
  * g_free (markup);
  * ]|
+ *
+ * This function will set the #GtkLabel:use-markup property to %TRUE as
+ * a side effect.
+ *
+ * If you set the label contents using the #GtkLabel:label property you
+ * should also ensure that you set the #GtkLabel:use-markup property
+ * accordingly.
+ *
+ * See also: gtk_label_set_text()
  **/
 void
 gtk_label_set_markup (GtkLabel    *label,