From 1b559404a56d3ccc075283e38222df064a13eac0 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Fri, 19 Feb 2021 08:10:17 -0500
Subject: docs: Tweak fontset docs

Add summaries, convert markup, etc.
---
 pango/pango-fontset.c | 28 +++++++++++++++-------------
 pango/pango-fontset.h | 27 ++++++++++++++-------------
 2 files changed, 29 insertions(+), 26 deletions(-)

diff --git a/pango/pango-fontset.c b/pango/pango-fontset.c
index 6a3ef4c6..6f3bdcbf 100644
--- a/pango/pango-fontset.c
+++ b/pango/pango-fontset.c
@@ -49,14 +49,14 @@ pango_fontset_class_init (PangoFontsetClass *class)
 
 /**
  * pango_fontset_get_font:
- * @fontset: a #PangoFontset
+ * @fontset: a `PangoFontset`
  * @wc: a Unicode character
  *
- * Returns the font in the fontset that contains the best glyph for the
- * Unicode character @wc.
+ * Returns the font in the fontset that contains the best glyph for a
+ * Unicode character.
  *
- * Return value: (transfer full): a #PangoFont. The caller must call
- *          g_object_unref when finished with the font.
+ * Return value: (transfer full): a `PangoFont`. The caller must call
+ *          g_object_unref() when finished with the font.
  **/
 PangoFont *
 pango_fontset_get_font (PangoFontset  *fontset,
@@ -87,12 +87,14 @@ pango_fontset_get_metrics (PangoFontset  *fontset)
 
 /**
  * pango_fontset_foreach:
- * @fontset: a #PangoFontset
+ * @fontset: a `PangoFontset`
  * @func: (closure data) (scope call): Callback function
  * @data: (closure): data to pass to the callback function
  *
  * Iterates through all the fonts in a fontset, calling @func for
- * each one. If @func returns %TRUE, that stops the iteration.
+ * each one.
+ *
+ * If @func returns %TRUE, that stops the iteration.
  *
  * Since: 1.4
  **/
@@ -232,11 +234,11 @@ struct _PangoFontsetSimpleClass
 
 /**
  * pango_fontset_simple_new:
- * @language: a #PangoLanguage tag
+ * @language: a `PangoLanguage` tag
  *
- * Creates a new #PangoFontsetSimple for the given language.
+ * Creates a new `PangoFontsetSimple` for the given language.
  *
- * Return value: the newly allocated #PangoFontsetSimple, which should
+ * Return value: the newly allocated `PangoFontsetSimple`, which should
  *               be freed with g_object_unref().
  **/
 PangoFontsetSimple *
@@ -301,8 +303,8 @@ pango_fontset_simple_finalize (GObject *object)
 
 /**
  * pango_fontset_simple_append:
- * @fontset: a #PangoFontsetSimple.
- * @font: a #PangoFont.
+ * @fontset: a `PangoFontsetSimple`.
+ * @font: a `PangoFont`.
  *
  * Adds a font to the fontset.
  **/
@@ -316,7 +318,7 @@ pango_fontset_simple_append (PangoFontsetSimple *fontset,
 
 /**
  * pango_fontset_simple_size:
- * @fontset: a #PangoFontsetSimple.
+ * @fontset: a `PangoFontsetSimple`.
  *
  * Returns the number of fonts in the fontset.
  *
diff --git a/pango/pango-fontset.h b/pango/pango-fontset.h
index ce7d4107..2b2018dd 100644
--- a/pango/pango-fontset.h
+++ b/pango/pango-fontset.h
@@ -54,12 +54,12 @@ typedef struct _PangoFontsetClass   PangoFontsetClass;
 
 /**
  * PangoFontsetForeachFunc:
- * @fontset: a #PangoFontset
+ * @fontset: a `PangoFontset`
  * @font: a font from @fontset
  * @user_data: callback data
  *
- * A callback function used by pango_fontset_foreach() when enumerating
- * the fonts in a fontset.
+ * Callback used by pango_fontset_foreach() when enumerating
+ * fonts in a fontset.
  *
  * Returns: if %TRUE, stop iteration and return immediately.
  *
@@ -72,12 +72,12 @@ typedef gboolean (*PangoFontsetForeachFunc) (PangoFontset  *fontset,
 /**
  * PangoFontset:
  *
- * A #PangoFontset represents a set of #PangoFont to use
- * when rendering text. It is the result of resolving a
- * #PangoFontDescription against a particular #PangoContext.
- * It has operations for finding the component font for
- * a particular Unicode character, and for finding a composite
- * set of metrics for the entire fontset.
+ * A `PangoFontset` represents a set of `PangoFont` to use when rendering text.
+ *
+ * A `PAngoFontset` is the result of resolving a `PangoFontDescription`
+ * against a particular `PangoContext`. It has operations for finding the
+ * component font for a particular Unicode character, and for finding a
+ * composite set of metrics for the entire fontset.
  */
 struct _PangoFontset
 {
@@ -130,10 +130,11 @@ struct _PangoFontsetClass
 /**
  * PangoFontsetSimple:
  *
- * #PangoFontsetSimple is a implementation of the abstract
- * #PangoFontset base class in terms of an array of fonts,
- * which the creator provides when constructing the
- * #PangoFontsetSimple.
+ * `PangoFontsetSimple` is a implementation of the abstract
+ * `PangoFontset` base class as an array of fonts.
+ *
+ * When creating a `PangoFontsetSimple`, you have to provide
+ * the array of fonts that make up the fontset.
  */
 #define PANGO_TYPE_FONTSET_SIMPLE       (pango_fontset_simple_get_type ())
 #define PANGO_FONTSET_SIMPLE(object)    (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONTSET_SIMPLE, PangoFontsetSimple))
-- 
cgit v1.2.1