[pango/gi-docs: 28/30] docs: Port PangoFc apis to the new doc format

[Matthias Clasen <matthiasc src gnome org>]

commit 2edd4790f6a8f69f91e17ff9f2dfb44816b3322c
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Feb 15 01:19:43 2021 -0500

    docs: Port PangoFc apis to the new doc format
    
    Replace gtk-doc'isms and use gi-docgen links instead.
    
    Cross-gir links are still an open issue.

 pango/pangofc-font.c    |  66 +++++++++++---------
 pango/pangofc-fontmap.c | 159 ++++++++++++++++++++++++------------------------
 2 files changed, 118 insertions(+), 107 deletions(-)
---
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index d4488531..d8616537 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -25,7 +25,7 @@
  * @title:PangoFcFont
  * @see_also: #PangoFcFontMap
  *
- * #PangoFcFont is a base class for font implementation using the
+ * `PangoFcFont` is a base class for font implementation using the
  * Fontconfig and FreeType libraries. It is used in the Xft and
  * FreeType backends shipped with Pango, but can also be used when
  * creating new backends. Any backend deriving from this base class
@@ -111,12 +111,23 @@ pango_fc_font_class_init (PangoFcFontClass *class)
   font_class->create_hb_font = pango_fc_font_create_hb_font;
   font_class->get_features = pango_fc_font_get_features;
 
+  /**
+   * PangoFcFont:pattern:
+   *
+   * The fontconfig pattern for this font.
+   */
   g_object_class_install_property (object_class, PROP_PATTERN,
                                   g_param_spec_pointer ("pattern",
                                                         "Pattern",
                                                         "The fontconfig pattern for this font",
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                         G_PARAM_STATIC_STRINGS));
+
+  /**
+   * PangoFcFont:fontmap:
+   *
+   * The PangoFc font map this font is associated with.
+   */
   g_object_class_install_property (object_class, PROP_FONTMAP,
                                   g_param_spec_object ("fontmap",
                                                        "Font Map",
@@ -529,17 +540,17 @@ pango_fc_font_real_get_glyph (PangoFcFont *font,
 
 /**
  * pango_fc_font_lock_face: (skip)
- * @font: a #PangoFcFont.
+ * @font: a `PangoFcFont`.
  *
  * Gets the FreeType `FT_Face` associated with a font,
  * This face will be kept around until you call
- * pango_fc_font_unlock_face().
+ * [method PangoFc Font.unlock_face].
  *
  * Return value: the FreeType `FT_Face` associated with @font.
  *
  * Since: 1.4
  * Deprecated: 1.44: Use pango_font_get_hb_font() instead
- **/
+ */
 FT_Face
 pango_fc_font_lock_face (PangoFcFont *font)
 {
@@ -550,14 +561,14 @@ pango_fc_font_lock_face (PangoFcFont *font)
 
 /**
  * pango_fc_font_unlock_face:
- * @font: a #PangoFcFont.
+ * @font: a `PangoFcFont`.
  *
  * Releases a font previously obtained with
- * pango_fc_font_lock_face().
+ * [method PangoFc Font.lock_face].
  *
  * Since: 1.4
  * Deprecated: 1.44: Use pango_font_get_hb_font() instead
- **/
+ */
 void
 pango_fc_font_unlock_face (PangoFcFont *font)
 {
@@ -577,7 +588,7 @@ pango_fc_font_unlock_face (PangoFcFont *font)
  *
  * Since: 1.4
  * Deprecated: 1.44: Use pango_font_has_char()
- **/
+ */
 gboolean
 pango_fc_font_has_char (PangoFcFont *font,
                        gunichar     wc)
@@ -602,14 +613,14 @@ pango_fc_font_has_char (PangoFcFont *font,
  * @wc: Unicode character to look up
  *
  * Gets the glyph index for a given Unicode character
- * for @font. If you only want to determine
- * whether the font has the glyph, use pango_fc_font_has_char().
+ * for @font. If you only want to determine whether the
+ * font has the glyph, use [method PangoFc Font.has_char].
  *
  * Return value: the glyph index, or 0, if the Unicode
  *   character doesn't exist in the font.
  *
  * Since: 1.4
- **/
+ */
 PangoGlyph
 pango_fc_font_get_glyph (PangoFcFont *font,
                         gunichar     wc)
@@ -642,7 +653,7 @@ pango_fc_font_get_glyph (PangoFcFont *font,
  * Return value: a glyph index into @font.
  *
  * Since: 1.4
- **/
+ */
 PangoGlyph
 pango_fc_font_get_unknown_glyph (PangoFcFont *font,
                                 gunichar     wc)
@@ -665,17 +676,16 @@ _pango_fc_font_shutdown (PangoFcFont *font)
 /**
  * pango_fc_font_kern_glyphs:
  * @font: a #PangoFcFont
- * @glyphs: a #PangoGlyphString
+ * @glyphs: a `PangoGlyphString`
  *
  * This function used to adjust each adjacent pair of glyphs
  * in @glyphs according to kerning information in @font.
  *
  * Since 1.44, it does nothing.
  *
- *
  * Since: 1.4
  * Deprecated: 1.32
- **/
+ */
 void
 pango_fc_font_kern_glyphs (PangoFcFont      *font,
                           PangoGlyphString *glyphs)
@@ -684,15 +694,14 @@ pango_fc_font_kern_glyphs (PangoFcFont      *font,
 
 /**
  * _pango_fc_font_get_decoder:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  *
  * This will return any custom decoder set on this font.
  *
  * Return value: The custom decoder
  *
  * Since: 1.6
- **/
-
+ */
 PangoFcDecoder *
 _pango_fc_font_get_decoder (PangoFcFont *font)
 {
@@ -703,15 +712,14 @@ _pango_fc_font_get_decoder (PangoFcFont *font)
 
 /**
  * _pango_fc_font_set_decoder:
- * @font: a #PangoFcFont
- * @decoder: a #PangoFcDecoder to set for this font
+ * @font: a `PangoFcFont`
+ * @decoder: a `PangoFcDecoder` to set for this font
  *
- * This sets a custom decoder for this font.  Any previous decoder
- * will be released before this one is set.
+ * This sets a custom decoder for this font.
+ * Any previous decoder will be released before this one is set.
  *
  * Since: 1.6
- **/
-
+ */
 void
 _pango_fc_font_set_decoder (PangoFcFont    *font,
                            PangoFcDecoder *decoder)
@@ -746,7 +754,7 @@ _pango_fc_font_set_font_key (PangoFcFont    *fcfont,
 
 /**
  * pango_fc_font_get_raw_extents:
- * @fcfont: a #PangoFcFont
+ * @fcfont: a `PangoFcFont`
  * @glyph: the glyph index to load
  * @ink_rect: (out) (optional): location to store ink extents of the
  *   glyph, or %NULL
@@ -764,7 +772,7 @@ _pango_fc_font_set_font_key (PangoFcFont    *fcfont,
  * caching functionality similar to pango_ft2_font_set_glyph_info().
  *
  * Since: 1.6
- **/
+ */
 void
 pango_fc_font_get_raw_extents (PangoFcFont    *fcfont,
                               PangoGlyph      glyph,
@@ -1033,7 +1041,7 @@ done:
 
 /**
  * pango_fc_font_get_languages:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  *
  * Returns the languages that are supported by @font.
  *
@@ -1043,7 +1051,7 @@ done:
  * and its fontmap are valid.
  *
  * Returns: (transfer none) (nullable): a %NULL-terminated
- *    array of PangoLanguage*
+ *    array of `PangoLanguage`*
  *
  * Since: 1.48
  */
@@ -1065,7 +1073,7 @@ pango_fc_font_get_languages (PangoFcFont *font)
 
 /**
  * pango_fc_font_get_pattern: (skip)
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  *
  * Returns the FcPattern that @font is based on.
  *
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index 25157dfe..c3fee67a 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -25,7 +25,7 @@
  * @title:PangoFcFontMap
  * @see_also: #PangoFcFont
  *
- * PangoFcFontMap is a base class for font map implementations using the
+ * `PangoFcFontMap` is a base class for font map implementations using the
  * Fontconfig and FreeType libraries. It is used in the Xft and FreeType
  * backends shipped with Pango, but can also be used when creating
  * new backends. Any backend deriving from this base class will
@@ -496,7 +496,7 @@ pango_fc_fontset_key_copy (const PangoFcFontsetKey *old)
  * Returns: the language
  *
  * Since: 1.24
- **/
+ */
 PangoLanguage *
 pango_fc_fontset_key_get_language (const PangoFcFontsetKey *key)
 {
@@ -512,7 +512,7 @@ pango_fc_fontset_key_get_language (const PangoFcFontsetKey *key)
  * Returns: the font description, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 const PangoFontDescription *
 pango_fc_fontset_key_get_description (const PangoFcFontsetKey *key)
 {
@@ -528,9 +528,9 @@ pango_fc_fontset_key_get_description (const PangoFcFontsetKey *key)
  * Returns: the matrix, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 const PangoMatrix *
-pango_fc_fontset_key_get_matrix      (const PangoFcFontsetKey *key)
+pango_fc_fontset_key_get_matrix (const PangoFcFontsetKey *key)
 {
   return &key->matrix;
 }
@@ -539,15 +539,15 @@ pango_fc_fontset_key_get_matrix      (const PangoFcFontsetKey *key)
  * pango_fc_fontset_key_get_absolute_size:
  * @key: the fontset key
  *
- * Gets the absolute font size of @key in Pango units.  This is adjusted
- * for both resolution and transformation matrix.
+ * Gets the absolute font size of @key in Pango units.
+ * This is adjusted for both resolution and transformation matrix.
  *
  * Returns: the pixel size of @key.
  *
  * Since: 1.24
- **/
+ */
 double
-pango_fc_fontset_key_get_absolute_size   (const PangoFcFontsetKey *key)
+pango_fc_fontset_key_get_absolute_size (const PangoFcFontsetKey *key)
 {
   return key->pixelsize;
 }
@@ -561,9 +561,9 @@ pango_fc_fontset_key_get_absolute_size   (const PangoFcFontsetKey *key)
  * Returns: the resolution of @key
  *
  * Since: 1.24
- **/
+ */
 double
-pango_fc_fontset_key_get_resolution  (const PangoFcFontsetKey *key)
+pango_fc_fontset_key_get_resolution (const PangoFcFontsetKey *key)
 {
   return key->resolution;
 }
@@ -577,7 +577,7 @@ pango_fc_fontset_key_get_resolution  (const PangoFcFontsetKey *key)
  * Returns: the context key, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 gpointer
 pango_fc_fontset_key_get_context_key (const PangoFcFontsetKey *key)
 {
@@ -684,7 +684,7 @@ pango_fc_font_key_init (PangoFcFontKey    *key,
  * Returns: the pattern, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 const FcPattern *
 pango_fc_font_key_get_pattern (const PangoFcFontKey *key)
 {
@@ -700,7 +700,7 @@ pango_fc_font_key_get_pattern (const PangoFcFontKey *key)
  * Returns: the matrix, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 const PangoMatrix *
 pango_fc_font_key_get_matrix (const PangoFcFontKey *key)
 {
@@ -716,7 +716,7 @@ pango_fc_font_key_get_matrix (const PangoFcFontKey *key)
  * Returns: the context key, which is owned by @key and should not be modified.
  *
  * Since: 1.24
- **/
+ */
 gpointer
 pango_fc_font_key_get_context_key (const PangoFcFontKey *key)
 {
@@ -1254,21 +1254,21 @@ pango_fc_font_map_class_init (PangoFcFontMapClass *class)
 
 /**
  * pango_fc_font_map_add_decoder_find_func:
- * @fcfontmap: The #PangoFcFontMap to add this method to.
- * @findfunc: The #PangoFcDecoderFindFunc callback function
+ * @fcfontmap: The `PangoFcFontMap` to add this method to.
+ * @findfunc: The `PangoFcDecoderFindFunc` callback function
  * @user_data: User data.
- * @dnotify: A #GDestroyNotify callback that will be called when the
- *  fontmap is finalized and the decoder is released.
+ * @dnotify: A `GDestroyNotify` callback that will be called when the
+ *   fontmap is finalized and the decoder is released.
  *
- * This function saves a callback method in the #PangoFcFontMap that
- * will be called whenever new fonts are created.  If the
- * function returns a #PangoFcDecoder, that decoder will be used to
- * determine both coverage via a #FcCharSet and a one-to-one mapping of
- * characters to glyphs.  This will allow applications to have
- * application-specific encodings for various fonts.
+ * This function saves a callback method in the `PangoFcFontMap` that
+ * will be called whenever new fonts are created. If the function returns
+ * a `PangoFcDecoder`, that decoder will be used to determine both coverage
+ * via a `FcCharSet` and a one-to-one mapping of characters to glyphs. This
+ * will allow applications to have application-specific encodings for various
+ * fonts.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_fc_font_map_add_decoder_find_func (PangoFcFontMap        *fcfontmap,
                                         PangoFcDecoderFindFunc findfunc,
@@ -1293,20 +1293,20 @@ pango_fc_font_map_add_decoder_find_func (PangoFcFontMap        *fcfontmap,
 
 /**
  * pango_fc_font_map_find_decoder:
- * @fcfontmap: The #PangoFcFontMap to use.
- * @pattern: The #FcPattern to find the decoder for.
+ * @fcfontmap: The `PangoFcFontMap` to use.
+ * @pattern: The `FcPattern` to find the decoder for.
  *
- * Finds the decoder to use for @pattern.  Decoders can be added to
- * a font map using pango_fc_font_map_add_decoder_find_func().
+ * Finds the decoder to use for @pattern. Decoders can be added to
+ * a font map using [method@PangoFc.FontMap.add_decoder_find_func].
  *
- * Returns: (transfer full) (nullable): a newly created #PangoFcDecoder
+ * Returns: (transfer full) (nullable): a newly created `PangoFcDecoder`
  *   object or %NULL if no decoder is set for @pattern.
  *
  * Since: 1.26
- **/
+ */
 PangoFcDecoder *
-pango_fc_font_map_find_decoder  (PangoFcFontMap *fcfontmap,
-                                FcPattern      *pattern)
+pango_fc_font_map_find_decoder (PangoFcFontMap *fcfontmap,
+                                FcPattern      *pattern)
 {
   GSList *l;
 
@@ -1992,7 +1992,7 @@ pango_fc_font_map_load_fontset (PangoFontMap                 *fontmap,
 
 /**
  * pango_fc_font_map_cache_clear:
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
  *
  * Clear all cached information and fontsets for this font map;
  * this should be called whenever there is a change in the
@@ -2001,7 +2001,7 @@ pango_fc_font_map_load_fontset (PangoFontMap                 *fontmap,
  * configuration.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_fc_font_map_cache_clear (PangoFcFontMap *fcfontmap)
 {
@@ -2032,15 +2032,15 @@ pango_fc_font_map_changed (PangoFontMap *fontmap)
 
 /**
  * pango_fc_font_map_config_changed:
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
  *
- * Informs font map that the fontconfig configuration (ie, FcConfig object)
- * used by this font map has changed.  This currently calls
- * pango_fc_font_map_cache_clear() which ensures that list of fonts, etc
- * will be regenerated using the updated configuration.
+ * Informs font map that the fontconfig configuration (i.e., FcConfig
+ * object) used by this font map has changed. This currently calls
+ * [method@PangoFc.FontMap.cache_clear] which ensures that list of fonts,
+ * etc will be regenerated using the updated configuration.
  *
  * Since: 1.38
- **/
+ */
 void
 pango_fc_font_map_config_changed (PangoFcFontMap *fcfontmap)
 {
@@ -2049,26 +2049,26 @@ pango_fc_font_map_config_changed (PangoFcFontMap *fcfontmap)
 
 /**
  * pango_fc_font_map_set_config: (skip)
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
  * @fcconfig: (nullable): a `FcConfig`, or %NULL
  *
- * Set the FcConfig for this font map to use.  The default value
+ * Set the FcConfig for this font map to use. The default value
  * is %NULL, which causes Fontconfig to use its global "current config".
  * You can create a new FcConfig object and use this API to attach it
  * to a font map.
  *
  * This is particularly useful for example, if you want to use application
- * fonts with Pango.  For that, you would create a fresh FcConfig, add your
+ * fonts with Pango. For that, you would create a fresh FcConfig, add your
  * app fonts to it, and attach it to a new Pango font map.
  *
  * If @fcconfig is different from the previous config attached to the font map,
  * pango_fc_font_map_config_changed() is called.
  *
  * This function acquires a reference to the FcConfig object; the caller
- * does NOT need to retain a reference.
+ * does **not** need to retain a reference.
  *
  * Since: 1.38
- **/
+ */
 void
 pango_fc_font_map_set_config (PangoFcFontMap *fcfontmap,
                              FcConfig       *fcconfig)
@@ -2093,17 +2093,17 @@ pango_fc_font_map_set_config (PangoFcFontMap *fcfontmap,
 
 /**
  * pango_fc_font_map_get_config: (skip)
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
  *
  * Fetches the `FcConfig` attached to a font map.
  *
- * See also: pango_fc_font_map_set_config()
+ * See also: [method@PangoFc.FontMap.set_config].
  *
- * Returns: (nullable): the `FcConfig` object attached to @fcfontmap, which
- *          might be %NULL.
+ * Returns: (nullable): the `FcConfig` object attached to
+ *   @fcfontmap, which might be %NULL.
  *
  * Since: 1.38
- **/
+ */
 FcConfig *
 pango_fc_font_map_get_config (PangoFcFontMap *fcfontmap)
 {
@@ -2248,13 +2248,13 @@ _pango_fc_font_map_get_coverage (PangoFcFontMap *fcfontmap,
 
 /**
  * _pango_fc_font_map_fc_to_coverage:
- * @charset: #FcCharSet to convert to a #PangoCoverage object.
+ * @charset: `FcCharSet` to convert to a `PangoCoverage` object.
  *
- * Convert the given #FcCharSet into a new #PangoCoverage object.  The
- * caller is responsible for freeing the newly created object.
+ * Convert the given `FcCharSet` into a new `PangoCoverage` object.
+ * The caller is responsible for freeing the newly created object.
  *
  * Since: 1.6
- **/
+ */
 PangoCoverage  *
 _pango_fc_font_map_fc_to_coverage (FcCharSet *charset)
 {
@@ -2317,22 +2317,24 @@ _pango_fc_font_map_get_languages (PangoFcFontMap *fcfontmap,
 
   return data->languages;
 }
+
 /**
  * pango_fc_font_map_create_context:
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
+ *
+ * Creates a new context for this fontmap.
  *
- * Creates a new context for this fontmap. This function is intended
- * only for backend implementations deriving from #PangoFcFontMap;
- * it is possible that a backend will store additional information
- * needed for correct operation on the #PangoContext after calling
- * this function.
+ * This function is intended only for backend implementations deriving
+ * from `PangoFcFontMap`; it is possible that a backend will store
+ * additional information needed for correct operation on the `PangoContext`
+ * after calling this function.
  *
- * Return value: (transfer full): a new #PangoContext
+ * Return value: (transfer full): a new `PangoContext`
  *
  * Since: 1.4
  *
  * Deprecated: 1.22: Use pango_font_map_create_context() instead.
- **/
+ */
 PangoContext *
 pango_fc_font_map_create_context (PangoFcFontMap *fcfontmap)
 {
@@ -2354,17 +2356,17 @@ shutdown_font (gpointer        key,
 
 /**
  * pango_fc_font_map_shutdown:
- * @fcfontmap: a #PangoFcFontMap
+ * @fcfontmap: a `PangoFcFontMap`
  *
  * Clears all cached information for the fontmap and marks
  * all fonts open for the fontmap as dead. (See the shutdown()
- * virtual function of #PangoFcFont.) This function might be used
+ * virtual function of `PangoFcFont`.) This function might be used
  * by a backend when the underlying windowing system for the font
  * map exits. This function is only intended to be called
- * only for backend implementations deriving from #PangoFcFontMap.
+ * only for backend implementations deriving from `PangoFcFontMap`.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_fc_font_map_shutdown (PangoFcFontMap *fcfontmap)
 {
@@ -2450,21 +2452,21 @@ pango_fc_convert_width_to_pango (int fc_stretch)
 
 /**
  * pango_fc_font_description_from_pattern:
- * @pattern: a #FcPattern
+ * @pattern: a `FcPattern`
  * @include_size: if %TRUE, the pattern will include the size from
  *   the @pattern; otherwise the resulting pattern will be unsized.
  *   (only %FC_SIZE is examined, not %FC_PIXEL_SIZE)
  *
- * Creates a #PangoFontDescription that matches the specified
+ * Creates a `PangoFontDescription` that matches the specified
  * Fontconfig pattern as closely as possible. Many possible Fontconfig
  * pattern values, such as %FC_RASTERIZER or %FC_DPI, don't make sense in
- * the context of #PangoFontDescription, so will be ignored.
+ * the context of `PangoFontDescription`, so will be ignored.
  *
- * Return value: a new #PangoFontDescription. Free with
- *  pango_font_description_free().
+ * Return value: a new `PangoFontDescription`. Free with
+ *   pango_font_description_free().
  *
  * Since: 1.4
- **/
+ */
 PangoFontDescription *
 pango_fc_font_description_from_pattern (FcPattern *pattern, gboolean include_size)
 {
@@ -3091,12 +3093,13 @@ pango_fc_family_init (PangoFcFamily *fcfamily)
 
 /**
  * pango_fc_font_map_get_hb_face: (skip)
- * @fcfontmap: a #PangoFcFontMap
- * @fcfont: a #PangoFcFont
+ * @fcfontmap: a `PangoFcFontMap`
+ * @fcfont: a `PangoFcFont`
  *
- * Retrieves the `hb_face_t` for the given #PangoFcFont.
+ * Retrieves the `hb_face_t` for the given `PangoFcFont`.
  *
- * Returns: (transfer none) (nullable): the `hb_face_t` for the given Pango font
+ * Returns: (transfer none) (nullable): the `hb_face_t`
+ *   for the given font
  *
  * Since: 1.44
  */