docs: Tweak glyph item docs

Add summaries, convert markup, etc.

4 files changed, 104 insertions, 92 deletions

diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index 326ae37f..8cca8627 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -30,13 +30,15 @@
 
 /**
  * pango_glyph_item_split:
- * @orig: a #PangoItem
+ * @orig: a `PangoItem`
  * @text: text to which positions in @orig apply
  * @split_index: byte index of position to split item, relative to the start of the item
  *
  * Modifies @orig to cover only the text after @split_index, and
  * returns a new item that covers the text before @split_index that
- * used to be in @orig. You can think of @split_index as the length of
+ * used to be in @orig.
+ *
+ * You can think of @split_index as the length of
  * the returned item. @split_index may not be 0, and it may not be
  * greater than or equal to the length of @orig (that is, there must
  * be at least one byte assigned to each item, you can't create a
@@ -132,11 +134,11 @@ pango_glyph_item_split (PangoGlyphItem *orig,
 
 /**
  * pango_glyph_item_copy:
- * @orig: (nullable): a #PangoGlyphItem, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`, may be %NULL
  *
- * Make a deep copy of an existing #PangoGlyphItem structure.
+ * Make a deep copy of an existing `PangoGlyphItem` structure.
  *
- * Return value: (nullable): the newly allocated #PangoGlyphItem, which should
+ * Return value: (nullable): the newly allocated `PangoGlyphItem`, which should
  *               be freed with pango_glyph_item_free(), or %NULL
  *               if @orig was %NULL.
  *
@@ -160,9 +162,9 @@ pango_glyph_item_copy  (PangoGlyphItem *orig)
 
 /**
  * pango_glyph_item_free:
- * @glyph_item: (nullable): a #PangoGlyphItem, may be %NULL
+ * @glyph_item: (nullable): a `PangoGlyphItem`, may be %NULL
  *
- * Frees a #PangoGlyphItem and resources to which it points.
+ * Frees a `PangoGlyphItem` and resources to which it points.
  *
  * Since: 1.6
  **/
@@ -187,13 +189,13 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item,
 
 /**
  * pango_glyph_item_iter_copy:
- * @orig: (nullable): a #PangoGlyphItemIter, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`Iter, may be %NULL
  *
- * Make a shallow copy of an existing #PangoGlyphItemIter structure.
+ * Make a shallow copy of an existing `PangoGlyphItemIter` structure.
  *
- * Return value: (nullable): the newly allocated #PangoGlyphItemIter, which should
- *               be freed with pango_glyph_item_iter_free(), or %NULL
- *               if @orig was %NULL.
+ * Return value: (nullable): the newly allocated `PangoGlyphItemIter`,
+ *   which should be freed with pango_glyph_item_iter_free(), or %NULL
+ *   if @orig was %NULL.
  *
  * Since: 1.22
  **/
@@ -214,9 +216,9 @@ pango_glyph_item_iter_copy  (PangoGlyphItemIter *orig)
 
 /**
  * pango_glyph_item_iter_free:
- * @iter: (nullable): a #PangoGlyphItemIter, may be %NULL
+ * @iter: (nullable): a `PangoGlyphItemIter`, may be %NULL
  *
- * Frees a #PangoGlyphItemIter created by pango_glyph_item_iter_copy().
+ * Frees a `PangoGlyphItem`Iter.
  *
  * Since: 1.22
  **/
@@ -235,13 +237,14 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItemIter, pango_glyph_item_iter,
 
 /**
  * pango_glyph_item_iter_next_cluster:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
  *
  * Advances the iterator to the next cluster in the glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
  *
- * Return value: %TRUE if the iterator was advanced, %FALSE if we were already on the
- *  last cluster.
+ * See `PangoGlyphItemIter` for details of cluster orders.
+ *
+ * Return value: %TRUE if the iterator was advanced,
+ *   %FALSE if we were already on the  last cluster.
  *
  * Since: 1.22
  **/
@@ -325,13 +328,13 @@ pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter)
 
 /**
  * pango_glyph_item_iter_prev_cluster:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
  *
  * Moves the iterator to the preceding cluster in the glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
+ * See `PangoGlyphItemIter` for details of cluster orders.
  *
- * Return value: %TRUE if the iterator was moved, %FALSE if we were already on the
- *  first cluster.
+ * Return value: %TRUE if the iterator was moved,
+ *   %FALSE if we were already on the first cluster.
  *
  * Since: 1.22
  **/
@@ -418,13 +421,14 @@ pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter)
 
 /**
  * pango_glyph_item_iter_init_start:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
  * @glyph_item: the glyph item to iterate over
  * @text: text corresponding to the glyph item
  *
- * Initializes a #PangoGlyphItemIter structure to point to the
+ * Initializes a `PangoGlyphItemIter` structure to point to the
  * first cluster in a glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
+ *
+ * See `PangoGlyphItemIter` for details of cluster orders.
  *
  * Return value: %FALSE if there are no clusters in the glyph item
  *
@@ -456,13 +460,14 @@ pango_glyph_item_iter_init_start (PangoGlyphItemIter  *iter,
 
 /**
  * pango_glyph_item_iter_init_end:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
  * @glyph_item: the glyph item to iterate over
  * @text: text corresponding to the glyph item
  *
- * Initializes a #PangoGlyphItemIter structure to point to the
+ * Initializes a `PangoGlyphItemIter` structure to point to the
  * last cluster in a glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
+ *
+ * See `PangoGlyphItemIter` for details of cluster orders.
  *
  * Return value: %FALSE if there are no clusters in the glyph item
  *
@@ -554,12 +559,14 @@ split_before_cluster_start (ApplyAttrsState *state)
  * pango_glyph_item_apply_attrs:
  * @glyph_item: a shaped item
  * @text: text that @list applies to
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
  *
- * Splits a shaped item (PangoGlyphItem) into multiple items based
- * on an attribute list. The idea is that if you have attributes
+ * Splits a shaped item (`PangoGlyphItem`) into multiple items based
+ * on an attribute list.
+ *
+ * The idea is that if you have attributes
  * that don't affect shaping, such as color or underline, to avoid
- * affecting shaping, you filter them out (pango_attr_list_filter()),
+ * affecting shaping, you filter them out ([method@Pango.AttrList.filter]),
  * apply the shaping process and then reapply them to the result using
  * this function.
  *
@@ -567,7 +574,7 @@ split_before_cluster_start (ApplyAttrsState *state)
  * to that cluster; for instance, if half of a cluster is underlined
  * and the other-half strikethrough, then the cluster will end
  * up with both underline and strikethrough attributes. In these
- * cases, it may happen that item->extra_attrs for some of the
+ * cases, it may happen that @item->extra_attrs for some of the
  * result items can have multiple attributes of the same type.
  *
  * This function takes ownership of @glyph_item; it will be reused
@@ -575,7 +582,7 @@ split_before_cluster_start (ApplyAttrsState *state)
  *
  * Return value: (transfer full) (element-type Pango.GlyphItem): a
  *   list of glyph items resulting from splitting @glyph_item. Free
- *   the elements using pango_glyph_item_free(), the list using
+ *   the elements using [method@Pango.GlyphItem.free], the list using
  *   g_slist_free().
  *
  * Since: 1.2
@@ -711,7 +718,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem   *glyph_item,
 
 /**
  * pango_glyph_item_letter_space:
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a `PangoGlyphItem`
  * @text: text that @glyph_item corresponds to
  *   (glyph_item->item->offset is an offset from the
  *    start of @text)
@@ -726,7 +733,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem   *glyph_item,
  * give the effect of typographic letter spacing.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
 			       const char     *text,
@@ -784,7 +791,7 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
 
 /**
  * pango_glyph_item_get_logical_widths:
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a `PangoGlyphItem`
  * @text: text that @glyph_item corresponds to
  *   (glyph_item->item->offset is an offset from the
  *    start of @text)
@@ -793,12 +800,13 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
  *                  glyph_item->item->num_chars) to be filled in with
  *                  the resulting character widths.
  *
- * Given a #PangoGlyphItem and the corresponding
- * text, determine the screen width corresponding to each character. When
- * multiple characters compose a single cluster, the width of the entire
+ * Given a `PangoGlyphItem` and the corresponding text, determine the width
+ * corresponding to each character.
+ *
+ * When multiple characters compose a single cluster, the width of the entire
  * cluster is divided equally among the characters.
  *
- * See also pango_glyph_string_get_logical_widths().
+ * See also [method@Pango.GlyphString.get_logical_widths].
  *
  * Since: 1.26
  **/
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index 543d74bd..8a1dbff4 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -31,14 +31,15 @@ G_BEGIN_DECLS
 
 /**
  * PangoGlyphItem:
- * @item: corresponding #PangoItem.
- * @glyphs: corresponding #PangoGlyphString.
- *
- * A #PangoGlyphItem is a pair of a #PangoItem and the glyphs
- * resulting from shaping the text corresponding to an item.
- * As an example of the usage of #PangoGlyphItem, the results
- * of shaping text with #PangoLayout is a list of #PangoLayoutLine,
- * each of which contains a list of #PangoGlyphItem.
+ * @item: corresponding `PangoItem`
+ * @glyphs: corresponding `PangoGlyphString`
+ *
+ * A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs
+ * resulting from shaping the items text.
+ *
+ * As an example of the usage of `PangoGlyphItem`, the results
+ * of shaping text with `PangoLayout` is a list of `PangoLayoutLine`,
+ * each of which contains a list of `PangoGlyphItem`.
  */
 typedef struct _PangoGlyphItem PangoGlyphItem;
 
@@ -84,21 +85,23 @@ void 	  pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
 /**
  * PangoGlyphItemIter:
  *
- * A #PangoGlyphItemIter is an iterator over the clusters in a
- * #PangoGlyphItem.  The *forward direction* of the
- * iterator is the logical direction of text.  That is, with increasing
- * @start_index and @start_char values.  If @glyph_item is right-to-left
- * (that is, if `glyph_item->item->analysis.level` is odd),
+ * A `PangoGlyphItemIter` is an iterator over the clusters in a
+ * `PangoGlyphItem`.
+ *
+ * The *forward direction* of the iterator is the logical direction of text.
+ * That is, with increasing @start_index and @start_char values. If @glyph_item
+ * is right-to-left (that is, if `glyph_item->item->analysis.level` is odd),
  * then @start_glyph decreases as the iterator moves forward.  Moreover,
  * in right-to-left cases, @start_glyph is greater than @end_glyph.
  *
- * An iterator should be initialized using either of
- * pango_glyph_item_iter_init_start() and
+ * An iterator should be initialized using either
+ * pango_glyph_item_iter_init_start() or
  * pango_glyph_item_iter_init_end(), for forward and backward iteration
  * respectively, and walked over using any desired mixture of
  * pango_glyph_item_iter_next_cluster() and
- * pango_glyph_item_iter_prev_cluster().  A common idiom for doing a
- * forward iteration over the clusters is:
+ * pango_glyph_item_iter_prev_cluster().
+ *
+ * A common idiom for doing a forward iteration over the clusters is:
  *
  * ```
  * PangoGlyphItemIter cluster_iter;
@@ -114,14 +117,14 @@ void 	  pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
  * ```
  *
  * Note that @text is the start of the text for layout, which is then
- * indexed by `glyph_item->item->offset` to get to the
- * text of @glyph_item.  The @start_index and @end_index values can directly
- * index into @text.  The @start_glyph, @end_glyph, @start_char, and @end_char
- * values however are zero-based for the @glyph_item.  For each cluster, the
- * item pointed at by the start variables is included in the cluster while
- * the one pointed at by end variables is not.
- *
- * None of the members of a #PangoGlyphItemIter should be modified manually.
+ * indexed by `glyph_item->item->offset` to get to the text of @glyph_item.
+ * The @start_index and @end_index values can directly index into @text. The
+ * @start_glyph, @end_glyph, @start_char, and @end_char values however are
+ * zero-based for the @glyph_item.  For each cluster, the item pointed at by
+ * the start variables is included in the cluster while the one pointed at by
+ * end variables is not.
+ *
+ * None of the members of a `PangoGlyphItemIter` should be modified manually.
  *
  * Since: 1.22
  */
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 628eac96..7c1bf7b5 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -36,8 +36,10 @@ typedef struct _PangoGlyphString PangoGlyphString;
 /**
  * PangoGlyphUnit:
  *
- * The #PangoGlyphUnit type is used to store dimensions within
- * Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit.
+ * The `PangoGlyphUnit` type is used to store dimensions within
+ * Pango.
+ *
+ * Dimensions are stored in 1/%PANGO_SCALE of a device unit.
  * (A device unit might be a pixel for screen display, or
  * a point on a printer.) %PANGO_SCALE is currently 1024, and
  * may change in the future (unlikely though), but you should not
@@ -54,7 +56,7 @@ typedef gint32 PangoGlyphUnit;
  * @x_offset: horizontal offset from nominal character position.
  * @y_offset: vertical offset from nominal character position.
  *
- * The #PangoGlyphGeometry structure contains width and positioning
+ * The `PangoGlyphGeometry` structure contains width and positioning
  * information for a single glyph.
  */
 struct _PangoGlyphGeometry
@@ -68,15 +70,17 @@ struct _PangoGlyphGeometry
  */
 /**
  * PangoGlyphVisAttr:
- * @is_cluster_start: set for the first logical glyph in each cluster. (Clusters
- * are stored in visual order, within the cluster, glyphs
- * are always ordered in logical order, since visual
- * order is meaningless; that is, in Arabic text, accent glyphs
- * follow the glyphs for the base character.)
+ * @is_cluster_start: set for the first logical glyph in each cluster.
+ *   (Clusters are stored in visual order, within the cluster, glyphs
+ *   are always ordered in logical order, since visual order is meaningless;
+ *   that is, in Arabic text, accent glyphs follow the glyphs for the
+ *   base character.)
+ *
+ * A `PangoGlyphVisAttr` structure communicates information between
+ * the shaping and rendering phases.
  *
- * The PangoGlyphVisAttr is used to communicate information between
- * the shaping phase and the rendering phase.  More attributes may be
- * added in the future.
+ * Currently, it contains only cluster start information. yMore attributes
+ * may be added in the future.
  */
 struct _PangoGlyphVisAttr
 {
@@ -91,9 +95,8 @@ struct _PangoGlyphVisAttr
  * @geometry: the positional information about the glyph.
  * @attr: the visual attributes of the glyph.
  *
- * The #PangoGlyphInfo structure represents a single glyph together with
+ * A `PangoGlyphInfo` structure represents a single glyph with
  * positioning information and visual attributes.
- * It contains the following fields.
  */
 struct _PangoGlyphInfo
 {
@@ -102,9 +105,6 @@ struct _PangoGlyphInfo
   PangoGlyphVisAttr  attr;
 };
 
-/* A string of glyphs with positional information and visual attributes -
- * ready for drawing
- */
 /**
  * PangoGlyphString:
  * @num_glyphs: number of the glyphs in this glyph string.
@@ -113,10 +113,11 @@ struct _PangoGlyphInfo
  * @log_clusters: logical cluster info, indexed by the byte index
  *                within the text corresponding to the glyph string.
  *
- * The #PangoGlyphString structure is used to store strings
- * of glyphs with geometry and visual attribute information.
- * The storage for the glyph information is owned
- * by the structure which simplifies memory management.
+ * A `PangoGlyphString` is used to store strings of glyphs with geometry
+ * and visual attribute information.
+ *
+ * The storage for the glyph information is owned by the structure
+ * which simplifies memory management.
  */
 struct _PangoGlyphString {
   gint num_glyphs;
@@ -211,7 +212,8 @@ void pango_shape_full (const char          *item_text,
  *     positioning of glyphs.
  *
  * Flags influencing the shaping process.
- * These can be passed to pango_shape_with_flags().
+ *
+ * `PangoShapeFlags` can be passed to pango_shape_with_flags().
  */
 typedef enum {
   PANGO_SHAPE_NONE            = 0,
diff --git a/pango/pango-item.h b/pango/pango-item.h
index 638f970a..a1e95086 100644
--- a/pango/pango-item.h
+++ b/pango/pango-item.h
@@ -34,7 +34,8 @@ typedef struct _PangoItem PangoItem;
  * PANGO_ANALYSIS_FLAG_CENTERED_BASELINE:
  *
  * Whether the segment should be shifted to center around the baseline.
- * Used in vertical writing directions mostly.
+ *
+ * This is mainly used in vertical writing directions.
  *
  * Since: 1.16
  */
@@ -43,8 +44,7 @@ typedef struct _PangoItem PangoItem;
 /**
  * PANGO_ANALYSIS_FLAG_IS_ELLIPSIS:
  *
- * This flag is used to mark runs that hold ellipsized text,
- * in an ellipsized layout.
+ * Whether this run holds ellipsized text.
  *
  * Since: 1.36.7
  */
@@ -53,8 +53,7 @@ typedef struct _PangoItem PangoItem;
 /**
  * PANGO_ANALYSIS_FLAG_NEED_HYPHEN:
  *
- * This flag tells Pango to add a hyphen at the end of the
- * run during shaping.
+ * Whether to add a hyphen at the end of the run during shaping.
  *
  * Since: 1.44
  */