Review of attachment 300673 [details] [review]:

::: gtk/gtklabel.c
@@ +2718,3 @@
  * g_free (markup);
  * ]|
+ * Note that the markup is not applied to the text unless the @set-markup property

You should leave an empty line between the ]| and the next paragraph.

Also, that's not how property linking works.

To link to a GObject property, use the #TypeName:property-name syntax.

The text is also misleading: using gtk_label_set_markup() will set the GtkLabel:use-markup property as a side effect.

Created attachment 300675 [details] [review]
note about that gtk_set_markup turns set-markup to true

Interesting.

My background is that I used gtk_set_markup in a Javascript program, but in there, gtk_set_markup does not do anything unless you explicitly make sure 'set-markup' should be true.

I could mention that in gtklabel.c too, but I assume this gtk+ API documentation is C specific or?

I assume 'gtk_set_markup' is really 'gtk_label_set_markup'.

I just tested with GJS, and this:

```
  const Gtk = imports.gi.Gtk;

  Gtk.init(null);

  let w = new Gtk.Window();
  w.set_default_size(200, 200);
  w.connect('destroy', function() { Gtk.main_quit(); });

  let l = new Gtk.Label();
  l.set_markup('<b>Foo</b> and <i>bar</i>');
  w.add(l);

  w.show_all();

  Gtk.main();
```

generates the expected result: http://i.imgur.com/hgMH4cJ.png

If you're setting the label with markup with properties, you will need:

```
  let l = new Gtk.Label({ label: '<b>foo</b> and <i>bar</i>', use_markup: true });
```

Because GtkLabel does not have a property that sets both the label and the use-markup properties at the same time.

my case bug 745743 in which I had to explicitly do 'this._label.set_use_markup(true)' in order to get the markup visible.

https://bugzilla.gnome.org/show_bug.cgi?id=745743#c10

https://bugzilla.gnome.org/attachment.cgi?id=300671&action=diff

but I guess this was some special case or?

It's not a special case. Like I said above: GtkLabel does not have a property that sets both the label and the use-markup properties at the same time. If you use the 'label' property directly, you'll also need to set the 'use-markup' property.

If you want to document that, you'll need to change the documentation of the GtkLabel:label property, for instance to something like this:

```
The text of the label.

If the contents of the string use Pango markup, you will need to set the #GtkLabel:use-markup property to %TRUE in order for the label to use the markup attributes.
```

Created attachment 300715 [details] [review]
add a note explaining under what conditions, gtk_label_set_markup() automatically sets set-markup to true.

From a user-of-documentation point of view, I would likely not have looked for
documentation of the GtkLabel:label property to change markup though. I'm suggesting to add this to gtk_set_use_markup() because that is the first encounter of the word 'markup' on the page for GtkListBox (and the first one I personally stumbled upon which sounded like it would solve all my problems without further work).

Attached suggestion is a small note, added to gtk_label_set_markup() documentation. I hope I explained the behavior of gtk_label_set_markup() correctly.

You had me confused here. The boolean property you're looking for is called "use-markup", not "set-markup"

Created attachment 300733 [details] [review]
add a note explaining under what conditions, gtk_label_set_use_markup() automatically sets use-markup to true.

super sorry about that! use-markup property and gtk_label_set_use_markup(). yes.

Review of attachment 300733 [details] [review]:

::: gtk/gtklabel.c
@@ +2719,3 @@
  * ]|
+ *
+ * When called, gtk_set_use_markup() will set the #GtkLabel:use-markup property

Wrong function name: it's gtk_label_set_markup().

@@ +2720,3 @@
+ *
+ * When called, gtk_set_use_markup() will set the #GtkLabel:use-markup property
+ * to true for the GtkLabel it takes as input. However, if the #GtkLabel

"true" should be "%TRUE".

Also, the wording is a bit awkward. I'd say:

This function will set the #GtkLabel:use-markup property to %TRUE as a side effect.

@@ +2721,3 @@
+ * When called, gtk_set_use_markup() will set the #GtkLabel:use-markup property
+ * to true for the GtkLabel it takes as input. However, if the #GtkLabel
+ * is constructed with properties, #GtkLabel:use-markup should be set when

The wording "is constructed with properties" does not really apply: if you use properties you can do that after construction.

I would say:

If you use the #GtkLabel:label property to set the contents of the label, you should also ensure that you set the #GtkLabel:use-markup accordingly.

I would also change the description of the "label" property, since we're linking to it inside this function. Right not, the description is taken from the GParamSpec, so you'd have to add a gtk-doc stanza, like this:

/**
 * 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 setting both this property and #GtkLabel:use-markup
 * at the same time.
 */

This way we close the loop between properties and accessors.

Review of attachment 300733 [details] [review]:

Additionally, the commit message is a bit awkwardly worded:

Something better would be:

  docs: Note that gtk_label_set_markup() sets use-markup

  Add a note explaining the side effects of gtk_label_set_markup().

Created attachment 300942 [details] [review]
Note the side effects of GtkLabel text setters

This is a bit more comprehensive documentation patch that covers the side effects of set_markup() and set_text(), as well as the various properties.

Created attachment 300944 [details] [review]
Note the side effects of GtkLabel text setters / v2

The "label" property should also mention "use-mnemonics"