[pango/gi-docs: 27/28] pangofc: Tweak docs

From: Matthias Clasen <matthiasc src gnome org>
To: commits-list gnome org
Cc:
Subject: [pango/gi-docs: 27/28] pangofc: Tweak docs
Date: Mon, 22 Feb 2021 05:32:03 +0000 (UTC)

commit 3b513dd2f136b50e25cbedd4c117abb4ccd2d4f9
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Feb 22 00:26:52 2021 -0500

    pangofc: Tweak docs
    
    Convert link syntax and add summaries.

 pango/pangofc-decoder.c | 34 +++++++++-----------
 pango/pangofc-decoder.h | 21 +++++++------
 pango/pangofc-font.c    | 30 +++++++-----------
 pango/pangofc-font.h    | 15 ++++-----
 pango/pangofc-fontmap.c | 81 +++++++++++++++++++++++++++--------------------
 pango/pangofc-fontmap.h | 83 ++++++++++++++++++++++++++++---------------------
 6 files changed, 139 insertions(+), 125 deletions(-)
---
diff --git a/pango/pangofc-decoder.c b/pango/pangofc-decoder.c
index 7af4cdfc..0d3b00a0 100644
--- a/pango/pangofc-decoder.c
+++ b/pango/pangofc-decoder.c
@@ -19,14 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:pangofc-decoder
- * @short_description:Custom font encoding handling
- * @title:PangoFcDecoder
- *
- * PangoFcDecoder represents a decoder that an application provides
- * for handling a font that is encoded in a custom way.
- */
 #include "config.h"
 #include "pangofc-decoder.h"
 
@@ -44,15 +36,17 @@ pango_fc_decoder_class_init (PangoFcDecoderClass *klass G_GNUC_UNUSED)
 
 /**
  * pango_fc_decoder_get_charset:
- * @decoder: a #PangoFcDecoder
- * @fcfont: the #PangoFcFont to query.
+ * @decoder: a `PangoFcDecoder`
+ * @fcfont: the `PangoFcFont` to query.
  *
- * Generates an #FcCharSet of supported characters for the fcfont
- * given.  The returned #FcCharSet will be a reference to an
- * internal value stored by the #PangoFcDecoder and must not
+ * Generates an `FcCharSet` of supported characters for the @fcfont
+ * given.
+ *
+ * The returned `FcCharSet` will be a reference to an
+ * internal value stored by the `PangoFcDecoder` and must not
  * be modified or freed.
  *
- * Returns: (transfer none): the #FcCharset for @fcfont; must not
+ * Returns: (transfer none): the `FcCharset` for @fcfont; must not
  *   be modified or freed.
  *
  * Since: 1.6
@@ -68,12 +62,14 @@ pango_fc_decoder_get_charset (PangoFcDecoder *decoder,
 
 /**
  * pango_fc_decoder_get_glyph:
- * @decoder: a #PangoFcDecoder
- * @fcfont: a #PangoFcFont to query.
- * @wc: the Unicode code point to convert to a single #PangoGlyph.
+ * @decoder: a `PangoFcDecoder`
+ * @fcfont: a `PangoFcFont` to query.
+ * @wc: the Unicode code point to convert to a single `PangoGlyph`.
+ *
+ * Generates a `PangoGlyph` for the given Unicode point using the
+ * custom decoder.
  *
- * Generates a #PangoGlyph for the given Unicode point using the
- * custom decoder. For complex scripts where there can be multiple
+ * For complex scripts where there can be multiple
  * glyphs for a single character, the decoder will return whatever
  * glyph is most convenient for it. (Usually whatever glyph is directly
  * in the fonts character map table.)
diff --git a/pango/pangofc-decoder.h b/pango/pangofc-decoder.h
index 7c78958c..65f89a59 100644
--- a/pango/pangofc-decoder.h
+++ b/pango/pangofc-decoder.h
@@ -48,13 +48,14 @@ typedef struct _PangoFcDecoderClass PangoFcDecoderClass;
 /**
  * PangoFcDecoder:
  *
- * #PangoFcDecoder is a virtual base class that implementations will
- * inherit from.  It's the interface that is used to define a custom
- * encoding for a font.  These objects are created in your code from a
- * function callback that was originally registered with
- * pango_fc_font_map_add_decoder_find_func().  Pango requires
- * information about the supported charset for a font as well as the
- * individual character to glyph conversions.  Pango gets that
+ * `PangoFcDecoder` is a virtual base class that implementations will
+ * inherit from.
+ *
+ * It's the interface that is used to define a custom encoding for a font.
+ * These objects are created in your code from a function callback that was
+ * originally registered with [method@PangoFc.FcFontMap.add_decoder_find_func].
+ * Pango requires information about the supported charset for a font as well
+ * as the individual character to glyph conversions. Pango gets that
  * information via the #get_charset and #get_glyph callbacks into your
  * object implementation.
  *
@@ -68,16 +69,16 @@ struct _PangoFcDecoder
 
 /**
  * PangoFcDecoderClass:
- * @get_charset: This returns an #FcCharset given a #PangoFcFont that
+ * @get_charset: This returns an `FcCharset` given a `PangoFcFont` that
  *  includes a list of supported characters in the font.  The
  *  #FcCharSet that is returned should be an internal reference to your
  *  code.  Pango will not free this structure.  It is important that
  *  you make this callback fast because this callback is called
  *  separately for each character to determine Unicode coverage.
- * @get_glyph: This returns a single #PangoGlyph for a given Unicode
+ * @get_glyph: This returns a single `PangoGlyph` for a given Unicode
  *  code point.
  *
- * Class structure for #PangoFcDecoder.
+ * Class structure for `PangoFcDecoder`.
  *
  * Since: 1.6
  **/
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index d8616537..5a164343 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -19,19 +19,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/**
- * SECTION:pangofc-font
- * @short_description:Base font class for Fontconfig-based backends
- * @title:PangoFcFont
- * @see_also: #PangoFcFontMap
- *
- * `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
- * will take advantage of the wide range of shapers implemented using
- * FreeType that come with Pango.
- */
 #include "config.h"
 
 #include "pangofc-font-private.h"
@@ -542,7 +529,8 @@ pango_fc_font_real_get_glyph (PangoFcFont *font,
  * pango_fc_font_lock_face: (skip)
  * @font: a `PangoFcFont`.
  *
- * Gets the FreeType `FT_Face` associated with a font,
+ * Gets the FreeType `FT_Face` associated with a font.
+ *
  * This face will be kept around until you call
  * [method PangoFc Font.unlock_face].
  *
@@ -613,8 +601,10 @@ 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 [method PangoFc 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.
@@ -716,6 +706,7 @@ _pango_fc_font_get_decoder (PangoFcFont *font)
  * @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.
  *
  * Since: 1.6
@@ -761,9 +752,10 @@ _pango_fc_font_set_font_key (PangoFcFont    *fcfont,
  * @logical_rect: (out) (optional): location to store logical extents
  *   of the glyph or %NULL
  *
- * Gets the extents of a single glyph from a font. The extents are in
- * user space; that is, they are not transformed by any matrix in effect
- * for the font.
+ * Gets the extents of a single glyph from a font.
+ *
+ * The extents are in user space; that is, they are not transformed
+ * by any matrix in effect for the font.
  *
  * Long term, this functionality probably belongs in the default
  * implementation of the get_glyph_extents() virtual function.
diff --git a/pango/pangofc-font.h b/pango/pangofc-font.h
index fbae5e10..b4aa399e 100644
--- a/pango/pangofc-font.h
+++ b/pango/pangofc-font.h
@@ -60,13 +60,14 @@ typedef struct _PangoFcFontClass PangoFcFontClass;
 /**
  * PangoFcFont:
  *
- * #PangoFcFont is a base class for font implementations
- * using the Fontconfig and FreeType libraries and is used in
- * conjunction with #PangoFcFontMap. When deriving from this
- * class, you need to implement all of its virtual functions
- * other than shutdown() along with the get_glyph_extents()
- * virtual function from #PangoFont.
- **/
+ * `PangoFcFont` is a base class for font implementations
+ * using the Fontconfig and FreeType libraries.
+ *
+ * It is used in onjunction with [class@PangoFc.FontMap].
+ * When deriving from this class, you need to implement all
+ * of its virtual functions other than shutdown() along with
+ * the get_glyph_extents() virtual function from `PangoFont`.
+ */
 struct _PangoFcFont
 {
   PangoFont parent_instance;
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index c3fee67a..cc2ec548 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -20,17 +20,15 @@
  */
 
 /**
- * SECTION:pangofc-fontmap
- * @short_description:Base fontmap class for Fontconfig-based backends
- * @title:PangoFcFontMap
- * @see_also: #PangoFcFont
+ * PangoFcFontMap:
  *
  * `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
- * take advantage of the wide range of shapers implemented using
- * FreeType that come with Pango.
+ * 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 take advantage of the wide
+ * range of shapers implemented using FreeType that come with Pango.
  */
 #define FONTSET_CACHE_SIZE 256
 
@@ -540,6 +538,7 @@ pango_fc_fontset_key_get_matrix (const PangoFcFontsetKey *key)
  * @key: the fontset key
  *
  * 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.
@@ -1261,11 +1260,12 @@ pango_fc_font_map_class_init (PangoFcFontMapClass *class)
  *   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.
+ * 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
  */
@@ -1296,8 +1296,10 @@ pango_fc_font_map_add_decoder_find_func (PangoFcFontMap        *fcfontmap,
  * @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 [method@PangoFc.FontMap.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`
  *   object or %NULL if no decoder is set for @pattern.
@@ -1994,8 +1996,9 @@ pango_fc_font_map_load_fontset (PangoFontMap                 *fontmap,
  * pango_fc_font_map_cache_clear:
  * @fcfontmap: a `PangoFcFontMap`
  *
- * Clear all cached information and fontsets for this font map;
- * this should be called whenever there is a change in the
+ * Clear all cached information and fontsets for this font map.
+ *
+ * This should be called whenever there is a change in the
  * output of the default_substitute() virtual function of the
  * font map, or if fontconfig has been reinitialized to new
  * configuration.
@@ -2035,9 +2038,11 @@ pango_fc_font_map_changed (PangoFontMap *fontmap)
  * @fcfontmap: a `PangoFcFontMap`
  *
  * 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.
+ * 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
  */
@@ -2052,19 +2057,21 @@ pango_fc_font_map_config_changed (PangoFcFontMap *fcfontmap)
  * @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
+ * 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.
+ * [method@PangoFc.FontMap.config_changed] is called.
  *
- * This function acquires a reference to the FcConfig object; the caller
+ * This function acquires a reference to the `FcConfig` object; the caller
  * does **not** need to retain a reference.
  *
  * Since: 1.38
@@ -2251,6 +2258,7 @@ _pango_fc_font_map_get_coverage (PangoFcFontMap *fcfontmap,
  * @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.
  *
  * Since: 1.6
@@ -2359,11 +2367,14 @@ shutdown_font (gpointer        key,
  * @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
- * 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`.
+ * all fonts open for the fontmap as dead.
+ *
+ * See the shutdown() 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`.
  *
  * Since: 1.4
  */
@@ -2458,9 +2469,11 @@ pango_fc_convert_width_to_pango (int fc_stretch)
  *   (only %FC_SIZE is examined, not %FC_PIXEL_SIZE)
  *
  * 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.
+ * 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.
  *
  * Return value: a new `PangoFontDescription`. Free with
  *   pango_font_description_free().
diff --git a/pango/pangofc-fontmap.h b/pango/pangofc-fontmap.h
index 6fdf32d2..8ae9250e 100644
--- a/pango/pangofc-fontmap.h
+++ b/pango/pangofc-fontmap.h
@@ -69,10 +69,11 @@ pango_fc_font_map_get_config (PangoFcFontMap *fcfontmap);
 
 /**
  * PangoFcDecoderFindFunc:
- * @pattern: a fully resolved #FcPattern specifying the font on the system
- * @user_data: user data passed to pango_fc_font_map_add_decoder_find_func()
+ * @pattern: a fully resolved `FcPattern` specifying the font on the system
+ * @user_data: user data passed to
+ *   [method@PangoFc.FontMap.add_decoder_find_func]
  *
- * Callback function passed to pango_fc_font_map_add_decoder_find_func().
+ * Callback function passed to [method@PangoFc.FontMap.add_decoder_find_func].
  *
  * Return value: a new reference to a custom decoder for this pattern,
  *  or %NULL if the default decoder handling should be used.
@@ -110,22 +111,24 @@ hb_face_t * pango_fc_font_map_get_hb_face (PangoFcFontMap *fcfontmap,
  * @pattern: the FcPattern to tweak.
  * @data: user data.
  *
- * Function type for doing final config tweaking on prepared FcPatterns.
+ * Function type for doing final config tweaking on prepared `FcPattern`s.
  */
 typedef void (*PangoFcSubstituteFunc) (FcPattern *pattern,
                                       gpointer   data);
 
 /**
  * pango_fc_font_map_set_default_substitute:
- * @fontmap: a #PangoFcFontMap
+ * @fontmap: a `PangoFcFontMap`
  * @func: function to call to to do final config tweaking
- *        on #FcPattern objects.
+ *        on `FcPattern` objects.
  * @data: data to pass to @func
  * @notify: function to call when @data is no longer used.
  *
  * Sets a function that will be called to do final configuration
- * substitution on a #FcPattern before it is used to load
- * the font. This function can be used to do things like set
+ * substitution on a `FcPattern` before it is used to load
+ * the font.
+ *
+ * This function can be used to do things like set
  * hinting and antialiasing options.
  *
  * Since: 1.48
@@ -138,11 +141,12 @@ void pango_fc_font_map_set_default_substitute (PangoFcFontMap        *fontmap,
 
 /**
  * pango_fc_font_map_substitute_changed:
- * @fontmap: a #PangoFcFontMap
+ * @fontmap: a `PangoFcFontMap`
+ *
+ * Call this function any time the results of the default
+ * substitution function set with
+ * [method@PangoFc.FontMap.set_default_substitute] change.
  *
- * Call this function any time the results of the
- * default substitution function set with
- * pango_fc_font_map_set_default_substitute() change.
  * That is, if your substitution function will return different
  * results for the same input pattern, you must call this function.
  *
@@ -154,13 +158,15 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_GRAVITY:
  *
- * String representing a fontconfig property name that Pango sets on any
- * fontconfig pattern it passes to fontconfig if a #PangoGravity other
- * than %PANGO_GRAVITY_SOUTH is desired.
+ * Fontconfig property that Pango sets on any
+ * fontconfig pattern it passes to fontconfig
+ * if a `PangoGravity` other than %PANGO_GRAVITY_SOUTH
+ * is desired.
  *
- * The property will have a #PangoGravity value as a string, like "east".
- * This can be used to write fontconfig configuration rules to choose
- * different fonts for horizontal and vertical writing directions.
+ * The property will have a `PangoGravity` value as a string,
+ * like "east". This can be used to write fontconfig configuration
+ * rules to choose different fonts for horizontal and vertical
+ * writing directions.
  *
  * Since: 1.20
  */
@@ -169,13 +175,13 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_VERSION:
  *
- * String representing a fontconfig property name that Pango sets on any
+ * Fontconfig property that Pango sets on any
  * fontconfig pattern it passes to fontconfig.
  *
  * The property will have an integer value equal to what
- * pango_version() returns.
- * This can be used to write fontconfig configuration rules that only affect
- * certain pango versions (or only pango-using applications, or only
+ * [func@Pango.version] returns. This can be used to write
+ * fontconfig configuration rules that only affect certain
+ * pango versions (or only pango-using applications, or only
  * non-pango-using applications).
  *
  * Since: 1.20
@@ -185,15 +191,16 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_PRGNAME:
  *
- * String representing a fontconfig property name that Pango sets on any
+ * Fontconfig property that Pango sets on any
  * fontconfig pattern it passes to fontconfig.
  *
  * The property will have a string equal to what
- * g_get_prgname() returns.
- * This can be used to write fontconfig configuration rules that only affect
+ * g_get_prgname() returns. This can be used to write
+ * fontconfig configuration rules that only affect
  * certain applications.
  *
- * This is equivalent to FC_PRGNAME in versions of fontconfig that have that.
+ * This is equivalent to FC_PRGNAME in versions of
+ * fontconfig that have that.
  *
  * Since: 1.24
  */
@@ -202,14 +209,16 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_FONT_FEATURES:
  *
- * String representing a fontconfig property name that Pango reads from font
- * patterns to populate list of OpenType features to be enabled for the font
- * by default.
+ * Fontconfig property that Pango reads from font
+ * patterns to populate list of OpenType features
+ * to be enabled for the font by default.
  *
- * The property will have a number of string elements, each of which is the
- * OpenType feature tag of one feature to enable.
+ * The property will have a number of string elements,
+ * each of which is the OpenType feature tag of one feature
+ * to enable.
  *
- * This is equivalent to FC_FONT_FEATURES in versions of fontconfig that have that.
+ * This is equivalent to FC_FONT_FEATURES in versions of
+ * fontconfig that have that.
  *
  * Since: 1.34
  */
@@ -218,11 +227,13 @@ void pango_fc_font_map_substitute_changed (PangoFcFontMap *fontmap);
 /**
  * PANGO_FC_FONT_VARIATIONS:
  *
- * String representing a fontconfig property name that Pango reads from font
- * patterns to populate list of OpenType font variations to be used for a font.
+ * Fontconfig property that Pango reads from font
+ * patterns to populate list of OpenType font variations
+ * to be used for a font.
  *
- * The property will have a string elements, each of which a comma-separated
- * list of OpenType axis setting of the form AXIS=VALUE.
+ * The property will have a string elements, each of which
+ * a comma-separated list of OpenType axis setting of the
+ * form AXIS=VALUE.
  */
 #define PANGO_FC_FONT_VARIATIONS "fontvariations"
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]