From 7632435e937d2c921e6eb96d40cfde55bd3d9500 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 22 Feb 2021 00:26:52 -0500 Subject: 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 de2f61e2..358b33fb 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 @@ -550,6 +548,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. @@ -1482,11 +1481,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 */ @@ -1517,8 +1517,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. @@ -2216,8 +2218,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. @@ -2257,9 +2260,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 */ @@ -2274,19 +2279,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 @@ -2497,6 +2504,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 @@ -2605,11 +2613,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 */ @@ -2704,9 +2715,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" -- cgit v1.2.1