summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthias Clasen <mclasen@redhat.com>2021-02-22 00:26:52 -0500
committerMatthias Clasen <mclasen@redhat.com>2021-03-11 13:17:37 -0500
commit7632435e937d2c921e6eb96d40cfde55bd3d9500 (patch)
tree50fd5835bd513d784b199234c553d62e5b003d28
parent5ac7f03b8195d2d4d0c2893b1284029132a9af10 (diff)
downloadpango-7632435e937d2c921e6eb96d40cfde55bd3d9500.tar.gz
pangofc: Tweak docs
Convert link syntax and add summaries.
-rw-r--r--pango/pangofc-decoder.c34
-rw-r--r--pango/pangofc-decoder.h21
-rw-r--r--pango/pangofc-font.c30
-rw-r--r--pango/pangofc-font.h15
-rw-r--r--pango/pangofc-fontmap.c81
-rw-r--r--pango/pangofc-fontmap.h83
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"