docs: Port PangoFont to the new doc format

Replace gtk-doc'isms and use gi-docgen links instead.

1 files changed, 48 insertions, 118 deletions

diff --git a/pango/pango-font.h b/pango/pango-font.h
index cc12a295..1fbade27 100644
--- a/pango/pango-font.h
+++ b/pango/pango-font.h
@@ -10,7 +10,7 @@
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
  *
  * You should have received a copy of the GNU Library General Public
@@ -33,7 +33,7 @@ G_BEGIN_DECLS
 /**
  * PangoFontDescription:
  *
- * The #PangoFontDescription structure represents the description
+ * The `PangoFontDescription` structure represents the description
  * of an ideal font. These structures are used both to list
  * what fonts are available on the system and also for specifying
  * the characteristics of a font to load.
@@ -42,7 +42,7 @@ typedef struct _PangoFontDescription PangoFontDescription;
 /**
  * PangoFontMetrics:
  *
- * A #PangoFontMetrics structure holds the overall metric information
+ * A `PangoFontMetrics` structure holds the overall metric information
  * for a font (possibly restricted to a script). The fields of this
  * structure are private to implementations of a font backend. See
  * the documentation of the corresponding getters for documentation
@@ -148,8 +148,8 @@ typedef enum {
  * @PANGO_FONT_MASK_GRAVITY: the font gravity is specified (Since: 1.16.)
  * @PANGO_FONT_MASK_VARIATIONS: OpenType font variations are specified (Since: 1.42)
  *
- * The bits in a #PangoFontMask correspond to fields in a
- * #PangoFontDescription that have been set.
+ * The bits in a `PangoFontMask` correspond to fields in a
+ * [struct@Pango.FontDescription] that have been set.
  */
 typedef enum {
   PANGO_FONT_MASK_FAMILY  = 1 << 0,
@@ -210,11 +210,6 @@ typedef enum {
  * PangoFontDescription
  */
 
-/**
- * PANGO_TYPE_FONT_DESCRIPTION:
- *
- * The #GObject type for #PangoFontDescription.
- */
 #define PANGO_TYPE_FONT_DESCRIPTION (pango_font_description_get_type ())
 
 PANGO_AVAILABLE_IN_ALL
@@ -229,54 +224,54 @@ PANGO_AVAILABLE_IN_ALL
 guint                 pango_font_description_hash        (const PangoFontDescription  *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 gboolean              pango_font_description_equal       (const PangoFontDescription  *desc1,
-							  const PangoFontDescription  *desc2) G_GNUC_PURE;
+                                                          const PangoFontDescription  *desc2) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                  pango_font_description_free        (PangoFontDescription        *desc);
 PANGO_AVAILABLE_IN_ALL
 void                  pango_font_descriptions_free       (PangoFontDescription       **descs,
-							  int                          n_descs);
+                                                          int                          n_descs);
 
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_family        (PangoFontDescription *desc,
-							       const char           *family);
+                                                               const char           *family);
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_family_static (PangoFontDescription *desc,
-							       const char           *family);
+                                                               const char           *family);
 PANGO_AVAILABLE_IN_ALL
 const char          *pango_font_description_get_family        (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_style         (PangoFontDescription *desc,
-							       PangoStyle            style);
+                                                               PangoStyle            style);
 PANGO_AVAILABLE_IN_ALL
 PangoStyle           pango_font_description_get_style         (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_variant       (PangoFontDescription *desc,
-							       PangoVariant          variant);
+                                                               PangoVariant          variant);
 PANGO_AVAILABLE_IN_ALL
 PangoVariant         pango_font_description_get_variant       (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_weight        (PangoFontDescription *desc,
-							       PangoWeight           weight);
+                                                               PangoWeight           weight);
 PANGO_AVAILABLE_IN_ALL
 PangoWeight          pango_font_description_get_weight        (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_stretch       (PangoFontDescription *desc,
-							       PangoStretch          stretch);
+                                                               PangoStretch          stretch);
 PANGO_AVAILABLE_IN_ALL
 PangoStretch         pango_font_description_get_stretch       (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_description_set_size          (PangoFontDescription *desc,
-							       gint                  size);
+                                                               gint                  size);
 PANGO_AVAILABLE_IN_ALL
 gint                 pango_font_description_get_size          (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_1_8
 void                 pango_font_description_set_absolute_size (PangoFontDescription *desc,
-							       double                size);
+                                                               double                size);
 PANGO_AVAILABLE_IN_1_8
 gboolean             pango_font_description_get_size_is_absolute (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_1_16
 void                 pango_font_description_set_gravity       (PangoFontDescription *desc,
-							       PangoGravity          gravity);
+                                                               PangoGravity          gravity);
 PANGO_AVAILABLE_IN_1_16
 PangoGravity         pango_font_description_get_gravity       (const PangoFontDescription *desc) G_GNUC_PURE;
 
@@ -293,21 +288,21 @@ PANGO_AVAILABLE_IN_ALL
 PangoFontMask pango_font_description_get_set_fields (const PangoFontDescription *desc) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_ALL
 void          pango_font_description_unset_fields   (PangoFontDescription       *desc,
-						     PangoFontMask               to_unset);
+                                                     PangoFontMask               to_unset);
 
 PANGO_AVAILABLE_IN_ALL
 void pango_font_description_merge        (PangoFontDescription       *desc,
-					  const PangoFontDescription *desc_to_merge,
-					  gboolean                    replace_existing);
+                                          const PangoFontDescription *desc_to_merge,
+                                          gboolean                    replace_existing);
 PANGO_AVAILABLE_IN_ALL
 void pango_font_description_merge_static (PangoFontDescription       *desc,
-					  const PangoFontDescription *desc_to_merge,
-					  gboolean                    replace_existing);
+                                          const PangoFontDescription *desc_to_merge,
+                                          gboolean                    replace_existing);
 
 PANGO_AVAILABLE_IN_ALL
 gboolean pango_font_description_better_match (const PangoFontDescription *desc,
-					      const PangoFontDescription *old_match,
-					      const PangoFontDescription *new_match) G_GNUC_PURE;
+                                              const PangoFontDescription *old_match,
+                                              const PangoFontDescription *new_match) G_GNUC_PURE;
 
 PANGO_AVAILABLE_IN_ALL
 PangoFontDescription *pango_font_description_from_string (const char                  *str);
@@ -320,11 +315,6 @@ char *                pango_font_description_to_filename (const PangoFontDescrip
  * PangoFontMetrics
  */
 
-/**
- * PANGO_TYPE_FONT_METRICS:
- *
- * The #GObject type for #PangoFontMetrics.
- */
 #define PANGO_TYPE_FONT_METRICS  (pango_font_metrics_get_type ())
 
 struct _PangoFontMetrics
@@ -373,23 +363,6 @@ int               pango_font_metrics_get_strikethrough_thickness (PangoFontMetri
  * PangoFontFamily
  */
 
-/**
- * PANGO_TYPE_FONT_FAMILY:
- *
- * The #GObject type for #PangoFontFamily.
- */
-/**
- * PANGO_FONT_FAMILY:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFontFamily.
- */
-/**
- * PANGO_IS_FONT_FAMILY:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFontFamily.
- */
 #define PANGO_TYPE_FONT_FAMILY              (pango_font_family_get_type ())
 #define PANGO_FONT_FAMILY(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FAMILY, PangoFontFamily))
 #define PANGO_IS_FONT_FAMILY(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FAMILY))
@@ -406,7 +379,7 @@ typedef struct _PangoFontFamilyClass PangoFontFamilyClass;
 /**
  * PangoFontFamily:
  *
- * The #PangoFontFamily structure is used to represent a family of related
+ * The `PangoFontFamily` structure is used to represent a family of related
  * font faces. The faces in a family share a common design, but differ in
  * slant, weight, width and other aspects.
  */
@@ -445,8 +418,8 @@ GType      pango_font_family_get_type       (void) G_GNUC_CONST;
 
 PANGO_AVAILABLE_IN_ALL
 void                 pango_font_family_list_faces (PangoFontFamily  *family,
-						   PangoFontFace  ***faces,
-						   int              *n_faces);
+                                                   PangoFontFace  ***faces,
+                                                   int              *n_faces);
 PANGO_AVAILABLE_IN_ALL
 const char *pango_font_family_get_name   (PangoFontFamily  *family) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_1_4
@@ -463,23 +436,6 @@ PangoFontFace *pango_font_family_get_face (PangoFontFamily *family,
  * PangoFontFace
  */
 
-/**
- * PANGO_TYPE_FONT_FACE:
- *
- * The #GObject type for #PangoFontFace.
- */
-/**
- * PANGO_FONT_FACE:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFontFace.
- */
-/**
- * PANGO_IS_FONT_FACE:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFontFace.
- */
 #define PANGO_TYPE_FONT_FACE              (pango_font_face_get_type ())
 #define PANGO_FONT_FACE(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FACE, PangoFontFace))
 #define PANGO_IS_FONT_FACE(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FACE))
@@ -494,7 +450,7 @@ typedef struct _PangoFontFaceClass   PangoFontFaceClass;
 /**
  * PangoFontFace:
  *
- * The #PangoFontFace structure is used to represent a group of fonts with
+ * The `PangoFontFace` structure is used to represent a group of fonts with
  * the same family, slant, weight, width, but varying sizes.
  */
 struct _PangoFontFace
@@ -534,8 +490,8 @@ PANGO_AVAILABLE_IN_ALL
 const char           *pango_font_face_get_face_name  (PangoFontFace  *face) G_GNUC_PURE;
 PANGO_AVAILABLE_IN_1_4
 void                  pango_font_face_list_sizes     (PangoFontFace  *face,
-						      int           **sizes,
-						      int            *n_sizes);
+                                                      int           **sizes,
+                                                      int            *n_sizes);
 PANGO_AVAILABLE_IN_1_18
 gboolean              pango_font_face_is_synthesized (PangoFontFace  *face) G_GNUC_PURE;
 
@@ -547,23 +503,6 @@ PangoFontFamily *     pango_font_face_get_family     (PangoFontFace  *face);
  * PangoFont
  */
 
-/**
- * PANGO_TYPE_FONT:
- *
- * The #GObject type for #PangoFont.
- */
-/**
- * PANGO_FONT:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFont.
- */
-/**
- * PANGO_IS_FONT:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFont.
- */
 #define PANGO_TYPE_FONT              (pango_font_get_type ())
 #define PANGO_FONT(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT, PangoFont))
 #define PANGO_IS_FONT(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT))
@@ -577,18 +516,8 @@ PangoFontFamily *     pango_font_face_get_family     (PangoFontFace  *face);
 /**
  * PangoFont:
  *
- * The #PangoFont structure is used to represent
- * a font in a rendering-system-independent matter.
- * To create an implementation of a #PangoFont,
- * the rendering-system specific code should allocate
- * a larger structure that contains a nested
- * #PangoFont, fill in the `klass` member of
- * the nested #PangoFont with a pointer to
- * a appropriate #PangoFontClass, then call
- * pango_font_init() on the structure.
- *
- * The #PangoFont structure contains one member
- * which the implementation fills in.
+ * The `PangoFont` structure is used to represent a font in a
+ * rendering-system-independent matter.
  */
 struct _PangoFont
 {
@@ -631,19 +560,19 @@ PANGO_AVAILABLE_IN_1_14
 PangoFontDescription *pango_font_describe_with_absolute_size (PangoFont        *font);
 PANGO_AVAILABLE_IN_ALL
 PangoCoverage *       pango_font_get_coverage      (PangoFont        *font,
-						    PangoLanguage    *language);
+                                                    PangoLanguage    *language);
 PANGO_DEPRECATED_IN_1_44
 PangoEngineShape *    pango_font_find_shaper       (PangoFont        *font,
-						    PangoLanguage    *language,
-						    guint32           ch);
+                                                    PangoLanguage    *language,
+                                                    guint32           ch);
 PANGO_AVAILABLE_IN_ALL
 PangoFontMetrics *    pango_font_get_metrics       (PangoFont        *font,
-						    PangoLanguage    *language);
+                                                    PangoLanguage    *language);
 PANGO_AVAILABLE_IN_ALL
 void                  pango_font_get_glyph_extents (PangoFont        *font,
-						    PangoGlyph        glyph,
-						    PangoRectangle   *ink_rect,
-						    PangoRectangle   *logical_rect);
+                                                    PangoGlyph        glyph,
+                                                    PangoRectangle   *ink_rect,
+                                                    PangoRectangle   *logical_rect);
 PANGO_AVAILABLE_IN_1_10
 PangoFontMap         *pango_font_get_font_map      (PangoFont        *font);
 
@@ -664,16 +593,17 @@ hb_font_t *           pango_font_get_hb_font       (PangoFont        *font);
 /**
  * PANGO_GLYPH_EMPTY:
  *
- * The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a
- *  special meaning, which is a zero-width empty glyph.  This is useful for
+ * The %PANGO_GLYPH_EMPTY macro represents a `PangoGlyph` value that has a
+ *  special meaning, which is a zero-width empty glyph. This is useful for
  * example in shaper modules, to use as the glyph for various zero-width
- * Unicode characters (those passing pango_is_zero_width()).
+ * Unicode characters (those passing [func@is_zero_width]).
  */
+
 /**
  * PANGO_GLYPH_INVALID_INPUT:
  *
- * The %PANGO_GLYPH_INVALID_INPUT macro represents a #PangoGlyph value that has a
- * special meaning of invalid input.  #PangoLayout produces one such glyph
+ * The %PANGO_GLYPH_INVALID_INPUT macro represents a `PangoGlyph` value that
+ * has a special meaning of invalid input. `PangoLayout` produces one such glyph
  * per invalid input UTF-8 byte and such a glyph is rendered as a crossed
  * box.
  *
@@ -686,18 +616,18 @@ hb_font_t *           pango_font_get_hb_font       (PangoFont        *font);
  * PANGO_GLYPH_UNKNOWN_FLAG:
  *
  * The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to
- * a #gunichar value of a valid Unicode character, to produce a #PangoGlyph
- * value, representing an unknown-character glyph for the respective #gunichar.
+ * a `gunichar` value of a valid Unicode character, to produce a `PangoGlyph`
+ * value, representing an unknown-character glyph for the respective `gunichar`.
  */
 /**
  * PANGO_GET_UNKNOWN_GLYPH:
  * @wc: a Unicode character
  *
- * The way this unknown glyphs are rendered is backend specific.  For example,
+ * The way this unknown glyphs are rendered is backend specific. For example,
  * a box with the hexadecimal Unicode code-point of the character written in it
  * is what is done in the most common backends.
  *
- * Returns: a #PangoGlyph value that means no glyph was found for @wc.
+ * Returns: a `PangoGlyph` value that means no glyph was found for @wc.
  */
 #define PANGO_GLYPH_EMPTY           ((PangoGlyph)0x0FFFFFFF)
 #define PANGO_GLYPH_INVALID_INPUT   ((PangoGlyph)0xFFFFFFFF)