From ded9903a835057e18e85a2853cd4697fe57dcdc3 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sat, 27 Feb 2021 10:55:35 -0500
Subject: [PATCH] root: Convert docs

---
 gtk/gtkroot.c | 42 ++++++++++++++++++++++++------------------
 1 file changed, 24 insertions(+), 18 deletions(-)

diff --git a/gtk/gtkroot.c b/gtk/gtkroot.c
index 16e1bef28c..b77d7d7a99 100644
--- a/gtk/gtkroot.c
+++ b/gtk/gtkroot.c
@@ -31,17 +31,21 @@
 #include "gtkshortcutmanager.h"
 
 /**
- * SECTION:gtkroot
- * @Title: GtkRoot
- * @Short_description: Interface for root widgets
- * @See_also: #GtkWindow
+ * GtkRoot:
  *
- * #GtkRoot is the interface implemented by all widgets that can act as a toplevel
- * widget to a hierarchy of widgets. The root widget takes care of providing the
- * connection to the windowing system and manages layout, drawing and event delivery
- * for its widget hierarchy.
+ * `GtkRoot` is the interface implemented by all widgets that can act as a toplevel
+ * widget.
  *
- * The obvious example of a #GtkRoot is #GtkWindow.
+ * The root widget takes care of providing the connection to the windowing system
+ * and manages layout, drawing and event delivery for its widget hierarchy.
+ *
+ * The obvious example of a `GtkRoot` is `GtkWindow`.
+ *
+ * To get the display to which a `GtkRoot` belongs, use
+ * [method@Gtk.Root.get_display].
+ *
+ * `GtkRoot` also maintains the location of keyboard focus inside its widget
+ * hierarchy, with [method@Gtk.Root.set_focus] and [method@Gtk.Root.get_focus].
  */
 
 G_DEFINE_INTERFACE_WITH_CODE (GtkRoot, gtk_root, GTK_TYPE_WIDGET,
@@ -83,9 +87,9 @@ gtk_root_default_init (GtkRootInterface *iface)
 
 /**
  * gtk_root_get_display:
- * @self: a #GtkRoot
+ * @self: a `GtkRoot`
  *
- * Returns the display that this GtkRoot is on.
+ * Returns the display that this `GtkRoot` is on.
  *
  * Returns: (transfer none): the display of @root
  */
@@ -113,16 +117,18 @@ gtk_root_get_constraint_solver (GtkRoot *self)
 
 /**
  * gtk_root_set_focus:
- * @self: a #GtkRoot
+ * @self: a `GtkRoot`
  * @focus: (allow-none): widget to be the new focus widget, or %NULL
  *    to unset the focus widget
  *
  * If @focus is not the current focus widget, and is focusable, sets
- * it as the focus widget for the root. If @focus is %NULL, unsets
- * the focus widget for the root.
+ * it as the focus widget for the root.
+ *
+ * If @focus is %NULL, unsets the focus widget for the root.
  *
  * To set the focus to a particular widget in the root, it is usually
- * more convenient to use gtk_widget_grab_focus() instead of this function.
+ * more convenient to use [method@Gtk.Widget.grab_focus] instead of
+ * this function.
  */
 void
 gtk_root_set_focus (GtkRoot   *self,
@@ -136,7 +142,7 @@ gtk_root_set_focus (GtkRoot   *self,
 
 /**
  * gtk_root_get_focus:
- * @self: a #GtkRoot
+ * @self: a `GtkRoot`
  *
  * Retrieves the current focused widget within the root.
  *
@@ -145,8 +151,8 @@ gtk_root_set_focus (GtkRoot   *self,
  * `gtk_widget_has_focus (widget)` will be %FALSE for the
  * widget.
  *
- * Returns: (nullable) (transfer none): the currently focused widget,
- *    or %NULL if there is none.
+ * Returns: (nullable) (transfer none): the currently focused
+ *   widget, or %NULL if there is none.
  */
 GtkWidget *
 gtk_root_get_focus (GtkRoot *self)