From bf978ba5a604889516f30e21f9dc20fc0b8245ba Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sun, 28 Feb 2021 13:13:44 -0500
Subject: [PATCH] textiter: Convert docs

---
 gtk/gtktextiter.c | 1126 +++++++++++++++++++++++++--------------------
 gtk/gtktextiter.h |    2 +-
 2 files changed, 625 insertions(+), 503 deletions(-)

diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 82d3e88b45..24e25d9d85 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -34,16 +34,14 @@
 
 
 /**
- * SECTION:gtktextiter
- * @Short_description: Text buffer iterator
- * @Title: GtkTextIter
+ * GtkTextIter:
  *
- * An iterator for the contents of a [class@Gtk.TextBuffer]
+ * An iterator for the contents of a `GtkTextBuffer`.
  *
  * You may wish to begin by reading the
- * [text widget conceptual overview][TextWidget]
- * which gives an overview of all the objects and data
- * types related to the text widget and how they work together.
+ * [text widget conceptual overview](section-text-widget.html),
+ * which gives an overview of all the objects and data types
+ * related to the text widget and how they work together.
  */
 
 
@@ -386,7 +384,7 @@ check_invariants (const GtkTextIter *iter)
  * gtk_text_iter_get_buffer:
  * @iter: an iterator
  *
- * Returns the #GtkTextBuffer this iterator is associated with.
+ * Returns the `GtkTextBuffer` this iterator is associated with.
  *
  * Returns: (transfer none): the buffer
  **/
@@ -411,13 +409,16 @@ gtk_text_iter_get_buffer (const GtkTextIter *iter)
  * gtk_text_iter_copy:
  * @iter: an iterator
  *
- * Creates a dynamically-allocated copy of an iterator. This function
- * is not useful in applications, because iterators can be copied with a
- * simple assignment (`GtkTextIter i = j;`). The
- * function is used by language bindings.
+ * Creates a dynamically-allocated copy of an iterator.
  *
- * Returns: a copy of the @iter, free with gtk_text_iter_free()
- **/
+ * This function is not useful in applications, because
+ * iterators can be copied with a simple assignment
+ * (`GtkTextIter i = j;`).
+ *
+ * The function is used by language bindings.
+ *
+ * Returns: a copy of the @iter, free with [method@Gtk.TextIter.free]
+ */
 GtkTextIter*
 gtk_text_iter_copy (const GtkTextIter *iter)
 {
@@ -436,11 +437,12 @@ gtk_text_iter_copy (const GtkTextIter *iter)
  * gtk_text_iter_free:
  * @iter: a dynamically-allocated iterator
  *
- * Free an iterator allocated on the heap. This function
- * is intended for use in language bindings, and is not
- * especially useful for applications, because iterators can
- * simply be allocated on the stack.
- **/
+ * Free an iterator allocated on the heap.
+ *
+ * This function is intended for use in language bindings,
+ * and is not especially useful for applications, because
+ * iterators can simply be allocated on the stack.
+ */
 void
 gtk_text_iter_free (GtkTextIter *iter)
 {
@@ -451,14 +453,16 @@ gtk_text_iter_free (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_assign:
- * @iter: a #GtkTextIter
- * @other: another #GtkTextIter
+ * @iter: a `GtkTextIter`
+ * @other: another `GtkTextIter`
  *
- * Assigns the value of @other to @iter.  This function
- * is not useful in applications, because iterators can be assigned
- * with `GtkTextIter i = j;`. The
- * function is used by language bindings.
- **/
+ * Assigns the value of @other to @iter.
+ *
+ * This function is not useful in applications, because
+ * iterators can be assigned with `GtkTextIter i = j;`.
+ *
+ * The function is used by language bindings.
+ */
 void
 gtk_text_iter_assign (GtkTextIter       *iter,
                       const GtkTextIter *other)
@@ -586,13 +590,14 @@ _gtk_text_iter_get_btree (const GtkTextIter *iter)
  * @iter: an iterator
  *
  * Returns the character offset of an iterator.
- * Each character in a #GtkTextBuffer has an offset,
+ *
+ * Each character in a `GtkTextBuffer` has an offset,
  * starting with 0 for the first character in the buffer.
- * Use gtk_text_buffer_get_iter_at_offset() to convert an
- * offset back into an iterator.
+ * Use [method@Gtk,TextBuffer.get_iter_at_offset] to convert
+ * an offset back into an iterator.
  *
  * Returns: a character offset
- **/
+ */
 int
 gtk_text_iter_get_offset (const GtkTextIter *iter)
 {
@@ -625,12 +630,13 @@ gtk_text_iter_get_offset (const GtkTextIter *iter)
  * gtk_text_iter_get_line:
  * @iter: an iterator
  *
- * Returns the line number containing the iterator. Lines in
- * a #GtkTextBuffer are numbered beginning with 0 for the first
- * line in the buffer.
+ * Returns the line number containing the iterator.
+ *
+ * Lines in a `GtkTextBuffer` are numbered beginning
+ * with 0 for the first line in the buffer.
  *
  * Returns: a line number
- **/
+ */
 int
 gtk_text_iter_get_line (const GtkTextIter *iter)
 {
@@ -658,10 +664,11 @@ gtk_text_iter_get_line (const GtkTextIter *iter)
  *
  * Returns the character offset of the iterator,
  * counting from the start of a newline-terminated line.
+ *
  * The first character on the line has offset 0.
  *
  * Returns: offset from start of line
- **/
+ */
 int
 gtk_text_iter_get_line_offset (const GtkTextIter *iter)
 {
@@ -687,12 +694,13 @@ gtk_text_iter_get_line_offset (const GtkTextIter *iter)
  *
  * Returns the byte index of the iterator, counting
  * from the start of a newline-terminated line.
- * Remember that #GtkTextBuffer encodes text in
+ *
+ * Remember that `GtkTextBuffer` encodes text in
  * UTF-8, and that characters can require a variable
  * number of bytes to represent.
  *
  * Returns: distance from start of line, in bytes
- **/
+ */
 int
 gtk_text_iter_get_line_index (const GtkTextIter *iter)
 {
@@ -714,15 +722,15 @@ gtk_text_iter_get_line_index (const GtkTextIter *iter)
 
 /**
  * gtk_text_iter_get_visible_line_offset:
- * @iter: a #GtkTextIter
- * 
+ * @iter: a `GtkTextIter`
+ *
  * Returns the offset in characters from the start of the
  * line to the given @iter, not counting characters that
  * are invisible due to tags with the “invisible” flag
  * toggled on.
- * 
- * Returns: offset in visible characters from the start of the line 
- **/
+ *
+ * Returns: offset in visible characters from the start of the line
+ */
 int
 gtk_text_iter_get_visible_line_offset (const GtkTextIter *iter)
 {
@@ -779,15 +787,15 @@ gtk_text_iter_get_visible_line_offset (const GtkTextIter *iter)
 
 /**
  * gtk_text_iter_get_visible_line_index:
- * @iter: a #GtkTextIter
- * 
+ * @iter: a `GtkTextIter`
+ *
  * Returns the number of bytes from the start of the
  * line to the given @iter, not counting bytes that
  * are invisible due to tags with the “invisible” flag
  * toggled on.
- * 
+ *
  * Returns: byte index of @iter with respect to the start of the line
- **/
+ */
 int
 gtk_text_iter_get_visible_line_index (const GtkTextIter *iter)
 {
@@ -849,13 +857,15 @@ gtk_text_iter_get_visible_line_index (const GtkTextIter *iter)
  * gtk_text_iter_get_char:
  * @iter: an iterator
  *
- * The Unicode character at this iterator is returned.  (Equivalent to
- * operator* on a C++ iterator.)  If the element at this iterator is a
- * non-character element, such as an image embedded in the buffer, the
- * Unicode “unknown” character 0xFFFC is returned. If invoked on
- * the end iterator, zero is returned; zero is not a valid Unicode character.
- * So you can write a loop which ends when gtk_text_iter_get_char()
- * returns 0.
+ * The Unicode character at this iterator is returned.
+ *
+ * Equivalent to operator* on a C++ iterator. If the element at
+ * this iterator is a non-character element, such as an image
+ * embedded in the buffer, the Unicode “unknown” character 0xFFFC
+ * is returned. If invoked on the end iterator, zero is returned;
+ * zero is not a valid Unicode character.
+ *
+ * So you can write a loop which ends when this function returns 0.
  *
  * Returns: a Unicode character, or 0 if @iter is not dereferenceable
  */
@@ -894,17 +904,19 @@ gtk_text_iter_get_char (const GtkTextIter *iter)
  * @start: iterator at start of a range
  * @end: iterator at end of a range
  *
- * Returns the text in the given range. A “slice” is an array of
- * characters encoded in UTF-8 format, including the Unicode “unknown”
- * character 0xFFFC for iterable non-character elements in the buffer,
- * such as images.  Because images are encoded in the slice, byte and
+ * Returns the text in the given range.
+ *
+ * A “slice” is an array of characters encoded in UTF-8 format,
+ * including the Unicode “unknown” character 0xFFFC for iterable
+ * non-character elements in the buffer, such as images.
+ * Because images are encoded in the slice, byte and
  * character offsets in the returned array will correspond to byte
  * offsets in the text buffer. Note that 0xFFFC can occur in normal
  * text as well, so it is not a reliable indicator that a paintable or
  * widget is in the buffer.
  *
  * Returns: (transfer full): slice of text from the buffer
- **/
+ */
 char *
 gtk_text_iter_get_slice       (const GtkTextIter *start,
                                const GtkTextIter *end)
@@ -923,14 +935,16 @@ gtk_text_iter_get_slice       (const GtkTextIter *start,
  * @start: iterator at start of a range
  * @end: iterator at end of a range
  *
- * Returns text in the given range.  If the range
+ * Returns text in the given range.
+ *
+ * If the range
  * contains non-text elements such as images, the character and byte
  * offsets in the returned string will not correspond to character and
  * byte offsets in the buffer. If you want offsets to correspond, see
- * gtk_text_iter_get_slice().
+ * [method@Gtk.TextIter.get_slice].
  *
  * Returns: (transfer full): array of characters from the buffer
- **/
+ */
 char *
 gtk_text_iter_get_text       (const GtkTextIter *start,
                               const GtkTextIter *end)
@@ -949,12 +963,15 @@ gtk_text_iter_get_text       (const GtkTextIter *start,
  * @start: iterator at start of range
  * @end: iterator at end of range
  *
- * Like gtk_text_iter_get_slice(), but invisible text is not included.
- * Invisible text is usually invisible because a #GtkTextTag with the
- * “invisible” attribute turned on has been applied to it.
+ * Returns visible text in the given range.
+ *
+ * Like [method@Gtk.TextIter.get_slice], but invisible text
+ * is not included. Invisible text is usually invisible because
+ * a `GtkTextTag` with the “invisible” attribute turned on has
+ * been applied to it.
  *
  * Returns: (transfer full): slice of text from the buffer
- **/
+ */
 char *
 gtk_text_iter_get_visible_slice (const GtkTextIter  *start,
                                  const GtkTextIter  *end)
@@ -973,13 +990,16 @@ gtk_text_iter_get_visible_slice (const GtkTextIter  *start,
  * @start: iterator at start of range
  * @end: iterator at end of range
  *
- * Like gtk_text_iter_get_text(), but invisible text is not included.
- * Invisible text is usually invisible because a #GtkTextTag with the
- * “invisible” attribute turned on has been applied to it.
+ * Returns visible text in the given range.
+ *
+ * Like [method@Gtk.TextIter.get_text], but invisible text
+ * is not included. Invisible text is usually invisible because
+ * a `GtkTextTag` with the “invisible” attribute turned on has
+ * been applied to it.
  *
  * Returns: (transfer full): string containing visible text in the
  * range
- **/
+ */
 char *
 gtk_text_iter_get_visible_text (const GtkTextIter  *start,
                                 const GtkTextIter  *end)
@@ -997,8 +1017,9 @@ gtk_text_iter_get_visible_text (const GtkTextIter  *start,
  * gtk_text_iter_get_paintable:
  * @iter: an iterator
  *
- * If the element at @iter is a paintable, the paintable is returned
- * (with no new reference count added). Otherwise, %NULL is returned.
+ * If the element at @iter is a paintable, the paintable is returned.
+ *
+ * Otherwise, %NULL is returned.
  *
  * Returns: (transfer none): the paintable at @iter
  **/
@@ -1027,8 +1048,9 @@ gtk_text_iter_get_paintable (const GtkTextIter *iter)
  * @iter: an iterator
  *
  * If the location at @iter contains a child anchor, the
- * anchor is returned (with no new reference count added). Otherwise,
- * %NULL is returned.
+ * anchor is returned.
+ *
+ * Otherwise, %NULL is returned.
  *
  * Returns: (transfer none): the anchor at @iter
  **/
@@ -1056,14 +1078,17 @@ gtk_text_iter_get_child_anchor (const GtkTextIter *iter)
  * gtk_text_iter_get_marks:
  * @iter: an iterator
  *
- * Returns a list of all #GtkTextMark at this location. Because marks
- * are not iterable (they don’t take up any "space" in the buffer,
- * they are just marks in between iterable locations), multiple marks
- * can exist in the same place. The returned list is not in any
- * meaningful order.
+ * Returns a list of all `GtkTextMark` at this location.
  *
- * Returns: (element-type GtkTextMark) (transfer container): list of #GtkTextMark
- **/
+ * Because marks are not iterable (they don’t take up any "space"
+ * in the buffer, they are just marks in between iterable locations),
+ * multiple marks can exist in the same place.
+ *
+ * The returned list is not in any meaningful order.
+ *
+ * Returns: (element-type GtkTextMark) (transfer container):
+ *   list of `GtkTextMark`
+ */
 GSList*
 gtk_text_iter_get_marks (const GtkTextIter *iter)
 {
@@ -1101,15 +1126,18 @@ gtk_text_iter_get_marks (const GtkTextIter *iter)
  * @iter: an iterator
  * @toggled_on: %TRUE to get toggled-on tags
  *
- * Returns a list of #GtkTextTag that are toggled on or off at this
- * point.  (If @toggled_on is %TRUE, the list contains tags that are
- * toggled on.) If a tag is toggled on at @iter, then some non-empty
+ * Returns a list of `GtkTextTag` that are toggled on or off at this
+ * point.
+ *
+ * If @toggled_on is %TRUE, the list contains tags that are
+ * toggled on. If a tag is toggled on at @iter, then some non-empty
  * range of characters following @iter has that tag applied to it.  If
  * a tag is toggled off, then some non-empty range following @iter
  * does not have the tag applied to it.
  *
- * Returns: (element-type GtkTextTag) (transfer container): tags toggled at this point
- **/
+ * Returns: (element-type GtkTextTag) (transfer container): tags
+ *   toggled at this point
+ */
 GSList*
 gtk_text_iter_get_toggled_tags  (const GtkTextIter  *iter,
                                  gboolean            toggled_on)
@@ -1157,17 +1185,18 @@ gtk_text_iter_get_toggled_tags  (const GtkTextIter  *iter,
 /**
  * gtk_text_iter_starts_tag:
  * @iter: an iterator
- * @tag: (nullable): a #GtkTextTag, or %NULL
+ * @tag: (nullable): a `GtkTextTag`, or %NULL
  *
- * Returns %TRUE if @tag is toggled on at exactly this point. If @tag
- * is %NULL, returns %TRUE if any tag is toggled on at this point.
+ * Returns %TRUE if @tag is toggled on at exactly this point.
  *
- * Note that if gtk_text_iter_starts_tag() returns %TRUE, it means that @iter is
- * at the beginning of the tagged range, and that the
+ * If @tag is %NULL, returns %TRUE if any tag is toggled on at this point.
+ *
+ * Note that if this function returns %TRUE, it means that
+ * @iter is at the beginning of the tagged range, and that the
  * character at @iter is inside the tagged range. In other
- * words, unlike gtk_text_iter_ends_tag(), if gtk_text_iter_starts_tag() returns
- * %TRUE, gtk_text_iter_has_tag() will also return %TRUE for the same
- * parameters.
+ * words, unlike [method@Gtk.TextIter.ends_tag], if
+ * this function returns %TRUE, [method@Gtk.TextIter.has_tag
+ * will also return %TRUE for the same parameters.
  *
  * Returns: whether @iter is the start of a range tagged with @tag
  **/
@@ -1206,19 +1235,21 @@ gtk_text_iter_starts_tag (const GtkTextIter *iter,
 /**
  * gtk_text_iter_ends_tag:
  * @iter: an iterator
- * @tag: (allow-none): a #GtkTextTag, or %NULL
+ * @tag: (allow-none): a `GtkTextTag`, or %NULL
  *
- * Returns %TRUE if @tag is toggled off at exactly this point. If @tag
- * is %NULL, returns %TRUE if any tag is toggled off at this point.
+ * Returns %TRUE if @tag is toggled off at exactly this point.
  *
- * Note that if gtk_text_iter_ends_tag() returns %TRUE, it means that @iter is
- * at the end of the tagged range, but that the character
+ * If @tag is %NULL, returns %TRUE if any tag is toggled off at this point.
+ *
+ * Note that if this function returns %TRUE, it means that
+ * @iter is at the end of the tagged range, but that the character
  * at @iter is outside the tagged range. In other words,
- * unlike gtk_text_iter_starts_tag(), if gtk_text_iter_ends_tag() returns %TRUE,
- * gtk_text_iter_has_tag() will return %FALSE for the same parameters.
+ * unlike [method@Gtk.TextIter.starts_tag], if this function
+ * returns %TRUE, [method@Gtk.TextIter.has_tag] will return
+ * %FALSE for the same parameters.
  *
  * Returns: whether @iter is the end of a range tagged with @tag
- **/
+ */
 gboolean
 gtk_text_iter_ends_tag   (const GtkTextIter  *iter,
                           GtkTextTag         *tag)
@@ -1254,14 +1285,16 @@ gtk_text_iter_ends_tag   (const GtkTextIter  *iter,
 /**
  * gtk_text_iter_toggles_tag:
  * @iter: an iterator
- * @tag: (allow-none): a #GtkTextTag, or %NULL
+ * @tag: (allow-none): a `GtkTextTag`, or %NULL
+ *
+ * Gets whether a range with @tag applied to it begins
+ * or ends at @iter.
  *
  * This is equivalent to (gtk_text_iter_starts_tag() ||
- * gtk_text_iter_ends_tag()), i.e. it tells you whether a range with
- * @tag applied to it begins or ends at @iter.
+ * gtk_text_iter_ends_tag())
  *
  * Returns: whether @tag is toggled on or off at @iter
- **/
+ */
 gboolean
 gtk_text_iter_toggles_tag (const GtkTextIter  *iter,
                            GtkTextTag         *tag)
@@ -1296,13 +1329,16 @@ gtk_text_iter_toggles_tag (const GtkTextIter  *iter,
 /**
  * gtk_text_iter_has_tag:
  * @iter: an iterator
- * @tag: a #GtkTextTag
+ * @tag: a `GtkTextTag`
  *
- * Returns %TRUE if @iter points to a character that is part of a range tagged
- * with @tag. See also gtk_text_iter_starts_tag() and gtk_text_iter_ends_tag().
+ * Returns %TRUE if @iter points to a character that is part
+ * of a range tagged with @tag.
+ *
+ * See also [method@Gtk.TextIter.starts_tag] and
+ * [method@Gtk.TextIter.ends_tag].
  *
  * Returns: whether @iter is tagged with @tag
- **/
+ */
 gboolean
 gtk_text_iter_has_tag (const GtkTextIter   *iter,
                        GtkTextTag          *tag)
@@ -1335,14 +1371,18 @@ gtk_text_iter_has_tag (const GtkTextIter   *iter,
 /**
  * gtk_text_iter_get_tags:
  * @iter: a #GtkTextIter
- * 
- * Returns a list of tags that apply to @iter, in ascending order of
- * priority (highest-priority tags are last). The #GtkTextTag in the
- * list don’t have a reference added, but you have to free the list
- * itself.
  *
- * Returns: (element-type GtkTextTag) (transfer container): list of #GtkTextTag
- **/
+ * Returns a list of tags that apply to @iter, in ascending order of
+ * priority.
+ *
+ * The highest-priority tags are last.
+ *
+ * The `GtkTextTag`s in the list don’t have a reference added,
+ * but you have to free the list itself.
+ *
+ * Returns: (element-type GtkTextTag) (transfer container): list of
+ *   `GtkTextTag`
+ */
 GSList*
 gtk_text_iter_get_tags (const GtkTextIter *iter)
 {
@@ -1394,11 +1434,11 @@ gtk_text_iter_get_tags (const GtkTextIter *iter)
  * inserted at @iter, because for insertion you don’t want to know
  * whether the char at @iter is inside an editable range, you want to
  * know whether a new character inserted at @iter would be inside an
- * editable range. Use gtk_text_iter_can_insert() to handle this
+ * editable range. Use [method@Gtk.TextIter.can_insert] to handle this
  * case.
  *
  * Returns: whether @iter is inside an editable range
- **/
+ */
 gboolean
 gtk_text_iter_editable (const GtkTextIter *iter,
                         gboolean           default_setting)
@@ -1425,16 +1465,18 @@ gtk_text_iter_editable (const GtkTextIter *iter,
  * gtk_text_iter_can_insert:
  * @iter: an iterator
  * @default_editability: %TRUE if text is editable by default
- * 
+ *
  * Considering the default editability of the buffer, and tags that
  * affect editability, determines whether text inserted at @iter would
- * be editable. If text inserted at @iter would be editable then the
+ * be editable.
+ *
+ * If text inserted at @iter would be editable then the
  * user should be allowed to insert text at @iter.
- * gtk_text_buffer_insert_interactive() uses this function to decide
- * whether insertions are allowed at a given position.
- * 
+ * [method@Gtk.TextBuffer.insert_interactive] uses this function
+ * to decide whether insertions are allowed at a given position.
+ *
  * Returns: whether text inserted at @iter would be editable
- **/
+ */
 gboolean
 gtk_text_iter_can_insert (const GtkTextIter *iter,
                           gboolean           default_editability)
@@ -1494,10 +1536,10 @@ gtk_text_iter_get_attributes (const GtkTextIter  *iter,
  * Returns the language in effect at @iter.
  *
  * If no tags affecting language apply to @iter, the return
- * value is identical to that of gtk_get_default_language().
+ * value is identical to that of [func@Gtk.get_default_language].
  *
  * Returns: (transfer full): language in effect at @iter
- **/
+ */
 PangoLanguage *
 gtk_text_iter_get_language (const GtkTextIter *iter)
 {
@@ -1519,14 +1561,16 @@ gtk_text_iter_get_language (const GtkTextIter *iter)
  * gtk_text_iter_starts_line:
  * @iter: an iterator
  *
- * Returns %TRUE if @iter begins a paragraph,
- * i.e. if gtk_text_iter_get_line_offset() would return 0.
- * However this function is potentially more efficient than
- * gtk_text_iter_get_line_offset() because it doesn’t have to compute
- * the offset, it just has to see whether it’s 0.
+ * Returns %TRUE if @iter begins a paragraph.
+ *
+ * This is the case if [method@Gtk.TextIter.get_line_offset]
+ * would return 0. However this function is potentially more
+ * efficient than [method@Gtk.TextIter.get_line_offset], because
+ * it doesn’t have to compute the offset, it just has to see
+ * whether it’s 0.
  *
  * Returns: whether @iter begins a line
- **/
+ */
 gboolean
 gtk_text_iter_starts_line (const GtkTextIter   *iter)
 {
@@ -1557,16 +1601,19 @@ gtk_text_iter_starts_line (const GtkTextIter   *iter)
  * @iter: an iterator
  *
  * Returns %TRUE if @iter points to the start of the paragraph
- * delimiter characters for a line (delimiters will be either a
- * newline, a carriage return, a carriage return followed by a
- * newline, or a Unicode paragraph separator character). Note that an
- * iterator pointing to the \n of a \r\n pair will not be counted as
- * the end of a line, the line ends before the \r. The end iterator is
- * considered to be at the end of a line, even though there are no
- * paragraph delimiter chars there.
+ * delimiter characters for a line.
+ *
+ * Delimiters will be either a newline, a carriage return, a carriage
+ * return followed by a newline, or a Unicode paragraph separator
+ * character.
+ *
+ * Note that an iterator pointing to the \n of a \r\n pair will not be
+ * counted as the end of a line, the line ends before the \r. The end
+ * iterator is considered to be at the end of a line, even though there
+ * are no paragraph delimiter chars there.
  *
  * Returns: whether @iter is at the end of a line
- **/
+ */
 gboolean
 gtk_text_iter_ends_line (const GtkTextIter   *iter)
 {
@@ -1617,13 +1664,14 @@ gtk_text_iter_ends_line (const GtkTextIter   *iter)
  * gtk_text_iter_is_end:
  * @iter: an iterator
  *
- * Returns %TRUE if @iter is the end iterator, i.e. one past the last
- * dereferenceable iterator in the buffer. gtk_text_iter_is_end() is
- * the most efficient way to check whether an iterator is the end
- * iterator.
+ * Returns %TRUE if @iter is the end iterator.
+ *
+ * This means it is one past the last dereferenceable iterator
+ * in the buffer. gtk_text_iter_is_end() is the most efficient
+ * way to check whether an iterator is the end iterator.
  *
  * Returns: whether @iter is the end iterator
- **/
+ */
 gboolean
 gtk_text_iter_is_end (const GtkTextIter *iter)
 {
@@ -1657,11 +1705,10 @@ gtk_text_iter_is_end (const GtkTextIter *iter)
  * gtk_text_iter_is_start:
  * @iter: an iterator
  *
- * Returns %TRUE if @iter is the first iterator in the buffer, that is
- * if @iter has a character offset of 0.
+ * Returns %TRUE if @iter is the first iterator in the buffer.
  *
  * Returns: whether @iter is the first in the buffer
- **/
+ */
 gboolean
 gtk_text_iter_is_start (const GtkTextIter *iter)
 {
@@ -1676,7 +1723,7 @@ gtk_text_iter_is_start (const GtkTextIter *iter)
  * including the paragraph delimiters.
  *
  * Returns: number of characters in the line
- **/
+ */
 int
 gtk_text_iter_get_chars_in_line (const GtkTextIter   *iter)
 {
@@ -1728,7 +1775,7 @@ gtk_text_iter_get_chars_in_line (const GtkTextIter   *iter)
  * including the paragraph delimiters.
  *
  * Returns: number of bytes in the line
- **/
+ */
 int
 gtk_text_iter_get_bytes_in_line (const GtkTextIter   *iter)
 {
@@ -2194,16 +2241,16 @@ _gtk_text_iter_backward_indexable_segment (GtkTextIter *iter)
  * gtk_text_iter_forward_char:
  * @iter: an iterator
  *
- * Moves @iter forward by one character offset. Note that images
- * embedded in the buffer occupy 1 character slot, so
- * gtk_text_iter_forward_char() may actually move onto an image instead
- * of a character, if you have images in your buffer.  If @iter is the
- * end iterator or one character before it, @iter will now point at
- * the end iterator, and gtk_text_iter_forward_char() returns %FALSE for
- * convenience when writing loops.
+ * Moves @iter forward by one character offset.
+ *
+ * Note that images embedded in the buffer occupy 1 character slot, so
+ * this function may actually move onto an image instead of a character,
+ * if you have images in your buffer. If @iter is the end iterator or
+ * one character before it, @iter will now point at the end iterator,
+ * and this function returns %FALSE for convenience when writing loops.
  *
  * Returns: whether @iter moved and is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_forward_char (GtkTextIter *iter)
 {
@@ -2226,13 +2273,14 @@ gtk_text_iter_forward_char (GtkTextIter *iter)
  * gtk_text_iter_backward_char:
  * @iter: an iterator
  *
- * Moves backward by one character offset. Returns %TRUE if movement
- * was possible; if @iter was the first in the buffer (character
- * offset 0), gtk_text_iter_backward_char() returns %FALSE for convenience when
- * writing loops.
+ * Moves backward by one character offset.
+ *
+ * Returns %TRUE if movement was possible; if @iter was the first
+ * in the buffer (character offset 0), this function returns %FALSE
+ * for convenience when writing loops.
  *
  * Returns: whether movement was possible
- **/
+ */
 gboolean
 gtk_text_iter_backward_char (GtkTextIter *iter)
 {
@@ -2263,15 +2311,18 @@ gtk_text_iter_backward_char (GtkTextIter *iter)
  * @iter: an iterator
  * @count: number of characters to move, may be negative
  *
- * Moves @count characters if possible (if @count would move past the
- * start or end of the buffer, moves to the start or end of the
- * buffer). The return value indicates whether the new position of
+ * Moves @count characters if possible.
+ *
+ * If @count would move past the start or end of the buffer,
+ * moves to the start or end of the buffer.
+ *
+ * The return value indicates whether the new position of
  * @iter is different from its original position, and dereferenceable
  * (the last iterator in the buffer is not dereferenceable). If @count
  * is 0, the function does nothing and returns %FALSE.
  *
  * Returns: whether @iter moved and is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_forward_chars (GtkTextIter *iter, int count)
 {
@@ -2334,16 +2385,18 @@ gtk_text_iter_forward_chars (GtkTextIter *iter, int count)
  * @iter: an iterator
  * @count: number of characters to move
  *
- * Moves @count characters backward, if possible (if @count would move
- * past the start or end of the buffer, moves to the start or end of
- * the buffer).  The return value indicates whether the iterator moved
+ * Moves @count characters backward, if possible.
+ *
+ * If @count would move past the start or end of the buffer, moves
+ * to the start or end of the buffer.
+ *
+ * The return value indicates whether the iterator moved
  * onto a dereferenceable position; if the iterator didn’t move, or
  * moved onto the end iterator, then %FALSE is returned. If @count is 0,
  * the function does nothing and returns %FALSE.
  *
  * Returns: whether @iter moved and is dereferenceable
- *
- **/
+ */
 gboolean
 gtk_text_iter_backward_chars (GtkTextIter *iter, int count)
 {
@@ -2449,13 +2502,15 @@ gtk_text_iter_backward_chars (GtkTextIter *iter, int count)
  * @iter: a #GtkTextIter
  * @count: number of chars to move
  *
- * Moves forward by @count text characters (paintables, widgets,
- * etc. do not count as characters for this). Equivalent to moving
- * through the results of gtk_text_iter_get_text(), rather than
- * gtk_text_iter_get_slice().
+ * Moves forward by @count text characters.
+ *
+ * Paintables, widgets, etc. do not count as characters for this.
+ *
+ * Equivalent to moving through the results of gtk_text_iter_get_text(),
+ * rather than gtk_text_iter_get_slice().
  *
  * Returns: whether @iter moved and is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_forward_text_chars  (GtkTextIter *iter,
                                    int          count)
@@ -2490,13 +2545,15 @@ gtk_text_iter_backward_text_chars (GtkTextIter *iter,
  * gtk_text_iter_forward_line:
  * @iter: an iterator
  *
- * Moves @iter to the start of the next line. If the iter is already on the
- * last line of the buffer, moves the iter to the end of the current line.
- * If after the operation, the iter is at the end of the buffer and not
+ * Moves @iter to the start of the next line.
+ *
+ * If the iter is already on the last line of the buffer,
+ * moves the iter to the end of the current line. If after
+ * the operation, the iter is at the end of the buffer and not
  * dereferenceable, returns %FALSE. Otherwise, returns %TRUE.
  *
  * Returns: whether @iter can be dereferenced
- **/
+ */
 gboolean
 gtk_text_iter_forward_line (GtkTextIter *iter)
 {
@@ -2539,16 +2596,18 @@ gtk_text_iter_forward_line (GtkTextIter *iter)
  * gtk_text_iter_backward_line:
  * @iter: an iterator
  *
- * Moves @iter to the start of the previous line. Returns %TRUE if
- * @iter could be moved; i.e. if @iter was at character offset 0, this
- * function returns %FALSE. Therefore if @iter was already on line 0,
- * but not at the start of the line, @iter is snapped to the start of
- * the line and the function returns %TRUE. (Note that this implies that
+ * Moves @iter to the start of the previous line.
+ *
+ * Returns %TRUE if @iter could be moved; i.e. if @iter was at
+ * character offset 0, this function returns %FALSE. Therefore,
+ * if @iter was already on line 0, but not at the start of the line,
+ * @iter is snapped to the start of the line and the function returns
+ * %TRUE. (Note that this implies that
  * in a loop calling this function, the line number may not change on
  * every iteration, if your first iteration is on line 0.)
  *
  * Returns: whether @iter moved
- **/
+ */
 gboolean
 gtk_text_iter_backward_line (GtkTextIter *iter)
 {
@@ -2615,19 +2674,22 @@ gtk_text_iter_backward_line (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_forward_lines:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of lines to move forward
  *
- * Moves @count lines forward, if possible (if @count would move
- * past the start or end of the buffer, moves to the start or end of
- * the buffer).  The return value indicates whether the iterator moved
+ * Moves @count lines forward, if possible.
+ *
+ * If @count would move past the start or end of the buffer, moves to
+ * the start or end of the buffer.
+ *
+ * The return value indicates whether the iterator moved
  * onto a dereferenceable position; if the iterator didn’t move, or
  * moved onto the end iterator, then %FALSE is returned. If @count is 0,
  * the function does nothing and returns %FALSE. If @count is negative,
  * moves backward by 0 - @count lines.
  *
  * Returns: whether @iter moved and is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_forward_lines (GtkTextIter *iter, int count)
 {
@@ -2666,19 +2728,22 @@ gtk_text_iter_forward_lines (GtkTextIter *iter, int count)
 
 /**
  * gtk_text_iter_backward_lines:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of lines to move backward
  *
- * Moves @count lines backward, if possible (if @count would move
- * past the start or end of the buffer, moves to the start or end of
- * the buffer).  The return value indicates whether the iterator moved
+ * Moves @count lines backward, if possible.
+ *
+ * If @count would move past the start or end of the buffer, moves to
+ * the start or end of the buffer.
+ *
+ * The return value indicates whether the iterator moved
  * onto a dereferenceable position; if the iterator didn’t move, or
  * moved onto the end iterator, then %FALSE is returned. If @count is 0,
  * the function does nothing and returns %FALSE. If @count is negative,
  * moves forward by 0 - @count lines.
  *
  * Returns: whether @iter moved and is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_backward_lines (GtkTextIter *iter, int count)
 {
@@ -2708,13 +2773,15 @@ gtk_text_iter_backward_lines (GtkTextIter *iter, int count)
  * gtk_text_iter_forward_visible_line:
  * @iter: an iterator
  *
- * Moves @iter to the start of the next visible line. Returns %TRUE if there
+ * Moves @iter to the start of the next visible line.
+ *
+ * Returns %TRUE if there
  * was a next line to move to, and %FALSE if @iter was simply moved to
  * the end of the buffer and is now not dereferenceable, or if @iter was
  * already at the end of the buffer.
  *
  * Returns: whether @iter can be dereferenced
- **/
+ */
 gboolean
 gtk_text_iter_forward_visible_line (GtkTextIter *iter)
 {
@@ -2743,7 +2810,9 @@ gtk_text_iter_forward_visible_line (GtkTextIter *iter)
  * gtk_text_iter_backward_visible_line:
  * @iter: an iterator
  *
- * Moves @iter to the start of the previous visible line. Returns %TRUE if
+ * Moves @iter to the start of the previous visible line.
+ *
+ * Returns %TRUE if
  * @iter could be moved; i.e. if @iter was at character offset 0, this
  * function returns %FALSE. Therefore if @iter was already on line 0,
  * but not at the start of the line, @iter is snapped to the start of
@@ -2752,7 +2821,7 @@ gtk_text_iter_forward_visible_line (GtkTextIter *iter)
  * every iteration, if your first iteration is on line 0.)
  *
  * Returns: whether @iter moved
- **/
+ */
 gboolean
 gtk_text_iter_backward_visible_line (GtkTextIter *iter)
 {
@@ -2779,19 +2848,22 @@ gtk_text_iter_backward_visible_line (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_forward_visible_lines:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of lines to move forward
  *
- * Moves @count visible lines forward, if possible (if @count would move
- * past the start or end of the buffer, moves to the start or end of
- * the buffer).  The return value indicates whether the iterator moved
+ * Moves @count visible lines forward, if possible.
+ *
+ * If @count would move past the start or end of the buffer, moves to
+ * the start or end of the buffer.
+ *
+ * The return value indicates whether the iterator moved
  * onto a dereferenceable position; if the iterator didn’t move, or
  * moved onto the end iterator, then %FALSE is returned. If @count is 0,
  * the function does nothing and returns %FALSE. If @count is negative,
  * moves backward by 0 - @count lines.
  *
  * Returns: whether @iter moved and is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_forward_visible_lines (GtkTextIter *iter,
                                      int          count)
@@ -2817,19 +2889,22 @@ gtk_text_iter_forward_visible_lines (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_backward_visible_lines:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of lines to move backward
  *
- * Moves @count visible lines backward, if possible (if @count would move
- * past the start or end of the buffer, moves to the start or end of
- * the buffer).  The return value indicates whether the iterator moved
+ * Moves @count visible lines backward, if possible.
+ *
+ * If @count would move past the start or end of the buffer, moves to
+ * the start or end of the buffer.
+ *
+ * The return value indicates whether the iterator moved
  * onto a dereferenceable position; if the iterator didn’t move, or
  * moved onto the end iterator, then %FALSE is returned. If @count is 0,
  * the function does nothing and returns %FALSE. If @count is negative,
  * moves forward by 0 - @count lines.
  *
  * Returns: whether @iter moved and is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_backward_visible_lines (GtkTextIter *iter,
                                       int          count)
@@ -3208,16 +3283,18 @@ move_multiple_steps (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_forward_word_end:
- * @iter: a #GtkTextIter
- * 
- * Moves forward to the next word end. (If @iter is currently on a
- * word end, moves forward to the next one after that.) Word breaks
- * are determined by Pango and should be correct for nearly any
- * language (if not, the correct fix would be to the Pango word break
- * algorithms).
- * 
- * Returns: %TRUE if @iter moved and is not the end iterator 
- **/
+ * @iter: a `GtkTextIter`
+ *
+ * Moves forward to the next word end.
+ *
+ * If @iter is currently on a word end, moves forward to the
+ * next one after that.
+ *
+ * Word breaks are determined by Pango and should be correct
+ * for nearly any language.
+ *
+ * Returns: %TRUE if @iter moved and is not the end iterator
+ */
 gboolean
 gtk_text_iter_forward_word_end (GtkTextIter *iter)
 {
@@ -3226,16 +3303,18 @@ gtk_text_iter_forward_word_end (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_backward_word_start:
- * @iter: a #GtkTextIter
- * 
- * Moves backward to the previous word start. (If @iter is currently on a
- * word start, moves backward to the next one after that.) Word breaks
- * are determined by Pango and should be correct for nearly any
- * language (if not, the correct fix would be to the Pango word break
- * algorithms).
- * 
- * Returns: %TRUE if @iter moved and is not the end iterator 
- **/
+ * @iter: a `GtkTextIter`
+ *
+ * Moves backward to the previous word start.
+ *
+ * If @iter is currently on a word start, moves backward to the
+ * next one after that.
+ *
+ * Word breaks are determined by Pango and should be correct
+ * for nearly any language
+ *
+ * Returns: %TRUE if @iter moved and is not the end iterator
+ */
 gboolean
 gtk_text_iter_backward_word_start (GtkTextIter *iter)
 {
@@ -3248,13 +3327,13 @@ gtk_text_iter_backward_word_start (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_forward_word_ends:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of times to move
- * 
+ *
  * Calls gtk_text_iter_forward_word_end() up to @count times.
  *
- * Returns: %TRUE if @iter moved and is not the end iterator 
- **/
+ * Returns: %TRUE if @iter moved and is not the end iterator
+ */
 gboolean
 gtk_text_iter_forward_word_ends (GtkTextIter      *iter,
                                  int               count)
@@ -3266,13 +3345,13 @@ gtk_text_iter_forward_word_ends (GtkTextIter      *iter,
 
 /**
  * gtk_text_iter_backward_word_starts:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of times to move
- * 
+ *
  * Calls gtk_text_iter_backward_word_start() up to @count times.
  *
- * Returns: %TRUE if @iter moved and is not the end iterator 
- **/
+ * Returns: %TRUE if @iter moved and is not the end iterator
+ */
 gboolean
 gtk_text_iter_backward_word_starts (GtkTextIter      *iter,
                                     int                count)
@@ -3284,16 +3363,18 @@ gtk_text_iter_backward_word_starts (GtkTextIter      *iter,
 
 /**
  * gtk_text_iter_forward_visible_word_end:
- * @iter: a #GtkTextIter
- * 
- * Moves forward to the next visible word end. (If @iter is currently on a
- * word end, moves forward to the next one after that.) Word breaks
- * are determined by Pango and should be correct for nearly any
- * language (if not, the correct fix would be to the Pango word break
- * algorithms).
- * 
- * Returns: %TRUE if @iter moved and is not the end iterator 
- **/
+ * @iter: a `GtkTextIter`
+ *
+ * Moves forward to the next visible word end.
+ *
+ * If @iter is currently on a word end, moves forward to the
+ * next one after that.
+ *
+ * Word breaks are determined by Pango and should be correct
+ * for nearly any language
+ *
+ * Returns: %TRUE if @iter moved and is not the end iterator
+ */
 gboolean
 gtk_text_iter_forward_visible_word_end (GtkTextIter *iter)
 {
@@ -3302,16 +3383,18 @@ gtk_text_iter_forward_visible_word_end (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_backward_visible_word_start:
- * @iter: a #GtkTextIter
- * 
- * Moves backward to the previous visible word start. (If @iter is currently 
- * on a word start, moves backward to the next one after that.) Word breaks
- * are determined by Pango and should be correct for nearly any
- * language (if not, the correct fix would be to the Pango word break
- * algorithms).
- * 
- * Returns: %TRUE if @iter moved and is not the end iterator 
- **/
+ * @iter: a `GtkTextIter`
+ *
+ * Moves backward to the previous visible word start.
+ *
+ * If @iter is currently on a word start, moves backward to the
+ * next one after that.
+ *
+ * Word breaks are determined by Pango and should be correct
+ * for nearly any language.
+ *
+ * Returns: %TRUE if @iter moved and is not the end iterator
+ */
 gboolean
 gtk_text_iter_backward_visible_word_start (GtkTextIter      *iter)
 {
@@ -3320,13 +3403,13 @@ gtk_text_iter_backward_visible_word_start (GtkTextIter      *iter)
 
 /**
  * gtk_text_iter_forward_visible_word_ends:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of times to move
- * 
+ *
  * Calls gtk_text_iter_forward_visible_word_end() up to @count times.
  *
- * Returns: %TRUE if @iter moved and is not the end iterator 
- **/
+ * Returns: %TRUE if @iter moved and is not the end iterator
+ */
 gboolean
 gtk_text_iter_forward_visible_word_ends (GtkTextIter *iter,
 					 int          count)
@@ -3338,13 +3421,13 @@ gtk_text_iter_forward_visible_word_ends (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_backward_visible_word_starts:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of times to move
- * 
+ *
  * Calls gtk_text_iter_backward_visible_word_start() up to @count times.
  *
- * Returns: %TRUE if @iter moved and is not the end iterator 
- **/
+ * Returns: %TRUE if @iter moved and is not the end iterator
+ */
 gboolean
 gtk_text_iter_backward_visible_word_starts (GtkTextIter *iter,
 					    int          count)
@@ -3356,15 +3439,15 @@ gtk_text_iter_backward_visible_word_starts (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_starts_word:
- * @iter: a #GtkTextIter
- * 
- * Determines whether @iter begins a natural-language word.  Word
- * breaks are determined by Pango and should be correct for nearly any
- * language (if not, the correct fix would be to the Pango word break
- * algorithms).
+ * @iter: a `GtkTextIter`
+ *
+ * Determines whether @iter begins a natural-language word.
+ *
+ * Word breaks are determined by Pango and should be correct
+ * for nearly any language.
  *
  * Returns: %TRUE if @iter is at the start of a word
- **/
+ */
 gboolean
 gtk_text_iter_starts_word (const GtkTextIter *iter)
 {
@@ -3373,15 +3456,15 @@ gtk_text_iter_starts_word (const GtkTextIter *iter)
 
 /**
  * gtk_text_iter_ends_word:
- * @iter: a #GtkTextIter
- * 
- * Determines whether @iter ends a natural-language word.  Word breaks
- * are determined by Pango and should be correct for nearly any
- * language (if not, the correct fix would be to the Pango word break
- * algorithms).
+ * @iter: a `GtkTextIter`
+ *
+ * Determines whether @iter ends a natural-language word.
+ *
+ * Word breaks are determined by Pango and should be correct
+ * for nearly any language.
  *
  * Returns: %TRUE if @iter is at the end of a word
- **/
+ */
 gboolean
 gtk_text_iter_ends_word (const GtkTextIter *iter)
 {
@@ -3390,18 +3473,20 @@ gtk_text_iter_ends_word (const GtkTextIter *iter)
 
 /**
  * gtk_text_iter_inside_word:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  *
  * Determines whether the character pointed by @iter is part of a
- * natural-language word (as opposed to say inside some whitespace).  Word
- * breaks are determined by Pango and should be correct for nearly any language
- * (if not, the correct fix would be to the Pango word break algorithms).
+ * natural-language word (as opposed to say inside some whitespace).
  *
- * Note that if gtk_text_iter_starts_word() returns %TRUE, then this function
- * returns %TRUE too, since @iter points to the first character of the word.
+ * Word breaks are determined by Pango and should be correct
+ * for nearly any language.
+ *
+ * Note that if [method@Gtk.TextIter.starts_word] returns %TRUE,
+ * then this function returns %TRUE too, since @iter points to
+ * the first character of the word.
  *
  * Returns: %TRUE if @iter is inside a word
- **/
+ */
 gboolean
 gtk_text_iter_inside_word (const GtkTextIter *iter)
 {
@@ -3410,15 +3495,15 @@ gtk_text_iter_inside_word (const GtkTextIter *iter)
 
 /**
  * gtk_text_iter_starts_sentence:
- * @iter: a #GtkTextIter
- * 
- * Determines whether @iter begins a sentence.  Sentence boundaries are
- * determined by Pango and should be correct for nearly any language
- * (if not, the correct fix would be to the Pango text boundary
- * algorithms).
- * 
+ * @iter: a `GtkTextIter`
+ *
+ * Determines whether @iter begins a sentence.
+ *
+ * Sentence boundaries are determined by Pango and
+ * should be correct for nearly any language.
+ *
  * Returns: %TRUE if @iter is at the start of a sentence.
- **/
+ */
 gboolean
 gtk_text_iter_starts_sentence (const GtkTextIter *iter)
 {
@@ -3427,15 +3512,15 @@ gtk_text_iter_starts_sentence (const GtkTextIter *iter)
 
 /**
  * gtk_text_iter_ends_sentence:
- * @iter: a #GtkTextIter
- * 
- * Determines whether @iter ends a sentence.  Sentence boundaries are
- * determined by Pango and should be correct for nearly any language
- * (if not, the correct fix would be to the Pango text boundary
- * algorithms).
- * 
+ * @iter: a `GtkTextIter`
+ *
+ * Determines whether @iter ends a sentence.
+ *
+ * Sentence boundaries are determined by Pango and should
+ * be correct for nearly any language.
+ *
  * Returns: %TRUE if @iter is at the end of a sentence.
- **/
+ */
 gboolean
 gtk_text_iter_ends_sentence (const GtkTextIter *iter)
 {
@@ -3444,16 +3529,17 @@ gtk_text_iter_ends_sentence (const GtkTextIter *iter)
 
 /**
  * gtk_text_iter_inside_sentence:
- * @iter: a #GtkTextIter
- * 
+ * @iter: a `GtkTextIter`
+ *
  * Determines whether @iter is inside a sentence (as opposed to in
  * between two sentences, e.g. after a period and before the first
- * letter of the next sentence).  Sentence boundaries are determined
- * by Pango and should be correct for nearly any language (if not, the
- * correct fix would be to the Pango text boundary algorithms).
- * 
+ * letter of the next sentence).
+ *
+ * Sentence boundaries are determined by Pango and should be correct
+ * for nearly any language.
+ *
  * Returns: %TRUE if @iter is inside a sentence.
- **/
+ */
 gboolean
 gtk_text_iter_inside_sentence (const GtkTextIter *iter)
 {
@@ -3462,16 +3548,18 @@ gtk_text_iter_inside_sentence (const GtkTextIter *iter)
 
 /**
  * gtk_text_iter_forward_sentence_end:
- * @iter: a #GtkTextIter
- * 
- * Moves forward to the next sentence end. (If @iter is at the end of
- * a sentence, moves to the next end of sentence.)  Sentence
- * boundaries are determined by Pango and should be correct for nearly
- * any language (if not, the correct fix would be to the Pango text
- * boundary algorithms).
- * 
+ * @iter: a `GtkTextIter`
+ *
+ * Moves forward to the next sentence end.
+ *
+ * If @iter is at the end of a sentence, moves to the next
+ * end of sentence.
+ *
+ * Sentence boundaries are determined by Pango and should
+ * be correct for nearly any language.
+ *
  * Returns: %TRUE if @iter moved and is not the end iterator
- **/
+ */
 gboolean
 gtk_text_iter_forward_sentence_end (GtkTextIter *iter)
 {
@@ -3480,16 +3568,18 @@ gtk_text_iter_forward_sentence_end (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_backward_sentence_start:
- * @iter: a #GtkTextIter
- * 
- * Moves backward to the previous sentence start; if @iter is already at
- * the start of a sentence, moves backward to the next one.  Sentence
- * boundaries are determined by Pango and should be correct for nearly
- * any language (if not, the correct fix would be to the Pango text
- * boundary algorithms).
- * 
+ * @iter: a `GtkTextIter`
+ *
+ * Moves backward to the previous sentence start.
+ *
+ * If @iter is already at the start of a sentence, moves backward
+ * to the next one.
+ *
+ * Sentence boundaries are determined by Pango and should
+ * be correct for nearly any language.
+ *
  * Returns: %TRUE if @iter moved and is not the end iterator
- **/
+ */
 gboolean
 gtk_text_iter_backward_sentence_start (GtkTextIter *iter)
 {
@@ -3501,15 +3591,15 @@ gtk_text_iter_backward_sentence_start (GtkTextIter *iter)
  */
 /**
  * gtk_text_iter_forward_sentence_ends:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of sentences to move
- * 
- * Calls gtk_text_iter_forward_sentence_end() @count times (or until
- * gtk_text_iter_forward_sentence_end() returns %FALSE). If @count is
- * negative, moves backward instead of forward.
- * 
+ *
+ * Calls gtk_text_iter_forward_sentence_end() @count times.
+ *
+ * If @count is negative, moves backward instead of forward.
+ *
  * Returns: %TRUE if @iter moved and is not the end iterator
- **/
+ */
 gboolean
 gtk_text_iter_forward_sentence_ends (GtkTextIter      *iter,
                                      int               count)
@@ -3521,15 +3611,15 @@ gtk_text_iter_forward_sentence_ends (GtkTextIter      *iter,
 
 /**
  * gtk_text_iter_backward_sentence_starts:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of sentences to move
- * 
- * Calls gtk_text_iter_backward_sentence_start() up to @count times,
- * or until it returns %FALSE. If @count is negative, moves forward
- * instead of backward.
- * 
+ *
+ * Calls gtk_text_iter_backward_sentence_start() up to @count times.
+ *
+ * If @count is negative, moves forward instead of backward.
+ *
  * Returns: %TRUE if @iter moved and is not the end iterator
- **/
+ */
 gboolean
 gtk_text_iter_backward_sentence_starts (GtkTextIter *iter,
                                         int          count)
@@ -3598,21 +3688,26 @@ is_cursor_pos_func (const PangoLogAttr *attrs,
 
 /**
  * gtk_text_iter_forward_cursor_position:
- * @iter: a #GtkTextIter
- * 
- * Moves @iter forward by a single cursor position. Cursor positions
- * are (unsurprisingly) positions where the cursor can appear. Perhaps
- * surprisingly, there may not be a cursor position between all
- * characters. The most common example for European languages would be
- * a carriage return/newline sequence. For some Unicode characters,
- * the equivalent of say the letter “a” with an accent mark will be
- * represented as two characters, first the letter then a "combining
- * mark" that causes the accent to be rendered; so the cursor can’t go
- * between those two characters. See also the #PangoLogAttr-struct and
- * pango_break() function.
- * 
+ * @iter: a `GtkTextIter`
+ *
+ * Moves @iter forward by a single cursor position.
+ *
+ * Cursor positions are (unsurprisingly) positions where the
+ * cursor can appear. Perhaps surprisingly, there may not be
+ * a cursor position between all characters. The most common
+ * example for European languages would be a carriage return/newline
+ * sequence.
+ *
+ * For some Unicode characters, the equivalent of say the letter “a”
+ * with an accent mark will be represented as two characters, first
+ * the letter then a "combining mark" that causes the accent to be
+ * rendered; so the cursor can’t go between those two characters.
+ *
+ * See also the [struct@Pango.LogAttr] struct and the [func@Pango.break]
+ * function.
+ *
  * Returns: %TRUE if we moved and the new position is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_forward_cursor_position (GtkTextIter *iter)
 {
@@ -3621,12 +3716,12 @@ gtk_text_iter_forward_cursor_position (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_backward_cursor_position:
- * @iter: a #GtkTextIter
- * 
+ * @iter: a `GtkTextIter`
+ *
  * Like gtk_text_iter_forward_cursor_position(), but moves backward.
- * 
+ *
  * Returns: %TRUE if we moved
- **/
+ */
 gboolean
 gtk_text_iter_backward_cursor_position (GtkTextIter *iter)
 {
@@ -3635,14 +3730,15 @@ gtk_text_iter_backward_cursor_position (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_forward_cursor_positions:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of positions to move
- * 
- * Moves up to @count cursor positions. See
- * gtk_text_iter_forward_cursor_position() for details.
- * 
+ *
+ * Moves up to @count cursor positions.
+ *
+ * See [method@Gtk.TextIter.forward_cursor_position] for details.
+ *
  * Returns: %TRUE if we moved and the new position is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_forward_cursor_positions (GtkTextIter *iter,
                                         int          count)
@@ -3654,14 +3750,15 @@ gtk_text_iter_forward_cursor_positions (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_backward_cursor_positions:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of positions to move
  *
- * Moves up to @count cursor positions. See
- * gtk_text_iter_forward_cursor_position() for details.
- * 
+ * Moves up to @count cursor positions.
+ *
+ * See [method@Gtk.TextIter.forward_cursor_position] for details.
+ *
  * Returns: %TRUE if we moved and the new position is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_backward_cursor_positions (GtkTextIter *iter,
                                          int          count)
@@ -3673,13 +3770,14 @@ gtk_text_iter_backward_cursor_positions (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_forward_visible_cursor_position:
- * @iter: a #GtkTextIter
- * 
- * Moves @iter forward to the next visible cursor position. See 
- * gtk_text_iter_forward_cursor_position() for details.
- * 
+ * @iter: a `GtkTextIter`
+ *
+ * Moves @iter forward to the next visible cursor position.
+ *
+ * See [method@Gtk.TextIter.forward_cursor_position] for details.
+ *
  * Returns: %TRUE if we moved and the new position is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_forward_visible_cursor_position (GtkTextIter *iter)
 {
@@ -3688,13 +3786,14 @@ gtk_text_iter_forward_visible_cursor_position (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_backward_visible_cursor_position:
- * @iter: a #GtkTextIter
- * 
- * Moves @iter forward to the previous visible cursor position. See 
- * gtk_text_iter_backward_cursor_position() for details.
- * 
+ * @iter: a `GtkTextIter`
+ *
+ * Moves @iter forward to the previous visible cursor position.
+ *
+ * See [method@Gtk.TextIter.backward_cursor_position] for details.
+ *
  * Returns: %TRUE if we moved and the new position is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_backward_visible_cursor_position (GtkTextIter *iter)
 {
@@ -3703,14 +3802,15 @@ gtk_text_iter_backward_visible_cursor_position (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_forward_visible_cursor_positions:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of positions to move
- * 
- * Moves up to @count visible cursor positions. See
- * gtk_text_iter_forward_cursor_position() for details.
- * 
+ *
+ * Moves up to @count visible cursor positions.
+ *
+ * See [method@Gtk.TextIter.forward_cursor_position] for details.
+ *
  * Returns: %TRUE if we moved and the new position is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_forward_visible_cursor_positions (GtkTextIter *iter,
 						int          count)
@@ -3722,14 +3822,15 @@ gtk_text_iter_forward_visible_cursor_positions (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_backward_visible_cursor_positions:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @count: number of positions to move
  *
- * Moves up to @count visible cursor positions. See
- * gtk_text_iter_backward_cursor_position() for details.
- * 
+ * Moves up to @count visible cursor positions.
+ *
+ * See [method@Gtk.TextIter.backward_cursor_position] for details.
+ *
  * Returns: %TRUE if we moved and the new position is dereferenceable
- **/
+ */
 gboolean
 gtk_text_iter_backward_visible_cursor_positions (GtkTextIter *iter,
 						 int          count)
@@ -3741,13 +3842,16 @@ gtk_text_iter_backward_visible_cursor_positions (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_is_cursor_position:
- * @iter: a #GtkTextIter
- * 
- * See gtk_text_iter_forward_cursor_position() or #PangoLogAttr or
- * pango_break() for details on what a cursor position is.
- * 
+ * @iter: a `GtkTextIter`
+ *
+ * Determine if @iter is at a cursor position.
+ *
+ * See [method@Gtk.TextIter.forward_cursor_position] or
+ * [struct@Pango.LogAttr] or [func@Pango.break] for details
+ * on what a cursor position is.
+ *
  * Returns: %TRUE if the cursor can be placed at @iter
- **/
+ */
 gboolean
 gtk_text_iter_is_cursor_position (const GtkTextIter *iter)
 {
@@ -3756,17 +3860,16 @@ gtk_text_iter_is_cursor_position (const GtkTextIter *iter)
 
 /**
  * gtk_text_iter_set_line_offset:
- * @iter: a #GtkTextIter 
+ * @iter: a `GtkTextIter`
  * @char_on_line: a character offset relative to the start of @iter’s current line
- * 
- * Moves @iter within a line, to a new character
- * (not byte) offset. The given character offset must be less than or
- * equal to the number of characters in the line; if equal, @iter
- * moves to the start of the next line. See
- * gtk_text_iter_set_line_index() if you have a byte index rather than
- * a character offset.
  *
- **/
+ * Moves @iter within a line, to a new character (not byte) offset.
+ *
+ * The given character offset must be less than or equal to the number
+ * of characters in the line; if equal, @iter moves to the start of the
+ * next line. See [method@Gtk.TextIter.set_line_index] if you have a byte
+ * index rather than a character offset.
+ */
 void
 gtk_text_iter_set_line_offset (GtkTextIter *iter,
                                int          char_on_line)
@@ -3797,15 +3900,14 @@ gtk_text_iter_set_line_offset (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_set_line_index:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @byte_on_line: a byte index relative to the start of @iter’s current line
  *
  * Same as gtk_text_iter_set_line_offset(), but works with a
  * byte index. The given byte index must be at
  * the start of a character, it can’t be in the middle of a UTF-8
  * encoded character.
- * 
- **/
+ */
 void
 gtk_text_iter_set_line_index (GtkTextIter *iter,
                               int          byte_on_line)
@@ -3844,13 +3946,13 @@ gtk_text_iter_set_line_index (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_set_visible_line_offset:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @char_on_line: a character offset
- * 
+ *
  * Like gtk_text_iter_set_line_offset(), but the offset is in visible
  * characters, i.e. text with a tag making it invisible is not
  * counted in the offset.
- **/
+ */
 void
 gtk_text_iter_set_visible_line_offset (GtkTextIter *iter,
                                        int          char_on_line)
@@ -3885,13 +3987,13 @@ gtk_text_iter_set_visible_line_offset (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_set_visible_line_index:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @byte_on_line: a byte index
- * 
+ *
  * Like gtk_text_iter_set_line_index(), but the index is in visible
  * bytes, i.e. text with a tag making it invisible is not counted
  * in the index.
- **/
+ */
 void
 gtk_text_iter_set_visible_line_index (GtkTextIter *iter,
                                       int          byte_on_line)
@@ -3945,14 +4047,14 @@ gtk_text_iter_set_visible_line_index (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_set_line:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @line_number: line number (counted from 0)
  *
- * Moves iterator @iter to the start of the line @line_number.  If
- * @line_number is negative or larger than the number of lines in the
- * buffer, moves @iter to the start of the last line in the buffer.
- * 
- **/
+ * Moves iterator @iter to the start of the line @line_number.
+ *
+ * If @line_number is negative or larger than the number of lines
+ * in the buffer, moves @iter to the start of the last line in the buffer.
+ */
 void
 gtk_text_iter_set_line (GtkTextIter *iter,
                         int          line_number)
@@ -3982,12 +4084,14 @@ gtk_text_iter_set_line (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_set_offset:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @char_offset: a character number
  *
- * Sets @iter to point to @char_offset. @char_offset counts from the start
+ * Sets @iter to point to @char_offset.
+ *
+ * @char_offset counts from the start
  * of the entire text buffer, starting with 0.
- **/
+ */
 void
 gtk_text_iter_set_offset (GtkTextIter *iter,
                           int          char_offset)
@@ -4025,12 +4129,14 @@ gtk_text_iter_set_offset (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_forward_to_end:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  *
- * Moves @iter forward to the “end iterator,” which points one past the last
- * valid character in the buffer. gtk_text_iter_get_char() called on the
- * end iterator returns 0, which is convenient for writing loops.
- **/
+ * Moves @iter forward to the “end iterator”, which points
+ * one past the last valid character in the buffer.
+ *
+ * gtk_text_iter_get_char() called on the end iterator
+ * returns 0, which is convenient for writing loops.
+ */
 void
 gtk_text_iter_forward_to_end  (GtkTextIter *iter)
 {
@@ -4081,19 +4187,22 @@ find_paragraph_delimiter_for_line (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_forward_to_line_end:
- * @iter: a #GtkTextIter
- * 
- * Moves the iterator to point to the paragraph delimiter characters,
- * which will be either a newline, a carriage return, a carriage
- * return/newline in sequence, or the Unicode paragraph separator
- * character. If the iterator is already at the paragraph delimiter
+ * @iter: a `GtkTextIter`
+ *
+ * Moves the iterator to point to the paragraph delimiter characters.
+ *
+ * The possible characters are either a newline, a carriage return,
+ * a carriage return/newline in sequence, or the Unicode paragraph
+ * separator character.
+ *
+ * If the iterator is already at the paragraph delimiter
  * characters, moves to the paragraph delimiter characters for the
  * next line. If @iter is on the last line in the buffer, which does
  * not end in paragraph delimiters, moves to the end iterator (end of
  * the last line), and returns %FALSE.
- * 
+ *
  * Returns: %TRUE if we moved and the new location is not the end iterator
- **/
+ */
 gboolean
 gtk_text_iter_forward_to_line_end (GtkTextIter *iter)
 {
@@ -4131,19 +4240,21 @@ gtk_text_iter_forward_to_line_end (GtkTextIter *iter)
 
 /**
  * gtk_text_iter_forward_to_tag_toggle:
- * @iter: a #GtkTextIter
- * @tag: (allow-none): a #GtkTextTag, or %NULL
+ * @iter: a `GtkTextIter`
+ * @tag: (allow-none): a `GtkTextTag`, or %NULL
  *
  * Moves forward to the next toggle (on or off) of the
- * #GtkTextTag @tag, or to the next toggle of any tag if
- * @tag is %NULL. If no matching tag toggles are found,
+ * @tag, or to the next toggle of any tag if
+ * @tag is %NULL.
+ *
+ * If no matching tag toggles are found,
  * returns %FALSE, otherwise %TRUE. Does not return toggles
  * located at @iter, only toggles after @iter. Sets @iter to
  * the location of the toggle, or to the end of the buffer
  * if no toggle is found.
  *
  * Returns: whether we found a tag toggle after @iter
- **/
+ */
 gboolean
 gtk_text_iter_forward_to_tag_toggle (GtkTextIter *iter,
                                      GtkTextTag  *tag)
@@ -4216,19 +4327,21 @@ gtk_text_iter_forward_to_tag_toggle (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_backward_to_tag_toggle:
- * @iter: a #GtkTextIter
- * @tag: (allow-none): a #GtkTextTag, or %NULL
+ * @iter: a `GtkTextIter`
+ * @tag: (allow-none): a `GtkTextTag`, or %NULL
  *
  * Moves backward to the next toggle (on or off) of the
- * #GtkTextTag @tag, or to the next toggle of any tag if
- * @tag is %NULL. If no matching tag toggles are found,
+ * @tag, or to the next toggle of any tag if
+ * @tag is %NULL.
+ *
+ * If no matching tag toggles are found,
  * returns %FALSE, otherwise %TRUE. Does not return toggles
  * located at @iter, only toggles before @iter. Sets @iter
  * to the location of the toggle, or the start of the buffer
  * if no toggle is found.
  *
  * Returns: whether we found a tag toggle before @iter
- **/
+ */
 gboolean
 gtk_text_iter_backward_to_tag_toggle (GtkTextIter *iter,
                                       GtkTextTag  *tag)
@@ -4329,18 +4442,19 @@ matches_pred (GtkTextIter *iter,
 
 /**
  * gtk_text_iter_forward_find_char:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @pred: (scope call): a function to be called on each character
  * @user_data: (closure): user data for @pred
- * @limit: (allow-none): search limit, or %NULL for none 
- * 
- * Advances @iter, calling @pred on each character. If
- * @pred returns %TRUE, returns %TRUE and stops scanning.
+ * @limit: (allow-none): search limit, or %NULL for none
+ *
+ * Advances @iter, calling @pred on each character.
+ *
+ * If @pred returns %TRUE, returns %TRUE and stops scanning.
  * If @pred never returns %TRUE, @iter is set to @limit if
  * @limit is non-%NULL, otherwise to the end iterator.
- * 
+ *
  * Returns: whether a match was found
- **/
+ */
 gboolean
 gtk_text_iter_forward_find_char (GtkTextIter         *iter,
                                  GtkTextCharPredicate pred,
@@ -4367,15 +4481,16 @@ gtk_text_iter_forward_find_char (GtkTextIter         *iter,
 
 /**
  * gtk_text_iter_backward_find_char:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @pred: (scope call): function to be called on each character
  * @user_data: (closure): user data for @pred
  * @limit: (allow-none): search limit, or %NULL for none
- * 
- * Same as gtk_text_iter_forward_find_char(), but goes backward from @iter.
- * 
+ *
+ * Same as gtk_text_iter_forward_find_char(),
+ * but goes backward from @iter.
+ *
  * Returns: whether a match was found
- **/
+ */
 gboolean
 gtk_text_iter_backward_find_char (GtkTextIter         *iter,
                                   GtkTextCharPredicate pred,
@@ -4853,18 +4968,19 @@ strbreakup (const char *string,
  * @match_end: (out caller-allocates) (allow-none): return location for end of match, or %NULL
  * @limit: (allow-none): location of last possible @match_end, or %NULL for the end of the buffer
  *
- * Searches forward for @str. Any match is returned by setting
- * @match_start to the first character of the match and @match_end to the
- * first character after the match. The search will not continue past
- * @limit. Note that a search is a linear or O(n) operation, so you
- * may wish to use @limit to avoid locking up your UI on large
- * buffers.
+ * Searches forward for @str.
  *
- * @match_start will never be set to a #GtkTextIter located before @iter, even if
- * there is a possible @match_end after or at @iter.
+ * Any match is returned by setting @match_start to the first character
+ * of the match and @match_end to the first character after the match.
+ * The search will not continue past @limit. Note that a search is a
+ * linear or O(n) operation, so you may wish to use @limit to avoid
+ * locking up your UI on large buffers.
+ *
+ * @match_start will never be set to a `GtkTextIter` located before @iter,
+ * even if there is a possible @match_end after or at @iter.
  *
  * Returns: whether a match was found
- **/
+ */
 gboolean
 gtk_text_iter_forward_search (const GtkTextIter *iter,
                               const char        *str,
@@ -5175,7 +5291,7 @@ lines_window_free (LinesWindow *win)
 
 /**
  * gtk_text_iter_backward_search:
- * @iter: a #GtkTextIter where the search begins
+ * @iter: a `GtkTextIter` where the search begins
  * @str: search string
  * @flags: bitmask of flags affecting the search
  * @match_start: (out caller-allocates) (allow-none): return location for start of match, or %NULL
@@ -5184,11 +5300,11 @@ lines_window_free (LinesWindow *win)
  *
  * Same as gtk_text_iter_forward_search(), but moves backward.
  *
- * @match_end will never be set to a #GtkTextIter located after @iter, even if
- * there is a possible @match_start before or at @iter.
+ * @match_end will never be set to a `GtkTextIter` located after @iter,
+ * even if there is a possible @match_start before or at @iter.
  *
  * Returns: whether a match was found
- **/
+ */
 gboolean
 gtk_text_iter_backward_search (const GtkTextIter *iter,
                                const char        *str,
@@ -5324,14 +5440,16 @@ gtk_text_iter_backward_search (const GtkTextIter *iter,
 
 /**
  * gtk_text_iter_equal:
- * @lhs: a #GtkTextIter
- * @rhs: another #GtkTextIter
+ * @lhs: a `GtkTextIter`
+ * @rhs: another `GtkTextIter`
  * 
  * Tests whether two iterators are equal, using the fastest possible
- * mechanism. This function is very fast; you can expect it to perform
- * better than e.g. getting the character offset for each iterator and
- * comparing the offsets yourself. Also, it’s a bit faster than
- * gtk_text_iter_compare().
+ * mechanism.
+ *
+ * This function is very fast; you can expect it to perform
+ * better than e.g. getting the character offset for each
+ * iterator and comparing the offsets yourself. Also, it’s a
+ * bit faster than [method@Gtk.TextIter.compare].
  * 
  * Returns: %TRUE if the iterators point to the same place in the buffer
  **/
@@ -5384,16 +5502,17 @@ _gtk_text_iter_same_line (const GtkTextIter *lhs,
 
 /**
  * gtk_text_iter_compare:
- * @lhs: a #GtkTextIter
- * @rhs: another #GtkTextIter
- * 
+ * @lhs: a `GtkTextIter`
+ * @rhs: another `GtkTextIter`
+ *
  * A qsort()-style function that returns negative if @lhs is less than
  * @rhs, positive if @lhs is greater than @rhs, and 0 if they’re equal.
- * Ordering is in character offset order, i.e. the first character in the buffer
- * is less than the second character in the buffer.
- * 
+ *
+ * Ordering is in character offset order, i.e. the first character
+ * in the buffer is less than the second character in the buffer.
+ *
  * Returns: -1 if @lhs is less than @rhs, 1 if @lhs is greater, 0 if they are equal
- **/
+ */
 int
 gtk_text_iter_compare (const GtkTextIter *lhs,
                        const GtkTextIter *rhs)
@@ -5455,15 +5574,16 @@ gtk_text_iter_compare (const GtkTextIter *lhs,
 
 /**
  * gtk_text_iter_in_range:
- * @iter: a #GtkTextIter
+ * @iter: a `GtkTextIter`
  * @start: start of range
  * @end: end of range
- * 
+ *
  * Checks whether @iter falls in the range [@start, @end).
+ *
  * @start and @end must be in ascending order.
- * 
+ *
  * Returns: %TRUE if @iter is in the range
- **/
+ */
 gboolean
 gtk_text_iter_in_range (const GtkTextIter *iter,
                         const GtkTextIter *start,
@@ -5480,17 +5600,19 @@ gtk_text_iter_in_range (const GtkTextIter *iter,
 
 /**
  * gtk_text_iter_order:
- * @first: a #GtkTextIter
- * @second: another #GtkTextIter
+ * @first: a `GtkTextIter`
+ * @second: another `GtkTextIter`
  *
  * Swaps the value of @first and @second if @second comes before
- * @first in the buffer. That is, ensures that @first and @second are
- * in sequence. Most text buffer functions that take a range call this
- * automatically on your behalf, so there’s no real reason to call it yourself
- * in those cases. There are some exceptions, such as gtk_text_iter_in_range(),
- * that expect a pre-sorted range.
- * 
- **/
+ * @first in the buffer.
+ *
+ * That is, ensures that @first and @second are in sequence.
+ * Most text buffer functions that take a range call this
+ * automatically on your behalf, so there’s no real reason to
+ * call it yourself in those cases. There are some exceptions,
+ * such as [method@Gtk.TextIter.in_range], that expect a
+ * pre-sorted range.
+ */
 void
 gtk_text_iter_order (GtkTextIter *first,
                      GtkTextIter *second)
diff --git a/gtk/gtktextiter.h b/gtk/gtktextiter.h
index c2ffd35c20..3a3107e49a 100644
--- a/gtk/gtktextiter.h
+++ b/gtk/gtktextiter.h
@@ -45,7 +45,7 @@ G_BEGIN_DECLS
  *
  * Flags affecting how a search is done.
  *
- * If neither #GTK_TEXT_SEARCH_VISIBLE_ONLY nor #GTK_TEXT_SEARCH_TEXT_ONLY are
+ * If neither %GTK_TEXT_SEARCH_VISIBLE_ONLY nor %GTK_TEXT_SEARCH_TEXT_ONLY are
  * enabled, the match must be exact; the special 0xFFFC character will match
  * embedded paintables or child widgets.
  */