diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index c296f06c11..0427fa81d7 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -73,36 +73,37 @@
 #include <string.h>
 
 /**
- * SECTION:gtkentry
- * @Short_description: A single line text entry field
- * @Title: GtkEntry
- * @See_also: #GtkTextView, #GtkEntryCompletion
+ * GtkEntry:
  *
- * The #GtkEntry widget is a single line text entry
- * widget. A fairly large set of key bindings are supported
- * by default. If the entered text is longer than the allocation
- * of the widget, the widget will scroll so that the cursor
- * position is visible.
+ * `GtkEntry` is a single line text entry widget.
  *
- * When using an entry for passwords and other sensitive information,
- * it can be put into “password mode” using gtk_entry_set_visibility().
+ * ![An example GtkEntry](entry.png)
+ *
+ * A fairly large set of key bindings are supported by default. If the
+ * entered text is longer than the allocation of the widget, the widget
+ * will scroll so that the cursor position is visible.
+ *
+ * When using an entry for passwords and other sensitive information, it
+ * can be put into “password mode” using [method@Gtk.Entry.set_visibility].
  * In this mode, entered text is displayed using a “invisible” character.
  * By default, GTK picks the best invisible character that is available
  * in the current font, but it can be changed with
- * gtk_entry_set_invisible_char().
+ * [method@Gtk.Entry.set_invisible_char].
  *
- * GtkEntry has the ability to display progress or activity
+ * `GtkEntry` has the ability to display progress or activity
  * information behind the text. To make an entry display such information,
- * use gtk_entry_set_progress_fraction() or gtk_entry_set_progress_pulse_step().
+ * use [method@Gtk.Entry.set_progress_fraction] or
+ * [method@Gtk.Entry.set_progress_pulse_step].
  *
- * Additionally, GtkEntry can show icons at either side of the entry. These
- * icons can be activatable by clicking, can be set up as drag source and
- * can have tooltips. To add an icon, use gtk_entry_set_icon_from_gicon() or
- * one of the various other functions that set an icon from an icon name or a
- * paintable. To trigger an action when the user clicks an icon,
- * connect to the #GtkEntry::icon-press signal. To allow DND operations
- * from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on
- * an icon, use gtk_entry_set_icon_tooltip_text() or the corresponding function
+ * Additionally, `GtkEntry` can show icons at either side of the entry.
+ * These icons can be activatable by clicking, can be set up as drag source
+ * and can have tooltips. To add an icon, use
+ * [method@Gtk.Entry.set_icon_from_gicon] or one of the various other functions
+ * that set an icon from an icon name or a paintable. To trigger an action when
+ * the user clicks an icon, connect to the [signal@Gtk.Entry::icon-press] signal.
+ * To allow DND operations from an icon, use
+ * [method@Gtk.Entry.set_icon_drag_source]. To set a tooltip on an icon, use
+ * [method@Gtk.Entry.set_icon_tooltip_text] or the corresponding function
  * for markup.
  *
  * Note that functionality or information that is only available by clicking
@@ -121,7 +122,7 @@
  * ╰── [progress[.pulse]]
  * ]|
  *
- * GtkEntry has a main node with the name entry. Depending on the properties
+ * `GtkEntry` has a main node with the name entry. Depending on the properties
  * of the entry, the style classes .read-only and .flat may appear. The style
  * classes .warning and .error may also be used with entries.
  *
@@ -132,11 +133,11 @@
  * The node has the style class .pulse when the shown progress is pulsing.
  *
  * For all the subnodes added to the text node in various situations,
- * see #GtkText.
+ * see [class@Gtk.Text].
  *
  * # GtkEntry as GtkBuildable
  *
- * The GtkEntry implementation of the GtkBuildable interface supports a
+ * The `GtkEntry` implementation of the `GtkBuildable` interface supports a
  * custom <attributes> element, which supports any number of <attribute>
  * elements. The <attribute> element has attributes named “name“, “value“,
  * “start“ and “end“ and allows you to specify #PangoAttribute values for
@@ -153,14 +154,14 @@
  * ]|
  *
  * The start and end attributes specify the range of characters to which the
- * Pango attribute applies. If start and end are not specified, the attribute is
- * applied to the whole text. Note that specifying ranges does not make much
+ * Pango attribute applies. If start and end are not specified, the attribute
+ * is applied to the whole text. Note that specifying ranges does not make much
  * sense with translatable attributes. Use markup embedded in the translatable
  * content instead.
  *
  * # Accessibility
  *
- * GtkEntry uses the #GTK_ACCESSIBLE_ROLE_TEXT_BOX role.
+ * `GtkEntry` uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role.
  */
 
 #define MAX_ICONS 2
@@ -474,6 +475,11 @@ gtk_entry_class_init (GtkEntryClass *class)
 
   quark_entry_completion = g_quark_from_static_string ("gtk-entry-completion-key");
 
+  /**
+   * GtkEntry:buffer
+   *
+   * The buffer object which actually stores the text.
+   */
   entry_props[PROP_BUFFER] =
       g_param_spec_object ("buffer",
                            P_("Text Buffer"),
@@ -481,6 +487,11 @@ gtk_entry_class_init (GtkEntryClass *class)
                            GTK_TYPE_ENTRY_BUFFER,
                            GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkEntry:max-length:
+   *
+   * Maximum number of characters for this entry.
+   */
   entry_props[PROP_MAX_LENGTH] =
       g_param_spec_int ("max-length",
                         P_("Maximum length"),
@@ -489,6 +500,12 @@ gtk_entry_class_init (GtkEntryClass *class)
                         0,
                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkEntry:visibility:
+   *
+   * Whether the entry should show the “invisible char” instead of the
+   * actual text (“password mode”).
+   */
   entry_props[PROP_VISIBILITY] =
       g_param_spec_boolean ("visibility",
                             P_("Visibility"),
@@ -496,6 +513,11 @@ gtk_entry_class_init (GtkEntryClass *class)
                             TRUE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkEntry:has-frame:
+   *
+   * Whehter the entry should draw a frame.
+   */
   entry_props[PROP_HAS_FRAME] =
       g_param_spec_boolean ("has-frame",
                             P_("Has Frame"),
@@ -503,6 +525,11 @@ gtk_entry_class_init (GtkEntryClass *class)
                             TRUE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkEntry:invisible=char:
+   *
+   * The character to use when masking entry contents (“password mode”).
+   */
   entry_props[PROP_INVISIBLE_CHAR] =
       g_param_spec_unichar ("invisible-char",
                             P_("Invisible character"),
@@ -510,6 +537,11 @@ gtk_entry_class_init (GtkEntryClass *class)
                             '*',
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkEntry:activates-default:
+   *
+   * Whether to activate the default widget when Enter is pressed.
+   */
   entry_props[PROP_ACTIVATES_DEFAULT] =
       g_param_spec_boolean ("activates-default",
                             P_("Activates default"),
@@ -517,6 +549,11 @@ gtk_entry_class_init (GtkEntryClass *class)
                             FALSE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkEntry:scroll-offset:
+   *
+   * Number of pixels of the entry scrolled off the screen to the left.
+   */
   entry_props[PROP_SCROLL_OFFSET] =
       g_param_spec_int ("scroll-offset",
                         P_("Scroll offset"),
@@ -540,7 +577,7 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:overwrite-mode:
    *
-   * If text is overwritten when typing in the #GtkEntry.
+   * If text is overwritten when typing in the `GtkEntry`.
    */
   entry_props[PROP_OVERWRITE_MODE] =
       g_param_spec_boolean ("overwrite-mode",
@@ -552,7 +589,7 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:text-length:
    *
-   * The length of the text in the #GtkEntry.
+   * The length of the text in the `GtkEntry`.
    */
   entry_props[PROP_TEXT_LENGTH] =
       g_param_spec_uint ("text-length",
@@ -565,7 +602,7 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:invisible-char-set:
    *
-   * Whether the invisible char has been set for the #GtkEntry.
+   * Whether the invisible char has been set for the `GtkEntry`.
    */
   entry_props[PROP_INVISIBLE_CHAR_SET] =
       g_param_spec_boolean ("invisible-char-set",
@@ -591,7 +628,9 @@ gtk_entry_class_init (GtkEntryClass *class)
    * GtkEntry:progress-pulse-step:
    *
    * The fraction of total entry width to move the progress
-   * bouncing block for each call to gtk_entry_progress_pulse().
+   * bouncing block for each pulse.
+   *
+   * See [method@Gtk.Entry.progress_pulse].
    */
   entry_props[PROP_PROGRESS_PULSE_STEP] =
       g_param_spec_double ("progress-pulse-step",
@@ -604,7 +643,7 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
   * GtkEntry:placeholder-text:
   *
-  * The text that will be displayed in the #GtkEntry when it is empty
+  * The text that will be displayed in the `GtkEntry` when it is empty
   * and unfocused.
   */
   entry_props[PROP_PLACEHOLDER_TEXT] =
@@ -617,7 +656,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    /**
    * GtkEntry:primary-icon-paintable:
    *
-   * A #GdkPaintable to use as the primary icon for the entry.
+   * A `GdkPaintable` to use as the primary icon for the entry.
    */
   entry_props[PROP_PAINTABLE_PRIMARY] =
       g_param_spec_object ("primary-icon-paintable",
@@ -629,7 +668,7 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:secondary-icon-paintable:
    *
-   * A #GdkPaintable to use as the secondary icon for the entry.
+   * A `GdkPaintable` to use as the secondary icon for the entry.
    */
   entry_props[PROP_PAINTABLE_SECONDARY] =
       g_param_spec_object ("secondary-icon-paintable",
@@ -665,7 +704,7 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:primary-icon-gicon:
    *
-   * The #GIcon to use for the primary icon for the entry.
+   * The `GIcon` to use for the primary icon for the entry.
    */
   entry_props[PROP_GICON_PRIMARY] =
       g_param_spec_object ("primary-icon-gicon",
@@ -677,7 +716,7 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:secondary-icon-gicon:
    *
-   * The #GIcon to use for the secondary icon for the entry.
+   * The `GIcon` to use for the secondary icon for the entry.
    */
   entry_props[PROP_GICON_SECONDARY] =
       g_param_spec_object ("secondary-icon-gicon",
@@ -717,8 +756,9 @@ gtk_entry_class_init (GtkEntryClass *class)
    *
    * Whether the primary icon is activatable.
    *
-   * GTK emits the #GtkEntry::icon-press and #GtkEntry::icon-release
-   * signals only on sensitive, activatable icons.
+   * GTK emits the [signal@Gtk.Entry::icon-press] and
+   * [signal@Gtk.Entry::icon-release] signals only on sensitive,
+   * activatable icons.
    *
    * Sensitive, but non-activatable icons can be used for purely
    * informational purposes.
@@ -735,8 +775,9 @@ gtk_entry_class_init (GtkEntryClass *class)
    *
    * Whether the secondary icon is activatable.
    *
-   * GTK emits the #GtkEntry::icon-press and #GtkEntry::icon-release
-   * signals only on sensitive, activatable icons.
+   * GTK emits the [signal@Gtk.Entry::icon-press] and
+   * [signal@Gtk.Entry::icon-release] signals only on sensitive,
+   * activatable icons.
    *
    * Sensitive, but non-activatable icons can be used for purely
    * informational purposes.
@@ -754,8 +795,8 @@ gtk_entry_class_init (GtkEntryClass *class)
    * Whether the primary icon is sensitive.
    *
    * An insensitive icon appears grayed out. GTK does not emit the
-   * #GtkEntry::icon-press and #GtkEntry::icon-release signals and
-   * does not allow DND from insensitive icons.
+   * [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release]
+   * signals and does not allow DND from insensitive icons.
    *
    * An icon should be set insensitive if the action that would trigger
    * when clicked is currently not available.
@@ -773,8 +814,8 @@ gtk_entry_class_init (GtkEntryClass *class)
    * Whether the secondary icon is sensitive.
    *
    * An insensitive icon appears grayed out. GTK does not emit the
-   * #GtkEntry::icon-press and #GtkEntry::icon-release signals and
-   * does not allow DND from insensitive icons.
+   * [signal@Gtk.Entry::icon-press[ and [signal@Gtk.Entry::icon-release]
+   * signals and does not allow DND from insensitive icons.
    *
    * An icon should be set insensitive if the action that would trigger
    * when clicked is currently not available.
@@ -791,7 +832,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    *
    * The contents of the tooltip on the primary icon.
    *
-   * Also see gtk_entry_set_icon_tooltip_text().
+   * Also see [method@Gtk.Entry.set_icon_tooltip_text].
    */
   entry_props[PROP_TOOLTIP_TEXT_PRIMARY] =
       g_param_spec_string ("primary-icon-tooltip-text",
@@ -805,7 +846,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    *
    * The contents of the tooltip on the secondary icon.
    *
-   * Also see gtk_entry_set_icon_tooltip_text().
+   * Also see [method@Gtk.Entry.set_icon_tooltip_text].
    */
   entry_props[PROP_TOOLTIP_TEXT_SECONDARY] =
       g_param_spec_string ("secondary-icon-tooltip-text",
@@ -817,10 +858,9 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:primary-icon-tooltip-markup:
    *
-   * The contents of the tooltip on the primary icon, which is marked up
-   * with the [Pango text markup language][PangoMarkupFormat].
+   * The contents of the tooltip on the primary icon, with markup.
    *
-   * Also see gtk_entry_set_icon_tooltip_markup().
+   * Also see [method@Gtk.Entry.set_icon_tooltip_markup].
    */
   entry_props[PROP_TOOLTIP_MARKUP_PRIMARY] =
       g_param_spec_string ("primary-icon-tooltip-markup",
@@ -832,10 +872,9 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:secondary-icon-tooltip-markup:
    *
-   * The contents of the tooltip on the secondary icon, which is marked up
-   * with the [Pango text markup language][PangoMarkupFormat].
+   * The contents of the tooltip on the secondary icon, with markup.
    *
-   * Also see gtk_entry_set_icon_tooltip_markup().
+   * Also see [method@Gtk.Entry.set_icon_tooltip_markup].
    */
   entry_props[PROP_TOOLTIP_MARKUP_SECONDARY] =
       g_param_spec_string ("secondary-icon-tooltip-markup",
@@ -848,11 +887,12 @@ gtk_entry_class_init (GtkEntryClass *class)
    * GtkEntry:im-module:
    *
    * Which IM (input method) module should be used for this entry.
-   * See #GtkIMContext.
    *
-   * Setting this to a non-%NULL value overrides the
-   * system-wide IM module setting. See the GtkSettings
-   * #GtkSettings:gtk-im-module property.
+   * See [class@Gtk.IMContext].
+   *
+   * Setting this to a non-%NULL value overrides the system-wide IM
+   * module setting. See the GtkSettings [property@Gtk.Settings:gtk-im-module]
+   * property.
    */
   entry_props[PROP_IM_MODULE] =
       g_param_spec_string ("im-module",
@@ -883,7 +923,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    *
    * Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or
    * %GTK_INPUT_PURPOSE_PIN is independent from setting
-   * #GtkEntry:visibility.
+   * [property@Gtk.Entry:visibility].
    */
   entry_props[PROP_INPUT_PURPOSE] =
       g_param_spec_enum ("input-purpose",
@@ -896,8 +936,9 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:input-hints:
    *
-   * Additional hints (beyond #GtkEntry:input-purpose) that
-   * allow input methods to fine-tune their behaviour.
+   * Additional hints that allow input methods to fine-tune their behavior.
+   *
+   * Also see [property@Gtk.Entry:input-purpose]
    */
   entry_props[PROP_INPUT_HINTS] =
       g_param_spec_flags ("input-hints",
@@ -915,7 +956,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * This is mainly useful to change the size or weight of the text.
    *
    * The #PangoAttribute's @start_index and @end_index must refer to the
-   * #GtkEntryBuffer text, i.e. without the preedit string.
+   * [class@Gtk.EntryBuffer] text, i.e. without the preedit string.
    */
   entry_props[PROP_ATTRIBUTES] =
       g_param_spec_boxed ("attributes",
@@ -939,8 +980,8 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry::show-emoji-icon:
    *
-   * When this is %TRUE, the entry will show an emoji icon in the secondary
-   * icon position that brings up the Emoji chooser when clicked.
+   * Whether the entry will sohw an Emoji icon in the secondary icon position
+   * to open the Emoji chooser.
    */
   entry_props[PROP_SHOW_EMOJI_ICON] =
       g_param_spec_boolean ("show-emoji-icon",
@@ -952,8 +993,7 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:extra-menu:
    *
-   * A menu model whose contents will be appended to
-   * the context menu.
+   * A menu model whose contents will be appended to the context menu.
    */
   entry_props[PROP_EXTRA_MENU] =
       g_param_spec_object ("extra-menu",
@@ -977,9 +1017,9 @@ gtk_entry_class_init (GtkEntryClass *class)
    * GtkEntry::activate:
    * @self: The widget on which the signal is emitted
    *
-   * The ::activate signal is forwarded from the
-   * #GtkText::activated signal, which is a keybinding
-   * signal for all forms of the Enter key.
+   * Emitted when the entry is activated.
+   *
+   * The keybindings for this signal are all forms of the Enter key.
    */
   signals[ACTIVATE] =
     g_signal_new (I_("activate"),
@@ -995,8 +1035,7 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @entry: The entry on which the signal is emitted
    * @icon_pos: The position of the clicked icon
    *
-   * The ::icon-press signal is emitted when an activatable icon
-   * is clicked.
+   * Emitted when an activatable icon is clicked.
    */
   signals[ICON_PRESS] =
     g_signal_new (I_("icon-press"),
@@ -1013,8 +1052,8 @@ gtk_entry_class_init (GtkEntryClass *class)
    * @entry: The entry on which the signal is emitted
    * @icon_pos: The position of the clicked icon
    *
-   * The ::icon-release signal is emitted on the button release from a
-   * mouse click over an activatable icon.
+   * Emitted on the button release from a mouse click
+   * over an activatable icon.
    */
   signals[ICON_RELEASE] =
     g_signal_new (I_("icon-release"),
@@ -1828,15 +1867,14 @@ gtk_entry_snapshot (GtkWidget   *widget,
 
 /**
  * gtk_entry_grab_focus_without_selecting:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
  * Causes @entry to have keyboard focus.
  *
- * It behaves like gtk_widget_grab_focus(),
- * except that it doesn't select the contents of the entry.
- * You only want to call this on some special entries
- * which the user usually doesn't want to replace all text in,
- * such as search-as-you-type entries.
+ * It behaves like [method@Gtk.Widget.grab_focus], except that it doesn't
+ * select the contents of the entry. You only want to call this on some
+ * special entries which the user usually doesn't want to replace all text
+ * in, such as search-as-you-type entries.
  *
  * Returns: %TRUE if focus is now inside @self
  */
@@ -1920,7 +1958,7 @@ gtk_entry_start_editing (GtkCellEditable *cell_editable,
 
 /**
  * gtk_entry_reset_im_context:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
  * Reset the input method context of the entry if needed.
  *
@@ -2002,7 +2040,7 @@ gtk_entry_clear_icon (GtkEntry             *entry,
  *
  * Creates a new entry.
  *
- * Returns: a new #GtkEntry.
+ * Returns: a new `GtkEntry`.
  */
 GtkWidget*
 gtk_entry_new (void)
@@ -2012,11 +2050,11 @@ gtk_entry_new (void)
 
 /**
  * gtk_entry_new_with_buffer:
- * @buffer: The buffer to use for the new #GtkEntry.
+ * @buffer: The buffer to use for the new `GtkEntry`.
  *
  * Creates a new entry with the specified text buffer.
  *
- * Returns: a new #GtkEntry
+ * Returns: a new `GtkEntry`
  */
 GtkWidget*
 gtk_entry_new_with_buffer (GtkEntryBuffer *buffer)
@@ -2036,12 +2074,12 @@ get_buffer (GtkEntry *entry)
 
 /**
  * gtk_entry_get_buffer:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Get the #GtkEntryBuffer object which holds the text for
+ * Get the `GtkEntryBuffer` object which holds the text for
  * this widget.
  *
- * Returns: (transfer none): A #GtkEntryBuffer object.
+ * Returns: (transfer none): A `GtkEntryBuffer` object.
  */
 GtkEntryBuffer*
 gtk_entry_get_buffer (GtkEntry *entry)
@@ -2053,10 +2091,10 @@ gtk_entry_get_buffer (GtkEntry *entry)
 
 /**
  * gtk_entry_set_buffer:
- * @entry: a #GtkEntry
- * @buffer: a #GtkEntryBuffer
+ * @entry: a `GtkEntry`
+ * @buffer: a `GtkEntryBuffer`
  *
- * Set the #GtkEntryBuffer object which holds the text for
+ * Set the `GtkEntryBuffer` object which holds the text for
  * this widget.
  */
 void
@@ -2072,27 +2110,28 @@ gtk_entry_set_buffer (GtkEntry       *entry,
 
 /**
  * gtk_entry_set_visibility:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @visible: %TRUE if the contents of the entry are displayed
  *           as plaintext
  *
  * Sets whether the contents of the entry are visible or not.
+ *
  * When visibility is set to %FALSE, characters are displayed
  * as the invisible char, and will also appear that way when
  * the text in the entry widget is copied elsewhere.
  *
  * By default, GTK picks the best invisible character available
  * in the current font, but it can be changed with
- * gtk_entry_set_invisible_char().
+ * [method@Gtk.Entry.set_invisible_char].
  *
- * Note that you probably want to set #GtkEntry:input-purpose
+ * Note that you probably want to set [property@Gtk.Entry:input-purpose]
  * to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to
  * inform input methods about the purpose of this entry,
  * in addition to setting visibility to %FALSE.
  */
 void
 gtk_entry_set_visibility (GtkEntry *entry,
-			  gboolean visible)
+			  gboolean  visible)
 {
   GtkEntryPrivate *priv = gtk_entry_get_instance_private (entry);
 
@@ -2103,13 +2142,14 @@ gtk_entry_set_visibility (GtkEntry *entry,
 
 /**
  * gtk_entry_get_visibility:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Retrieves whether the text in @entry is visible. See
- * gtk_entry_set_visibility().
+ * Retrieves whether the text in @entry is visible.
+ *
+ * See [method@Gtk.Entry.set_visibility].
  *
  * Returns: %TRUE if the text is currently visible
- **/
+ */
 gboolean
 gtk_entry_get_visibility (GtkEntry *entry)
 {
@@ -2122,17 +2162,20 @@ gtk_entry_get_visibility (GtkEntry *entry)
 
 /**
  * gtk_entry_set_invisible_char:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @ch: a Unicode character
- * 
- * Sets the character to use in place of the actual text when
- * gtk_entry_set_visibility() has been called to set text visibility
- * to %FALSE. i.e. this is the character used in “password mode” to
- * show the user how many characters have been typed. By default, GTK
- * picks the best invisible char available in the current font. If you
- * set the invisible char to 0, then the user will get no feedback
- * at all; there will be no text on the screen as they type.
- **/
+ *
+ * Sets the character to use in place of the actual text
+ * in “password mode”.
+ *
+ * See [method@Gtk.Entry.set_visibility] for how to enable
+ * “password mode”.
+ *
+ * By default, GTK picks the best invisible char available in
+ * the current font. If you set the invisible char to 0, then
+ * the user will get no feedback at all; there will be no text
+ * on the screen as they type.
+ */
 void
 gtk_entry_set_invisible_char (GtkEntry *entry,
                               gunichar  ch)
@@ -2146,14 +2189,14 @@ gtk_entry_set_invisible_char (GtkEntry *entry,
 
 /**
  * gtk_entry_get_invisible_char:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Retrieves the character displayed in place of the real characters
- * for entries with visibility set to false. See gtk_entry_set_invisible_char().
+ * Retrieves the character displayed in place of the actual text
+ * in “password mode”.
  *
  * Returns: the current invisible char, or 0, if the entry does not
- *               show invisible text at all. 
- **/
+ *   show invisible text at all.
+ */
 gunichar
 gtk_entry_get_invisible_char (GtkEntry *entry)
 {
@@ -2166,12 +2209,11 @@ gtk_entry_get_invisible_char (GtkEntry *entry)
 
 /**
  * gtk_entry_unset_invisible_char:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Unsets the invisible char previously set with
- * gtk_entry_set_invisible_char(). So that the
- * default invisible char is used again.
- **/
+ * Unsets the invisible char, so that the default invisible char
+ * is used again. See [method@Gtk.Entry.set_invisible_char].
+ */
 void
 gtk_entry_unset_invisible_char (GtkEntry *entry)
 {
@@ -2184,11 +2226,11 @@ gtk_entry_unset_invisible_char (GtkEntry *entry)
 
 /**
  * gtk_entry_set_overwrite_mode:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @overwrite: new value
  *
- * Sets whether the text is overwritten when typing in the #GtkEntry.
- **/
+ * Sets whether the text is overwritten when typing in the `GtkEntry`.
+ */
 void
 gtk_entry_set_overwrite_mode (GtkEntry *entry,
                               gboolean  overwrite)
@@ -2202,12 +2244,12 @@ gtk_entry_set_overwrite_mode (GtkEntry *entry,
 
 /**
  * gtk_entry_get_overwrite_mode:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Gets the value set by gtk_entry_set_overwrite_mode().
+ * Gets whether the `GtkEntry` is in overwrite mode.
  *
  * Returns: whether the text is overwritten when typing.
- **/
+ */
 gboolean
 gtk_entry_get_overwrite_mode (GtkEntry *entry)
 {
@@ -2221,18 +2263,19 @@ gtk_entry_get_overwrite_mode (GtkEntry *entry)
 
 /**
  * gtk_entry_set_max_length:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @max: the maximum length of the entry, or 0 for no maximum.
  *   (other than the maximum length of entries.) The value passed in will
  *   be clamped to the range 0-65536.
  *
- * Sets the maximum allowed length of the contents of the widget. If
- * the current contents are longer than the given length, then they
- * will be truncated to fit.
+ * Sets the maximum allowed length of the contents of the widget.
  *
- * This is equivalent to getting @entry's #GtkEntryBuffer and
- * calling gtk_entry_buffer_set_max_length() on it.
- **/
+ * If the current contents are longer than the given length, then
+ * they will be truncated to fit.
+ *
+ * This is equivalent to getting @entry's `GtkEntryBuffer` and
+ * calling [method@Gtk.EntryBuffer.set_max_length] on it.
+ */
 void
 gtk_entry_set_max_length (GtkEntry     *entry,
                           int           max)
@@ -2246,17 +2289,15 @@ gtk_entry_set_max_length (GtkEntry     *entry,
 
 /**
  * gtk_entry_get_max_length:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Retrieves the maximum allowed length of the text in
- * @entry. See gtk_entry_set_max_length().
+ * Retrieves the maximum allowed length of the text in @entry.
  *
- * This is equivalent to getting @entry's #GtkEntryBuffer and
- * calling gtk_entry_buffer_get_max_length() on it.
+ * See [method@Gtk.Entry.set_max_length].
  *
  * Returns: the maximum allowed number of characters
- *               in #GtkEntry, or 0 if there is no maximum.
- **/
+ *   in `GtkEntry`, or 0 if there is no maximum.
+ */
 int
 gtk_entry_get_max_length (GtkEntry *entry)
 {
@@ -2269,18 +2310,16 @@ gtk_entry_get_max_length (GtkEntry *entry)
 
 /**
  * gtk_entry_get_text_length:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Retrieves the current length of the text in
- * @entry. 
+ * Retrieves the current length of the text in @entry.
  *
- * This is equivalent to getting @entry's #GtkEntryBuffer and
- * calling gtk_entry_buffer_get_length() on it.
-
+ * This is equivalent to getting @entry's `GtkEntryBuffer`
+ * and calling [method@Gtk.EntryBuffer.get_length] on it.
  *
  * Returns: the current number of characters
- *               in #GtkEntry, or 0 if there are none.
- **/
+ *   in `GtkEntry`, or 0 if there are none.
+ */
 guint16
 gtk_entry_get_text_length (GtkEntry *entry)
 {
@@ -2293,14 +2332,15 @@ gtk_entry_get_text_length (GtkEntry *entry)
 
 /**
  * gtk_entry_set_activates_default:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @setting: %TRUE to activate window’s default widget on Enter keypress
  *
- * If @setting is %TRUE, pressing Enter in the @entry will activate the default
- * widget for the window containing the entry. This usually means that
- * the dialog box containing the entry will be closed, since the default
- * widget is usually one of the dialog buttons.
- **/
+ * Sets whether pressing Enter in the @entry will activate the default
+ * widget for the window containing the entry.
+ *
+ * This usually means that the dialog containing the entry will be closed,
+ * since the default widget is usually one of the dialog buttons.
+ */
 void
 gtk_entry_set_activates_default (GtkEntry *entry,
                                  gboolean  setting)
@@ -2314,7 +2354,7 @@ gtk_entry_set_activates_default (GtkEntry *entry,
 
 /**
  * gtk_entry_get_activates_default:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
  * Retrieves the value set by gtk_entry_set_activates_default().
  *
@@ -2332,11 +2372,11 @@ gtk_entry_get_activates_default (GtkEntry *entry)
 
 /**
  * gtk_entry_set_has_frame:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @setting: new value
  *
  * Sets whether the entry has a beveled frame around it.
- **/
+ */
 void
 gtk_entry_set_has_frame (GtkEntry *entry,
                          gboolean  setting)
@@ -2358,12 +2398,12 @@ gtk_entry_set_has_frame (GtkEntry *entry,
 
 /**
  * gtk_entry_get_has_frame:
- * @entry: a #GtkEntry
- * 
+ * @entry: a `GtkEntry`
+ *
  * Gets the value set by gtk_entry_set_has_frame().
- * 
+ *
  * Returns: whether the entry has a beveled frame
- **/
+ */
 gboolean
 gtk_entry_get_has_frame (GtkEntry *entry)
 {
@@ -2374,14 +2414,15 @@ gtk_entry_get_has_frame (GtkEntry *entry)
 
 /**
  * gtk_entry_set_alignment:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @xalign: The horizontal alignment, from 0 (left) to 1 (right).
- *          Reversed for RTL layouts
- * 
- * Sets the alignment for the contents of the entry. This controls
- * the horizontal positioning of the contents when the displayed
- * text is shorter than the width of the entry.
- **/
+ *   Reversed for RTL layouts
+ *
+ * Sets the alignment for the contents of the entry.
+ *
+ * This controls the horizontal positioning of the contents when
+ * the displayed text is shorter than the width of the entry.
+ */
 void
 gtk_entry_set_alignment (GtkEntry *entry,
                          float     xalign)
@@ -2395,12 +2436,12 @@ gtk_entry_set_alignment (GtkEntry *entry,
 
 /**
  * gtk_entry_get_alignment:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
  * Gets the value set by gtk_entry_set_alignment().
  *
  * Returns: the alignment
- **/
+ */
 float
 gtk_entry_get_alignment (GtkEntry *entry)
 {
@@ -2413,11 +2454,11 @@ gtk_entry_get_alignment (GtkEntry *entry)
 
 /**
  * gtk_entry_set_icon_from_paintable:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @icon_pos: Icon position
- * @paintable: (allow-none): A #GdkPaintable, or %NULL
+ * @paintable: (allow-none): A `GdkPaintable`, or %NULL
  *
- * Sets the icon shown in the specified position using a #GdkPaintable
+ * Sets the icon shown in the specified position using a `GdkPaintable`.
  *
  * If @paintable is %NULL, no icon will be shown in the specified position.
  */
@@ -2468,17 +2509,18 @@ gtk_entry_set_icon_from_paintable (GtkEntry             *entry,
 
 /**
  * gtk_entry_set_icon_from_icon_name:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
  * @icon_pos: The position at which to set the icon
  * @icon_name: (allow-none): An icon name, or %NULL
  *
  * Sets the icon shown in the entry at the specified position
  * from the current icon theme.
  *
- * If the icon name isn’t known, a “broken image” icon will be displayed
- * instead.
+ * If the icon name isn’t known, a “broken image” icon will be
+ * displayed instead.
  *
- * If @icon_name is %NULL, no icon will be shown in the specified position.
+ * If @icon_name is %NULL, no icon will be shown in the
+ * specified position.
  */
 void
 gtk_entry_set_icon_from_icon_name (GtkEntry             *entry,
@@ -2523,16 +2565,18 @@ gtk_entry_set_icon_from_icon_name (GtkEntry             *entry,
 
 /**
  * gtk_entry_set_icon_from_gicon:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
  * @icon_pos: The position at which to set the icon
  * @icon: (allow-none): The icon to set, or %NULL
  *
  * Sets the icon shown in the entry at the specified position
  * from the current icon theme.
- * If the icon isn’t known, a “broken image” icon will be displayed
- * instead.
  *
- * If @icon is %NULL, no icon will be shown in the specified position.
+ * If the icon isn’t known, a “broken image” icon will be
+ * displayed instead.
+ *
+ * If @icon is %NULL, no icon will be shown in the
+ * specified position.
  */
 void
 gtk_entry_set_icon_from_gicon (GtkEntry             *entry,
@@ -2576,7 +2620,7 @@ gtk_entry_set_icon_from_gicon (GtkEntry             *entry,
 
 /**
  * gtk_entry_set_icon_activatable:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
  * @icon_pos: Icon position
  * @activatable: %TRUE if the icon should be activatable
  *
@@ -2611,7 +2655,7 @@ gtk_entry_set_icon_activatable (GtkEntry             *entry,
 
 /**
  * gtk_entry_get_icon_activatable:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @icon_pos: Icon position
  *
  * Returns whether the icon is activatable.
@@ -2635,15 +2679,16 @@ gtk_entry_get_icon_activatable (GtkEntry             *entry,
 
 /**
  * gtk_entry_get_icon_paintable:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
  * @icon_pos: Icon position
  *
- * Retrieves the #GdkPaintable used for the icon.
+ * Retrieves the `GdkPaintable` used for the icon.
  *
- * If no #GdkPaintable was used for the icon, %NULL is returned.
+ * If no `GdkPaintable` was used for the icon, %NULL is returned.
  *
- * Returns: (transfer none) (nullable): A #GdkPaintable, or %NULL if no icon is
- *     set for this position or the icon set is not a #GdkPaintable.
+ * Returns: (transfer none) (nullable): A `GdkPaintable`, or %NULL
+ *   if no icon is set for this position or the icon set is not
+ *   a `GdkPaintable`.
  */
 GdkPaintable *
 gtk_entry_get_icon_paintable (GtkEntry             *entry,
@@ -2665,15 +2710,16 @@ gtk_entry_get_icon_paintable (GtkEntry             *entry,
 
 /**
  * gtk_entry_get_icon_gicon:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
  * @icon_pos: Icon position
  *
- * Retrieves the #GIcon used for the icon, or %NULL if there is
- * no icon or if the icon was set by some other method (e.g., by
- * paintable or icon name).
+ * Retrieves the `GIcon` used for the icon.
  *
- * Returns: (transfer none) (nullable): A #GIcon, or %NULL if no icon is set
- *     or if the icon is not a #GIcon
+ * %NULL will be returned if there is no icon or if the icon was
+ * set by some other method (e.g., by `GdkPaintable` or icon name).
+ *
+ * Returns: (transfer none) (nullable): A `GIcon`, or %NULL if no
+ *   icon is set or if the icon is not a `GIcon`
  */
 GIcon *
 gtk_entry_get_icon_gicon (GtkEntry             *entry,
@@ -2695,15 +2741,16 @@ gtk_entry_get_icon_gicon (GtkEntry             *entry,
 
 /**
  * gtk_entry_get_icon_name:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
  * @icon_pos: Icon position
  *
- * Retrieves the icon name used for the icon, or %NULL if there is
- * no icon or if the icon was set by some other method (e.g., by
- * paintable or gicon).
+ * Retrieves the icon name used for the icon.
  *
- * Returns: (nullable): An icon name, or %NULL if no icon is set or if the icon
- *          wasn’t set from an icon name
+ * %NULL is returned if there is no icon or if the icon was set
+ * by some other method (e.g., by `GdkPaintable` or gicon).
+ *
+ * Returns: (nullable): An icon name, or %NULL if no icon is set
+ *   or if the icon wasn’t set from an icon name
  */
 const char *
 gtk_entry_get_icon_name (GtkEntry             *entry,
@@ -2725,10 +2772,10 @@ gtk_entry_get_icon_name (GtkEntry             *entry,
 
 /**
  * gtk_entry_set_icon_sensitive:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
  * @icon_pos: Icon position
  * @sensitive: Specifies whether the icon should appear
- *             sensitive or insensitive
+ *   sensitive or insensitive
  *
  * Sets the sensitivity for the specified icon.
  */
@@ -2759,7 +2806,7 @@ gtk_entry_set_icon_sensitive (GtkEntry             *entry,
 
 /**
  * gtk_entry_get_icon_sensitive:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @icon_pos: Icon position
  *
  * Returns whether the icon appears sensitive or insensitive.
@@ -2786,15 +2833,17 @@ gtk_entry_get_icon_sensitive (GtkEntry             *entry,
 
 /**
  * gtk_entry_get_icon_storage_type:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @icon_pos: Icon position
  *
  * Gets the type of representation being used by the icon
- * to store image data. If the icon has no image data,
- * the return value will be %GTK_IMAGE_EMPTY.
+ * to store image data.
+ *
+ * If the icon has no image data, the return value will
+ * be %GTK_IMAGE_EMPTY.
  *
  * Returns: image representation being used
- **/
+ */
 GtkImageType
 gtk_entry_get_icon_storage_type (GtkEntry             *entry,
                                  GtkEntryIconPosition  icon_pos)
@@ -2815,15 +2864,16 @@ gtk_entry_get_icon_storage_type (GtkEntry             *entry,
 
 /**
  * gtk_entry_get_icon_at_pos:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @x: the x coordinate of the position to find, relative to @entry
  * @y: the y coordinate of the position to find, relative to @entry
  *
- * Finds the icon at the given position and return its index. The
- * position’s coordinates are relative to the @entry’s top left corner.
- * If @x, @y doesn’t lie inside an icon, -1 is returned.
- * This function is intended for use in a #GtkWidget::query-tooltip
- * signal handler.
+ * Finds the icon at the given position and return its index.
+ *
+ * The position’s coordinates are relative to the @entry’s
+ * top left corner. If @x, @y doesn’t lie inside an icon,
+ * -1 is returned. This function is intended for use in a
+ *  [signal@Gtk.Widget::query-tooltip] signal handler.
  *
  * Returns: the index of the icon at the given position, or -1
  */
@@ -2857,12 +2907,14 @@ gtk_entry_get_icon_at_pos (GtkEntry *entry,
 
 /**
  * gtk_entry_set_icon_drag_source:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @icon_pos: icon position
  * @provider: a #GdkContentProvider
  * @actions: a bitmask of the allowed drag actions
  *
- * Sets up the icon at the given position so that GTK will start a drag
+ * Sets up the icon at the given position as drag source.
+ *
+ * This makes it so that GTK will start a drag
  * operation when the user clicks and drags the icon.
  */
 void
@@ -2886,13 +2938,13 @@ gtk_entry_set_icon_drag_source (GtkEntry             *entry,
 
 /**
  * gtk_entry_get_current_icon_drag_source:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Returns the index of the icon which is the source of the current
- * DND operation, or -1.
+ * Returns the index of the icon which is the source of the
+ * current  DND operation, or -1.
  *
- * Returns: index of the icon which is the source of the current
- *          DND operation, or -1.
+ * Returns: index of the icon which is the source of the
+ *   current DND operation, or -1.
  */
 int
 gtk_entry_get_current_icon_drag_source (GtkEntry *entry)
@@ -2917,17 +2969,19 @@ gtk_entry_get_current_icon_drag_source (GtkEntry *entry)
 
 /**
  * gtk_entry_get_icon_area:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
  * @icon_pos: Icon position
  * @icon_area: (out): Return location for the icon’s area
  *
  * Gets the area where entry’s icon at @icon_pos is drawn.
+ *
  * This function is useful when drawing something to the
  * entry in a draw callback.
  *
- * If the entry is not realized or has no icon at the given position,
- * @icon_area is filled with zeros. Otherwise, @icon_area will be filled
- * with the icon's allocation, relative to @entry's allocation.
+ * If the entry is not realized or has no icon at the given
+ * position, @icon_area is filled with zeros. Otherwise,
+ * @icon_area will be filled with the icon's allocation,
+ * relative to @entry's allocation.
  */
 void
 gtk_entry_get_icon_area (GtkEntry             *entry,
@@ -2990,14 +3044,14 @@ ensure_has_tooltip (GtkEntry *entry)
 
 /**
  * gtk_entry_get_icon_tooltip_text:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @icon_pos: the icon position
  *
- * Gets the contents of the tooltip on the icon at the specified 
+ * Gets the contents of the tooltip on the icon at the specified
  * position in @entry.
- * 
+ *
  * Returns: (nullable): the tooltip text, or %NULL. Free the returned
- *     string with g_free() when done.
+ *   string with g_free() when done.
  */
 char *
 gtk_entry_get_icon_tooltip_text (GtkEntry             *entry,
@@ -3024,23 +3078,28 @@ gtk_entry_get_icon_tooltip_text (GtkEntry             *entry,
 
 /**
  * gtk_entry_set_icon_tooltip_text:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @icon_pos: the icon position
- * @tooltip: (allow-none): the contents of the tooltip for the icon, or %NULL
+ * @tooltip: (allow-none): the contents of the tooltip for the
+ *   icon, or %NULL
  *
  * Sets @tooltip as the contents of the tooltip for the icon
  * at the specified position.
  *
  * Use %NULL for @tooltip to remove an existing tooltip.
  *
- * See also gtk_widget_set_tooltip_text() and 
- * gtk_entry_set_icon_tooltip_markup().
+ * See also [method@Gtk.Widget.set_tooltip_text] and
+ * [method@Gtk.Entry.set_icon_tooltip_markup].
  *
- * If you unset the widget tooltip via gtk_widget_set_tooltip_text() or
- * gtk_widget_set_tooltip_markup(), this sets GtkWidget:has-tooltip to %FALSE,
- * which suppresses icon tooltips too. You can resolve this by then calling
- * gtk_widget_set_has_tooltip() to set GtkWidget:has-tooltip back to %TRUE, or
- * setting at least one non-empty tooltip on any icon achieves the same result.
+ * If you unset the widget tooltip via
+ * [method@Gtk.Widget.set_tooltip_text] or
+ * [method@Gtk.Widget.set_tooltip_markup], this sets
+ * [property@Gtk.Widget:has-tooltip] to %FALSE, which suppresses
+ * icon tooltips too. You can resolve this by then calling
+ * [method@Gtk.Widget.set_has_tooltip] to set
+ * [property@Gtk.Widget:has-tooltip] back to %TRUE, or
+ * setting at least one non-empty tooltip on any icon
+ * achieves the same result.
  */
 void
 gtk_entry_set_icon_tooltip_text (GtkEntry             *entry,
@@ -3076,14 +3135,14 @@ gtk_entry_set_icon_tooltip_text (GtkEntry             *entry,
 
 /**
  * gtk_entry_get_icon_tooltip_markup:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @icon_pos: the icon position
  *
- * Gets the contents of the tooltip on the icon at the specified 
+ * Gets the contents of the tooltip on the icon at the specified
  * position in @entry.
- * 
- * Returns: (nullable): the tooltip text, or %NULL. Free the returned
- *     string with g_free() when done.
+ *
+ * Returns: (nullable): the tooltip text, or %NULL. Free the
+ *   returned string with g_free() when done.
  */
 char *
 gtk_entry_get_icon_tooltip_markup (GtkEntry             *entry,
@@ -3105,18 +3164,20 @@ gtk_entry_get_icon_tooltip_markup (GtkEntry             *entry,
 
 /**
  * gtk_entry_set_icon_tooltip_markup:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @icon_pos: the icon position
- * @tooltip: (allow-none): the contents of the tooltip for the icon, or %NULL
+ * @tooltip: (allow-none): the contents of the tooltip for the
+ *   icon, or %NULL
  *
  * Sets @tooltip as the contents of the tooltip for the icon at
- * the specified position. @tooltip is assumed to be marked up with
- * the [Pango text markup language][PangoMarkupFormat].
+ * the specified position.
+ *
+ * @tooltip is assumed to be marked up with Pango Markup.
  *
  * Use %NULL for @tooltip to remove an existing tooltip.
  *
- * See also gtk_widget_set_tooltip_markup() and 
- * gtk_entry_set_icon_tooltip_text().
+ * See also [method@Gtk.Widget.set_tooltip_markup] and
+ * [method@Gtk.Entry.set_icon_tooltip_text].
  */
 void
 gtk_entry_set_icon_tooltip_markup (GtkEntry             *entry,
@@ -3188,13 +3249,15 @@ gtk_entry_query_tooltip (GtkWidget  *widget,
 
 /**
  * gtk_entry_set_completion:
- * @entry: A #GtkEntry
- * @completion: (allow-none): The #GtkEntryCompletion or %NULL
+ * @entry: A `GtkEntry`
+ * @completion: (allow-none): The `GtkEntryCompletion` or %NULL
  *
- * Sets @completion to be the auxiliary completion object to use with @entry.
- * All further configuration of the completion mechanism is done on
- * @completion using the #GtkEntryCompletion API. Completion is disabled if
- * @completion is set to %NULL.
+ * Sets @completion to be the auxiliary completion object
+ * to use with @entry.
+ *
+ * All further configuration of the completion mechanism is
+ * done on @completion using the `GtkEntryCompletion` API.
+ * Completion is disabled if @completion is set to %NULL.
  */
 void
 gtk_entry_set_completion (GtkEntry           *entry,
@@ -3234,12 +3297,13 @@ gtk_entry_set_completion (GtkEntry           *entry,
 
 /**
  * gtk_entry_get_completion:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
  *
- * Returns the auxiliary completion object currently in use by @entry.
+ * Returns the auxiliary completion object currently
+ * in use by @entry.
  *
- * Returns: (nullable) (transfer none): The auxiliary completion object currently
- *     in use by @entry.
+ * Returns: (nullable) (transfer none): The auxiliary
+ *   completion object currently in use by @entry
  */
 GtkEntryCompletion *
 gtk_entry_get_completion (GtkEntry *entry)
@@ -3273,12 +3337,13 @@ gtk_entry_ensure_progress_widget (GtkEntry *entry)
 
 /**
  * gtk_entry_set_progress_fraction:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @fraction: fraction of the task that’s been completed
  *
  * Causes the entry’s progress indicator to “fill in” the given
- * fraction of the bar. The fraction should be between 0.0 and 1.0,
- * inclusive.
+ * fraction of the bar.
+ *
+ * The fraction should be between 0.0 and 1.0, inclusive.
  */
 void
 gtk_entry_set_progress_fraction (GtkEntry *entry,
@@ -3304,10 +3369,11 @@ gtk_entry_set_progress_fraction (GtkEntry *entry,
 
 /**
  * gtk_entry_get_progress_fraction:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
  * Returns the current fraction of the task that’s been completed.
- * See gtk_entry_set_progress_fraction().
+ *
+ * See [method@Gtk.Entry.set_progress_fraction].
  *
  * Returns: a fraction from 0.0 to 1.0
  */
@@ -3326,11 +3392,14 @@ gtk_entry_get_progress_fraction (GtkEntry *entry)
 
 /**
  * gtk_entry_set_progress_pulse_step:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @fraction: fraction between 0.0 and 1.0
  *
  * Sets the fraction of total entry width to move the progress
- * bouncing block for each call to gtk_entry_progress_pulse().
+ * bouncing block for each pulse.
+ *
+ * Use [method@Gtk.Entry.progress_pulse] to pulse
+ * the progress.
  */
 void
 gtk_entry_set_progress_pulse_step (GtkEntry *entry,
@@ -3353,9 +3422,10 @@ gtk_entry_set_progress_pulse_step (GtkEntry *entry,
 
 /**
  * gtk_entry_get_progress_pulse_step:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Retrieves the pulse step set with gtk_entry_set_progress_pulse_step().
+ * Retrieves the pulse step set with
+ * gtk_entry_set_progress_pulse_step().
  *
  * Returns: a fraction from 0.0 to 1.0
  */
@@ -3374,14 +3444,16 @@ gtk_entry_get_progress_pulse_step (GtkEntry *entry)
 
 /**
  * gtk_entry_progress_pulse:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Indicates that some progress is made, but you don’t know how much.
- * Causes the entry’s progress indicator to enter “activity mode,”
- * where a block bounces back and forth. Each call to
- * gtk_entry_progress_pulse() causes the block to move by a little bit
- * (the amount of movement per pulse is determined by
- * gtk_entry_set_progress_pulse_step()).
+ * Indicates that some progress is made, but you don’t
+ * know how much.
+ *
+ * Causes the entry’s progress indicator to enter “activity
+ * mode”, where a block bounces back and forth. Each call to
+ * gtk_entry_progress_pulse() causes the block to move by a
+ * little bit (the amount of movement per pulse is determined
+ * by [method@Gtk.Entry.set_progress_pulse_step]).
  */
 void
 gtk_entry_progress_pulse (GtkEntry *entry)
@@ -3396,13 +3468,15 @@ gtk_entry_progress_pulse (GtkEntry *entry)
 
 /**
  * gtk_entry_set_placeholder_text:
- * @entry: a #GtkEntry
- * @text: (nullable): a string to be displayed when @entry is empty and unfocused, or %NULL
+ * @entry: a `GtkEntry`
+ * @text: (nullable): a string to be displayed when @entry is
+ *   empty and unfocused, or %NULL
  *
  * Sets text to be displayed in @entry when it is empty.
- * This can be used to give a visual hint of the expected contents of
- * the #GtkEntry.
- **/
+ *
+ * This can be used to give a visual hint of the expected
+ * contents of the `GtkEntry`.
+ */
 void
 gtk_entry_set_placeholder_text (GtkEntry    *entry,
                                 const char *text)
@@ -3420,15 +3494,17 @@ gtk_entry_set_placeholder_text (GtkEntry    *entry,
 
 /**
  * gtk_entry_get_placeholder_text:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Retrieves the text that will be displayed when @entry is empty and unfocused
+ * Retrieves the text that will be displayed when @entry
+ * is empty and unfocused
  *
- * Returns: (nullable) (transfer none):a pointer to the placeholder text as a string.
- *   This string points to internally allocated storage in the widget and must
- *   not be freed, modified or stored. If no placeholder text has been set,
- *   %NULL will be returned.
- **/
+ * Returns: (nullable) (transfer none):a pointer to the
+ *   placeholder text as a string. This string points to
+ *   internally allocated storage in the widget and must
+ *   not be freed, modified or stored. If no placeholder
+ *   text has been set, %NULL will be returned.
+ */
 const char *
 gtk_entry_get_placeholder_text (GtkEntry *entry)
 {
@@ -3441,12 +3517,11 @@ gtk_entry_get_placeholder_text (GtkEntry *entry)
 
 /**
  * gtk_entry_set_input_purpose:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @purpose: the purpose
  *
- * Sets the #GtkEntry:input-purpose property which
- * can be used by on-screen keyboards and other input
- * methods to adjust their behaviour.
+ * Sets the input purpose which can be used by input methods
+ * to adjust their behavior.
  */
 void
 gtk_entry_set_input_purpose (GtkEntry        *entry,
@@ -3462,9 +3537,9 @@ gtk_entry_set_input_purpose (GtkEntry        *entry,
 
 /**
  * gtk_entry_get_input_purpose:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Gets the value of the #GtkEntry:input-purpose property.
+ * Gets the input purpose of the `GtkEntry`.
  */
 GtkInputPurpose
 gtk_entry_get_input_purpose (GtkEntry *entry)
@@ -3478,11 +3553,11 @@ gtk_entry_get_input_purpose (GtkEntry *entry)
 
 /**
  * gtk_entry_set_input_hints:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @hints: the hints
  *
- * Sets the #GtkEntry:input-hints property, which
- * allows input methods to fine-tune their behaviour.
+ * Set additional hints which allow input methods to
+ * fine-tune their behavior.
  */
 void
 gtk_entry_set_input_hints (GtkEntry      *entry,
@@ -3498,9 +3573,9 @@ gtk_entry_set_input_hints (GtkEntry      *entry,
 
 /**
  * gtk_entry_get_input_hints:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Gets the value of the #GtkEntry:input-hints property.
+ * Gets the input hints of this `GtkEntry`.
  */
 GtkInputHints
 gtk_entry_get_input_hints (GtkEntry *entry)
@@ -3514,11 +3589,16 @@ gtk_entry_get_input_hints (GtkEntry *entry)
 
 /**
  * gtk_entry_set_attributes:
- * @entry: a #GtkEntry
- * @attrs: a #PangoAttrList
+ * @entry: a `GtkEntry`
+ * @attrs: a `PangoAttrList`
  *
- * Sets a #PangoAttrList; the attributes in the list are applied to the
- * entry text.
+ * Sets a `PangoAttrList`.
+ *
+ * The attributes in the list are applied to the entry text.
+ *
+ * Since the attributes will be applies to text that changes
+ * as the user types, it makes most sense to use attributes
+ * with unlimited extent.
  */
 void
 gtk_entry_set_attributes (GtkEntry      *entry,
@@ -3533,13 +3613,14 @@ gtk_entry_set_attributes (GtkEntry      *entry,
 
 /**
  * gtk_entry_get_attributes:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Gets the attribute list that was set on the entry using
- * gtk_entry_set_attributes(), if any.
+ * Gets the attribute list of the `GtkEntry`.
  *
- * Returns: (transfer none) (nullable): the attribute list, or %NULL
- *     if none was set.
+ * See [method@Gtk.Entry.set_attributes].
+ *
+ * Returns: (transfer none) (nullable): the attribute list,
+ *   or %NULL if none was set.
  */
 PangoAttrList *
 gtk_entry_get_attributes (GtkEntry *entry)
@@ -3553,11 +3634,12 @@ gtk_entry_get_attributes (GtkEntry *entry)
 
 /**
  * gtk_entry_set_tabs:
- * @entry: a #GtkEntry
- * @tabs: (nullable): a #PangoTabArray
+ * @entry: a `GtkEntry`
+ * @tabs: (nullable): a `PangoTabArray`
  *
- * Sets a #PangoTabArray; the tabstops in the array are applied to the entry
- * text.
+ * Sets a `PangoTabArray`.
+ *
+ * The tabstops in the array are applied to the entry text.
  */
 
 void
@@ -3573,12 +3655,14 @@ gtk_entry_set_tabs (GtkEntry      *entry,
 
 /**
  * gtk_entry_get_tabs:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
- * Gets the tabstops that were set on the entry using gtk_entry_set_tabs(), if
- * any.
+ * Gets the tabstops of the `GtkEntry.
  *
- * Returns: (nullable) (transfer none): the tabstops, or %NULL if none was set.
+ * See [method@Gtk.Entry.set_tabs].
+ *
+ * Returns: (nullable) (transfer none): the tabstops,
+ *   or %NULL if none was set.
  */
 
 PangoTabArray *
@@ -3672,8 +3756,8 @@ gtk_entry_get_text_widget (GtkEntry *entry)
 
 /**
  * gtk_entry_set_extra_menu:
- * @entry: a #GtkEntry
- * @model: (allow-none): a #GMenuModel
+ * @entry: a `GtkEntry`
+ * @model: (allow-none): a `GMenuModel`
  *
  * Sets a menu model to add when constructing
  * the context menu for @entry.
@@ -3693,7 +3777,7 @@ gtk_entry_set_extra_menu (GtkEntry   *entry,
 
 /**
  * gtk_entry_get_extra_menu:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  *
  * Gets the menu model set with gtk_entry_set_extra_menu().
  *
@@ -3711,11 +3795,15 @@ gtk_entry_get_extra_menu (GtkEntry *entry)
 
 /*< private >
  * gtk_entry_activate_icon:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
  * @pos: the icon position
  *
- * Emits the #GtkEntry::icon-press and #GtkEntry::icon-release signals on
- * the @entry icon at the given @pos, if the icon is set and activatable.
+ * Activates an icon.
+ *
+ * This causes the [signal@Gtk.Entry::icon-press] and
+ * [signal@Gtk.Entry::icon-release] signals to be emitted
+ * on the @entry icon at the given @pos, if the icon is
+ * set and activatable.
  *
  * Returns: %TRUE if the signal was emitted
  */