fontbutton: Convert docs

Change link syntax, add an example image, generally clean things up.

gtk/gtkfontbutton.c

@@ -48,13 +48,13 @@
 
 
 /**
- * SECTION:gtkfontbutton
+ * GtkFontButton:
- * @Short_description: A button to launch a font chooser dialog
+ *
- * @Title: GtkFontButton
+ * The `GtkFontButton` allows to open a font chooser dialog to change
- * @See_also: #GtkFontChooserDialog, #GtkColorButton.
+ * the font.
+ *
+ * ![An example GtkFontButton](font-button.png)
  *
- * The #GtkFontButton is a button which displays the currently selected
- * font an allows to open a font chooser dialog to change the font.
  * It is suitable widget for selecting a font in a preference dialog.
  *
  * # CSS nodes
@@ -65,7 +65,7 @@
  *     ╰── [content]
  *]|
  *
- * GtkFontButton has a single CSS node with name fontbutton which
+ * `GtkFontButton` has a single CSS node with name fontbutton which
  * contains a button node with the .font style class.
  */
 
@@ -489,8 +489,7 @@ gtk_font_button_class_init (GtkFontButtonClass *klass)
   /**
    * GtkFontButton:use-font:
    *
-   * If this property is set to %TRUE, the label will be drawn 
+   * Whether the buttons label will be drawn in the selected font.
-   * in the selected font.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_USE_FONT,
@@ -503,8 +502,7 @@ gtk_font_button_class_init (GtkFontButtonClass *klass)
   /**
    * GtkFontButton:use-size:
    *
-   * If this property is set to %TRUE, the label will be drawn 
+   * Whether the buttons label will use the selected font size.
-   * with the selected font size.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_USE_SIZE,
@@ -514,6 +512,11 @@ gtk_font_button_class_init (GtkFontButtonClass *klass)
                                                          FALSE,
                                                          GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
 
+  /**
+   * GtkFontButton:modal:
+   *
+   * Whether the font chooser dialog should be modal.
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_MODAL,
                                    g_param_spec_boolean ("modal",
@@ -524,15 +527,16 @@ gtk_font_button_class_init (GtkFontButtonClass *klass)
 
   /**
    * GtkFontButton::font-set:
-   * @widget: the object which received the signal.
+   * @widget: the object which received the signal
    *
-   * The ::font-set signal is emitted when the user selects a font. 
+   * Emitted when the user selects a font.
-   * When handling this signal, use gtk_font_chooser_get_font()
+   *
+   * When handling this signal, use [method@Gtk.FontChooser.get_font]
    * to find out which font was just selected.
    *
-   * Note that this signal is only emitted when the user
+   * Note that this signal is only emitted when the user changes the font.
-   * changes the font. If you need to react to programmatic font changes
+   * If you need to react to programmatic font changes as well, use
-   * as well, use the notify::font signal.
+   * the notify::font signal.
    */
   font_button_signals[FONT_SET] = g_signal_new (I_("font-set"),
                                                 G_TYPE_FROM_CLASS (gobject_class),
@@ -723,7 +727,7 @@ gtk_font_button_new (void)
  * gtk_font_button_new_with_font:
  * @fontname: Name of font to display in font chooser dialog
  *
- * Creates a new font picker widget.
+ * Creates a new font picker widget showing the given font.
  *
  * Returns: a new font picker widget.
  */
@@ -735,7 +739,7 @@ gtk_font_button_new_with_font (const char *fontname)
 
 /**
  * gtk_font_button_set_title:
- * @font_button: a #GtkFontButton
+ * @font_button: a `GtkFontButton`
  * @title: a string containing the font chooser dialog title
  *
  * Sets the title for the font chooser dialog.
@@ -759,11 +763,12 @@ gtk_font_button_set_title (GtkFontButton *font_button,
 
 /**
  * gtk_font_button_get_title:
- * @font_button: a #GtkFontButton
+ * @font_button: a `GtkFontButton`
  *
  * Retrieves the title of the font chooser dialog.
  *
- * Returns: an internal copy of the title string which must not be freed.
+ * Returns: an internal copy of the title string
+ *   which must not be freed.
  */
 const char *
 gtk_font_button_get_title (GtkFontButton *font_button)
@@ -775,7 +780,7 @@ gtk_font_button_get_title (GtkFontButton *font_button)
 
 /**
  * gtk_font_button_set_modal:
- * @font_button: a #GtkFontButton
+ * @font_button: a `GtkFontButton`
  * @modal: %TRUE to make the dialog modal
  *
  * Sets whether the dialog should be modal.
@@ -799,7 +804,7 @@ gtk_font_button_set_modal (GtkFontButton *font_button,
 
 /**
  * gtk_font_button_get_modal:
- * @font_button: a #GtkFontButton
+ * @font_button: a `GtkFontButton`
  *
  * Gets whether the dialog is modal.
  *
@@ -815,7 +820,7 @@ gtk_font_button_get_modal (GtkFontButton *font_button)
 
 /**
  * gtk_font_button_get_use_font:
- * @font_button: a #GtkFontButton
+ * @font_button: a `GtkFontButton`
  *
  * Returns whether the selected font is used in the label.
  *
@@ -831,10 +836,11 @@ gtk_font_button_get_use_font (GtkFontButton *font_button)
 
 /**
  * gtk_font_button_set_use_font:
- * @font_button: a #GtkFontButton
+ * @font_button: a `GtkFontButton`
  * @use_font: If %TRUE, font name will be written using font chosen.
  *
- * If @use_font is %TRUE, the font name will be written using the selected font.  
+ * If @use_font is %TRUE, the font name will be written
+ * using the selected font.
  */
 void
 gtk_font_button_set_use_font (GtkFontButton *font_button,
@@ -857,7 +863,7 @@ gtk_font_button_set_use_font (GtkFontButton *font_button,
 
 /**
  * gtk_font_button_get_use_size:
- * @font_button: a #GtkFontButton
+ * @font_button: a `GtkFontButton`
  *
  * Returns whether the selected size is used in the label.
  *
@@ -873,10 +879,12 @@ gtk_font_button_get_use_size (GtkFontButton *font_button)
 
 /**
  * gtk_font_button_set_use_size:
- * @font_button: a #GtkFontButton
+ * @font_button: a `GtkFontButton`
- * @use_size: If %TRUE, font name will be written using the selected size.
+ * @use_size: If %TRUE, font name will be written using the
+ *   selected size.
  *
- * If @use_size is %TRUE, the font name will be written using the selected size.
+ * If @use_size is %TRUE, the font name will be written using
+ * the selected size.
  */
 void
 gtk_font_button_set_use_size (GtkFontButton *font_button,