summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--CODING_STYLE.md16
-rw-r--r--pango/break.c69
-rw-r--r--pango/ellipsize.c6
-rw-r--r--pango/fonts.c56
-rw-r--r--pango/glyphstring.c79
-rw-r--r--pango/modules.c10
-rw-r--r--pango/pango-attributes.c424
-rw-r--r--pango/pango-attributes.h40
-rw-r--r--pango/pango-bidi-type.c6
-rw-r--r--pango/pango-color.c88
-rw-r--r--pango/pango-context.c10
-rw-r--r--pango/pango-context.h5
-rw-r--r--pango/pango-coverage.c31
-rw-r--r--pango/pango-coverage.h38
-rw-r--r--pango/pango-engine.h40
-rw-r--r--pango/pango-fontmap.c11
-rw-r--r--pango/pango-fontmap.h23
-rw-r--r--pango/pango-fontset.c25
-rw-r--r--pango/pango-fontset.h16
-rw-r--r--pango/pango-glyph-item.c80
-rw-r--r--pango/pango-glyph-item.h12
-rw-r--r--pango/pango-glyph.h17
-rw-r--r--pango/pango-gravity.c8
-rw-r--r--pango/pango-gravity.h29
-rw-r--r--pango/pango-language.c83
-rw-r--r--pango/pango-language.h5
-rw-r--r--pango/pango-layout.c371
-rw-r--r--pango/pango-layout.h6
-rw-r--r--pango/pango-markup.c12
-rw-r--r--pango/pango-matrix.c10
-rw-r--r--pango/pango-matrix.h7
-rw-r--r--pango/pango-modules.h2
-rw-r--r--pango/pango-ot-buffer.c95
-rw-r--r--pango/pango-ot-info.c138
-rw-r--r--pango/pango-ot-private.h10
-rw-r--r--pango/pango-ot-ruleset.c229
-rw-r--r--pango/pango-ot-tag.c26
-rw-r--r--pango/pango-ot.h24
-rw-r--r--pango/pango-renderer.c29
-rw-r--r--pango/pango-renderer.h14
-rw-r--r--pango/pango-script.c43
-rw-r--r--pango/pango-tabs.c8
-rw-r--r--pango/pango-types.h48
-rw-r--r--pango/pango-utils.c102
-rw-r--r--pango/pangocairo-context.c39
-rw-r--r--pango/pangocairo-render.c13
-rw-r--r--pango/pangocoretext.c2
-rw-r--r--pango/pangofc-font-private.h6
-rw-r--r--pango/pangofc-font.c16
-rw-r--r--pango/pangofc-fontmap-private.h14
-rw-r--r--pango/pangofc-fontmap.h5
-rw-r--r--pango/pangoft2-render.c97
-rw-r--r--pango/pangoft2.c57
-rw-r--r--pango/pangowin32-fontcache.c35
-rw-r--r--pango/pangowin32-fontmap.c32
-rw-r--r--pango/pangowin32.c115
-rw-r--r--pango/pangoxft-font.c28
-rw-r--r--pango/pangoxft-fontmap.c12
-rw-r--r--pango/pangoxft-render.c110
-rw-r--r--pango/pangoxft-render.h4
-rw-r--r--pango/pangoxft.h8
-rw-r--r--pango/reorder-items.c6
-rw-r--r--pango/shape.c4
63 files changed, 1531 insertions, 1473 deletions
diff --git a/CODING_STYLE.md b/CODING_STYLE.md
index 25929a78..aa183e5d 100644
--- a/CODING_STYLE.md
+++ b/CODING_STYLE.md
@@ -49,19 +49,19 @@ in the gtk-doc / gnome-doc style. For instance:
/**
* pango_layout_get_line:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
* @line: the index of a line, which must be between 0 and
- * pango_layout_get_line_count(layout) - 1, inclusive.
+ * `pango_layout_get_line_count(layout) - 1`, inclusive.
*
- * Retrieves a particular line from a #PangoLayout (or @layout.)
+ * Retrieves a particular line from a `PangoLayout` (or @layout.)
*
- * Return value: the requested #PangoLayoutLine, or %NULL if the
- * index is out of range. This layout line can
- * be ref'ed and retained, but will become invalid
- * if changes are made to the #PangoLayout.
+ * Return value: the requested `PangoLayoutLine`, or %NULL
+ * if the index is out of range. This layout line can
+ * be ref'ed and retained, but will become invalid
+ * if changes are made to the `PangoLayout`.
*
* Since: 1.6
- **/
+ */
PangoLayoutLine *
pango_layout_get_line (PangoLayout *layout,
int line)
diff --git a/pango/break.c b/pango/break.c
index c34d0512..7d204fa3 100644
--- a/pango/break.c
+++ b/pango/break.c
@@ -143,17 +143,18 @@ typedef enum
* pango_default_break:
* @text: text to break. Must be valid UTF-8
* @length: length of text in bytes (may be -1 if @text is nul-terminated)
- * @analysis: (nullable): a #PangoAnalysis for the @text
+ * @analysis: (nullable): a `PangoAnalysis` structure for the @text
* @attrs: logical attributes to fill in
* @attrs_len: size of the array passed as @attrs
*
* This is the default break algorithm.
*
- * It applies Unicode rules without language-specific tailoring, therefore
- * the @analyis argument is unused and can be %NULL.
+ * It applies Unicode rules without language-specific
+ * tailoring, therefore the @analyis argument is unused
+ * and can be %NULL.
*
- * See pango_tailor_break() for language-specific breaks.
- **/
+ * See [func@Pango.tailor_break] for language-specific breaks.
+ */
void
pango_default_break (const gchar *text,
gint length,
@@ -1617,19 +1618,20 @@ tailor_break (const char *text,
/**
* pango_break:
- * @text: the text to process. Must be valid UTF-8
- * @length: length of @text in bytes (may be -1 if @text is nul-terminated)
- * @analysis: #PangoAnalysis structure from pango_itemize()
- * @attrs: (array length=attrs_len): an array to store character
- * information in
+ * @text: the text to process. Must be valid UTF-8
+ * @length: length of @text in bytes (may be -1 if @text is nul-terminated)
+ * @analysis: `PangoAnalysis` structure for @text
+ * @attrs: (array length=attrs_len): an array to store character information in
* @attrs_len: size of the array passed as @attrs
*
- * Determines possible line, word, and character breaks for a string of
- * Unicode text with a single analysis.
+ * Determines possible line, word, and character breaks
+ * for a string of Unicode text with a single analysis.
*
- * For most purposes you may want to use pango_get_log_attrs().
+ * For most purposes you may want to use
+ * [func@Pango.get_log_attrs].
*
- * Deprecated: 1.44: Use pango_default_break() and pango_tailor_break()
+ * Deprecated: 1.44: Use [func@Pango.default_break] and
+ * [func@Pango.tailor_break]
*/
void
pango_break (const gchar *text,
@@ -1656,15 +1658,18 @@ pango_break (const gchar *text,
*
* Locates a paragraph boundary in @text.
*
- * A boundary is caused by delimiter characters, such as a newline, carriage
- * return, carriage return-newline pair, or Unicode paragraph separator character.
- * The index of the run of delimiters is returned in @paragraph_delimiter_index.
- * The index of the start of the paragrap (index after all delimiters) is stored
+ * A boundary is caused by delimiter characters, such as
+ * a newline, carriage return, carriage return-newline pair,
+ * or Unicode paragraph separator character.
+ *
+ * The index of the run of delimiters is returned in
+ * @paragraph_delimiter_index. The index of the start
+ * of the paragrap (index after all delimiters) is stored
* in @next_paragraph_start.
*
- * If no delimiters are found, both @paragraph_delimiter_index and
- * @next_paragraph_start are filled with the length of @text (an index one
- * off the end).
+ * If no delimiters are found, both @paragraph_delimiter_index
+ * and @next_paragraph_start are filled with the length of @text
+ * (an index one off the end).
*/
void
pango_find_paragraph_boundary (const gchar *text,
@@ -1750,16 +1755,18 @@ pango_find_paragraph_boundary (const gchar *text,
* pango_tailor_break:
* @text: text to process. Must be valid UTF-8
* @length: length in bytes of @text
- * @analysis: `PangoAnalysis` structure from [func@itemize] for @text
+ * @analysis: `PangoAnalysis` for @text
* @offset: Byte offset of @text from the beginning of the
- * paragraph, or -1 to ignore attributes from @analysis
+ * paragraph, or -1 to ignore attributes from @analysis
* @log_attrs: (array length=log_attrs_len): array with one `PangoLogAttr`
* per character in @text, plus one extra, to be filled in
* @log_attrs_len: length of @log_attrs array
*
- * Apply language-specific tailoring to the breaks in @log_attrs.
+ * Apply language-specific tailoring to the breaks
+ * in @log_attrs.
*
- * The line breaks are assumed to have been produced by [func@default_break].
+ * The line breaks are assumed to have been produced
+ * by [func@Pango.default_break].
*
* If @offset is not -1, it is used to apply attributes
* from @analysis that are relevant to line breaking.
@@ -1825,11 +1832,13 @@ tailor_segment (const char *range_start,
*
* Computes a `PangoLogAttr` for each character in @text.
*
- * The @log_attrs array must have one `PangoLogAttr` for each position in @text;
- * if @text contains N characters, it has N+1 positions, including the last
- * position at the end of the text. @text should be an entire paragraph; logical
- * attributes can't be computed without context (for example you need to see
- * spaces on either side of a word to know the word is a word).
+ * The @log_attrs array must have one `PangoLogAttr` for
+ * each position in @text; if @text contains N characters,
+ * it has N+1 positions, including the last position at the
+ * end of the text. @text should be an entire paragraph;
+ * logical attributes can't be computed without context
+ * (for example you need to see spaces on either side of
+ * a word to know the word is a word).
*/
void
pango_get_log_attrs (const char *text,
diff --git a/pango/ellipsize.c b/pango/ellipsize.c
index 0d54483e..e05277f6 100644
--- a/pango/ellipsize.c
+++ b/pango/ellipsize.c
@@ -243,7 +243,7 @@ line_iter_prev_cluster (EllipsizeState *state,
* - Starts a grapheme - checked here
*
* In the future we'd also like to add a check for cursive connectivity here.
- * This should be an addition to #PangoGlyphVisAttr
+ * This should be an addition to `PangoGlyphVisAttr`
*
*/
@@ -735,11 +735,11 @@ current_width (EllipsizeState *state)
/**
* _pango_layout_line_ellipsize:
- * @line: a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
* @attrs: Attributes being used for itemization/shaping
* @shape_flags: Flags to use when shaping
*
- * Given a #PangoLayoutLine with the runs still in logical order, ellipsize
+ * Given a `PangoLayoutLine` with the runs still in logical order, ellipsize
* it according the layout's policy to fit within the set width of the layout.
*
* Return value: whether the line had to be ellipsized
diff --git a/pango/fonts.c b/pango/fonts.c
index b199e785..8f08698c 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -183,7 +183,7 @@ pango_font_description_get_family (const PangoFontDescription *desc)
*
* The [enum@Pango.Style] enumeration describes whether the font is
* slanted and the manner in which it is slanted; it can be either
- * #PANGO_STYLE_NORMAL, #PANGO_STYLE_ITALIC, or #PANGO_STYLE_OBLIQUE.
+ * %PANGO_STYLE_NORMAL, %PANGO_STYLE_ITALIC, or %PANGO_STYLE_OBLIQUE.
*
* Most fonts will either have a italic style or an oblique style,
* but not both, and font matching in Pango will match italic
@@ -644,7 +644,7 @@ pango_font_description_unset_fields (PangoFontDescription *desc,
/**
* pango_font_description_merge:
* @desc: a `PangoFontDescription`
- * @desc_to_merge: (allow-none): the `PangoFontDescription` to merge from,
+ * @desc_to_merge: (nullable): the `PangoFontDescription` to merge from,
* or %NULL
* @replace_existing: if %TRUE, replace fields in @desc with the
* corresponding values from @desc_to_merge, even if they
@@ -766,7 +766,7 @@ compute_distance (const PangoFontDescription *a,
/**
* pango_font_description_better_match:
* @desc: a `PangoFontDescription`
- * @old_match: (allow-none): a `PangoFontDescription`, or %NULL
+ * @old_match: (nullable): a `PangoFontDescription`, or %NULL
* @new_match: a `PangoFontDescription`
*
* Determines if the style attributes of @new_match are a closer match
@@ -984,7 +984,7 @@ pango_font_description_free (PangoFontDescription *desc)
/**
* pango_font_descriptions_free:
- * @descs: (allow-none) (array length=n_descs) (transfer full): a pointer
+ * @descs: (nullable) (array length=n_descs) (transfer full): a pointer
* to an array of `PangoFontDescription`, may be %NULL
* @n_descs: number of font descriptions in @descs
*
@@ -1803,10 +1803,8 @@ pango_font_find_shaper (PangoFont *font,
* pango_font_get_glyph_extents:
* @font: (nullable): a `PangoFont`
* @glyph: the glyph index
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of the glyph
- * as drawn or %NULL to indicate that the result is not needed.
- * @logical_rect: (out) (allow-none): rectangle used to store the logical extents of
- * the glyph or %NULL to indicate that the result is not needed.
+ * @ink_rect: (out) (optional): rectangle used to store the extents of the glyph as drawn
+ * @logical_rect: (out) (optional): rectangle used to store the logical extents of the glyph
*
* Gets the logical and ink extents of a glyph within a font.
*
@@ -1851,7 +1849,7 @@ pango_font_get_glyph_extents (PangoFont *font,
/**
* pango_font_get_metrics:
* @font: (nullable): a `PangoFont`
- * @language: (allow-none): language tag used to determine which script
+ * @language: (nullable): language tag used to determine which script
* to get the metrics for, or %NULL to indicate to get the metrics for
* the entire font.
*
@@ -1893,21 +1891,22 @@ pango_font_get_metrics (PangoFont *font,
/**
* pango_font_get_font_map:
- * @font: (nullable): a `PangoFont`, or %NULL
+ * @font: (nullable): a `PangoFont`
*
* Gets the font map for which the font was created.
*
- * Note that the font maintains a *weak* reference to the font map, so if
- * all references to font map are dropped, the font map will be finalized
- * even if there are fonts created with the font map that are still alive.
+ * Note that the font maintains a *weak* reference to
+ * the font map, so if all references to font map are
+ * dropped, the font map will be finalized even if there
+ * are fonts created with the font map that are still alive.
* In that case this function will return %NULL.
*
- * It is the responsibility of the user to ensure that the font map is kept
- * alive. In most uses this is not an issue as a #PangoContext holds
- * a reference to the font map.
+ * It is the responsibility of the user to ensure that the
+ * font map is kept alive. In most uses this is not an issue
+ * as a `PangoContext` holds a reference to the font map.
*
- * Return value: (transfer none) (nullable): the `PangoFontMap` for the
- * font, or %NULL if @font is %NULL.
+ * Return value: (transfer none) (nullable): the `PangoFontMap`
+ * for the font
*
* Since: 1.10
*/
@@ -1947,11 +1946,12 @@ pango_font_get_face (PangoFont *font)
*
* Get a `hb_font_t` object backing this font.
*
- * Note that the objects returned by this function are cached and immutable.
- * If you need to make changes to the `hb_font_t`, use hb_font_create_sub_font().
+ * Note that the objects returned by this function are cached
+ * and immutable. If you need to make changes to the `hb_font_t`,
+ * use hb_font_create_sub_font().
*
- * Returns: (transfer none) (nullable): the `hb_font_t` object backing the
- * font, or %NULL if the font does not have one
+ * Returns: (transfer none) (nullable): the `hb_font_t` object
+ * backing the font
*
* Since: 1.44
*/
@@ -2311,7 +2311,7 @@ pango_font_family_get_name (PangoFontFamily *family)
/**
* pango_font_family_list_faces:
* @family: a `PangoFontFamily`
- * @faces: (out) (allow-none) (array length=n_faces) (transfer container):
+ * @faces: (out) (optional) (array length=n_faces) (transfer container):
* location to store an array of pointers to `PangoFontFace` objects,
* or %NULL. This array should be freed with g_free() when it is no
* longer needed.
@@ -2369,13 +2369,13 @@ pango_font_family_real_get_face (PangoFontFamily *family,
* pango_font_family_get_face:
* @family: a `PangoFontFamily`
* @name: (nullable): the name of a face. If the name is %NULL,
- * the family's default face (fontconfig calls it "Regular")
- * will be returned.
+ * the family's default face (fontconfig calls it "Regular")
+ * will be returned.
*
* Gets the `PangoFontFace` of @family with the given name.
*
* Returns: (transfer none) (nullable): the `PangoFontFace`,
- * or %NULL if no face with the given name exists.
+ * or %NULL if no face with the given name exists.
*
* Since: 1.46
*/
@@ -2526,8 +2526,8 @@ pango_font_face_get_face_name (PangoFontFace *face)
* pango_font_face_list_sizes:
* @face: a `PangoFontFace`.
* @sizes: (out) (array length=n_sizes) (nullable) (optional):
- * location to store a pointer to an array of int. This array
- * should be freed with g_free().
+ * location to store a pointer to an array of int. This array
+ * should be freed with g_free().
* @n_sizes: location to store the number of elements in @sizes
*
* List the available sizes for a font.
diff --git a/pango/glyphstring.c b/pango/glyphstring.c
index 6c2338f1..f6e59016 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -31,7 +31,7 @@
* Create a new `PangoGlyphString`.
*
* Return value: the newly allocated `PangoGlyphString`, which
- * should be freed with [method@Pango.GlyphString.free].
+ * should be freed with [method@Pango.GlyphString.free].
*/
PangoGlyphString *
pango_glyph_string_new (void)
@@ -48,8 +48,8 @@ pango_glyph_string_new (void)
/**
* pango_glyph_string_set_size:
- * @string: a `PangoGlyphString`.
- * @new_len: the new length of the string.
+ * @string: a `PangoGlyphString`.
+ * @new_len: the new length of the string
*
* Resize a glyph string to the given length.
*/
@@ -97,13 +97,13 @@ G_DEFINE_BOXED_TYPE (PangoGlyphString, pango_glyph_string,
/**
* pango_glyph_string_copy:
- * @string: (nullable): a `PangoGlyphString`, may be %NULL
+ * @string: (nullable): a `PangoGlyphString`
*
* Copy a glyph string and associated storage.
*
- * Return value: (nullable): the newly allocated `PangoGlyphString`,
- * which should be freed with [method@Pango.GlyphString.free],
- * or %NULL if @string was %NULL.
+ * Return value: (nullable): the newly allocated `PangoGlyphString`
+ * which should be freed with [method@Pango.GlyphString.free],
+ * or %NULL if @string was %NULL.
*/
PangoGlyphString *
pango_glyph_string_copy (PangoGlyphString *string)
@@ -144,17 +144,15 @@ pango_glyph_string_free (PangoGlyphString *string)
/**
* pango_glyph_string_extents_range:
- * @glyphs: a `PangoGlyphString`
- * @start: start index
- * @end: end index (the range is the set of bytes with
- indices such that start <= index < end)
- * @font: a `PangoFont`
+ * @glyphs: a `PangoGlyphString`
+ * @start: start index
+ * @end: end index (the range is the set of bytes with
+ * indices such that start <= index < end)
+ * @font: a `PangoFont`
* @ink_rect: (out caller-allocates) (optional): rectangle used to
- * store the extents of the glyph string range as drawn or
- * %NULL to indicate that the result is not needed.
+ * store the extents of the glyph string range as drawn
* @logical_rect: (out caller-allocates) (optional): rectangle used to
- * store the logical extents of the glyph string range or
- * %NULL to indicate that the result is not needed.
+ * store the logical extents of the glyph string range
*
* Computes the extents of a sub-portion of a glyph string.
*
@@ -262,12 +260,10 @@ pango_glyph_string_extents_range (PangoGlyphString *glyphs,
/**
* pango_glyph_string_extents:
- * @glyphs: a `PangoGlyphString`
- * @font: a `PangoFont`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of the glyph string
- * as drawn or %NULL to indicate that the result is not needed.
- * @logical_rect: (out) (allow-none): rectangle used to store the logical extents of the
- * glyph string or %NULL to indicate that the result is not needed.
+ * @glyphs: a `PangoGlyphString`
+ * @font: a `PangoFont`
+ * @ink_rect: (out) (optional): rectangle used to store the extents of the glyph string as drawn
+ * @logical_rect: (out) (optional): rectangle used to store the logical extents of the glyph string
*
* Compute the logical and ink extents of a glyph string.
*
@@ -322,9 +318,8 @@ pango_glyph_string_get_width (PangoGlyphString *glyphs)
* @length: the length of @text, in bytes
* @embedding_level: the embedding level of the string
* @logical_widths: (array): an array whose length is the number of
- * characters in text (equal to g_utf8_strlen (text,
- * length) unless text has NUL bytes) to be filled in
- * with the resulting character widths.
+ * characters in text (equal to `g_utf8_strlen (text, length)` unless
+ * text has `NUL` bytes) to be filled in with the resulting character widths.
*
* Given a `PangoGlyphString` and corresponding text, determine the width
* corresponding to each character.
@@ -363,14 +358,14 @@ pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs,
/**
* pango_glyph_string_index_to_x:
- * @glyphs: the glyphs return from [func@shape]
- * @text: the text for the run
- * @length: the number of bytes (not characters) in @text.
- * @analysis: the analysis information return from [func@itemize]
- * @index_: the byte index within @text
- * @trailing: whether we should compute the result for the beginning (%FALSE)
- * or end (%TRUE) of the character.
- * @x_pos: (out): location to store result
+ * @glyphs: the glyphs return from [func@shape]
+ * @text: the text for the run
+ * @length: the number of bytes (not characters) in @text.
+ * @analysis: the analysis information return from [func@itemize]
+ * @index_: the byte index within @text
+ * @trailing: whether we should compute the result for the beginning (%FALSE)
+ * or end (%TRUE) of the character.
+ * @x_pos: (out): location to store result
*
* Converts from character position to x position.
*
@@ -378,7 +373,6 @@ pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs,
* Character positions are computed by dividing up each cluster
* into equal portions.
*/
-
void
pango_glyph_string_index_to_x (PangoGlyphString *glyphs,
char *text,
@@ -493,15 +487,14 @@ pango_glyph_string_index_to_x (PangoGlyphString *glyphs,
/**
* pango_glyph_string_x_to_index:
- * @glyphs: the glyphs returned from [func@shape]
- * @text: the text for the run
- * @length: the number of bytes (not characters) in text.
- * @analysis: the analysis information return from [func@itemize]
- * @x_pos: the x offset (in Pango units)
- * @index_: (out): location to store calculated byte index within @text
- * @trailing: (out): location to store a boolean indicating
- * whether the user clicked on the leading or trailing
- * edge of the character.
+ * @glyphs: the glyphs returned from [func@shape]
+ * @text: the text for the run
+ * @length: the number of bytes (not characters) in text.
+ * @analysis: the analysis information return from [func@itemize]
+ * @x_pos: the x offset (in Pango units)
+ * @index_: (out): location to store calculated byte index within @text
+ * @trailing: (out): location to store a boolean indicating whether the
+ * user clicked on the leading or trailing edge of the character
*
* Convert from x offset to character position.
*
diff --git a/pango/modules.c b/pango/modules.c
index b7ba105b..4aea37c5 100644
--- a/pango/modules.c
+++ b/pango/modules.c
@@ -45,8 +45,8 @@ pango_find_map (PangoLanguage *language G_GNUC_UNUSED,
/**
* pango_map_get_engine: (skip)
- * @map: a #PangoMap
- * @script: a #PangoScript
+ * @map: a `PangoMap`
+ * @script: a `PangoScript`
*
* Do not use. Does not do anything.
*
@@ -63,8 +63,8 @@ pango_map_get_engine (PangoMap *map G_GNUC_UNUSED,
/**
* pango_map_get_engines: (skip)
- * @map: a #PangoMap
- * @script: a #PangoScript
+ * @map: a `PangoMap`
+ * @script: a `PangoScript`
* @exact_engines: (nullable): location to store list of engines that exactly
* handle this script.
* @fallback_engines: (nullable): location to store list of engines that
@@ -89,7 +89,7 @@ pango_map_get_engines (PangoMap *map G_GNUC_UNUSED,
/**
* pango_module_register: (skip)
- * @module: a #PangoIncludedModule
+ * @module: a `PangoIncludedModule`
*
* Do not use. Does not do anything.
*
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 225dc654..63c031f9 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -49,7 +49,8 @@ static GHashTable *name_map = NULL; /* MT-safe */
*
* Allocate a new attribute type ID.
*
- * The attribute type name can be accessed later by using [type_func@Pango.AttrType.get_name].
+ * The attribute type name can be accessed later
+ * by using [type_func@Pango.AttrType.get_name].
*
* Return value: the new type ID.
*/
@@ -82,14 +83,17 @@ pango_attr_type_register (const gchar *name)
*
* Fetches the attribute type name.
*
- * The attribute type name is the string passed in when registering the type
- * using [type_func@attr_type_register].
+ * The attribute type name is the string passed in
+ * when registering the type using
+ * [type_func@attr_type_register].
*
- * The returned value is an interned string (see g_intern_string() for what
- * that means) that should not be modified or freed.
+ * The returned value is an interned string (see
+ * g_intern_string() for what that means) that should
+ * not be modified or freed.
*
- * Return value: (nullable): the type ID name (which may be %NULL), or
- * %NULL if @type is a built-in Pango attribute type or invalid.
+ * Return value: (nullable): the type ID name (which
+ * may be %NULL), or %NULL if @type is a built-in Pango
+ * attribute type or invalid.
*
* Since: 1.22
*/
@@ -138,8 +142,9 @@ pango_attribute_init (PangoAttribute *attr,
*
* Make a copy of an attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy].
*/
PangoAttribute *
pango_attribute_copy (const PangoAttribute *attr)
@@ -178,11 +183,13 @@ G_DEFINE_BOXED_TYPE (PangoAttribute, pango_attribute,
* @attr1: a `PangoAttribute`
* @attr2: another `PangoAttribute`
*
- * Compare two attributes for equality. This compares only the
- * actual value of the two attributes and not the ranges that the
- * attributes apply to.
+ * Compare two attributes for equality.
+ *
+ * This compares only the actual value of the two
+ * attributes and not the ranges that the attributes
+ * apply to.
*
- * Return value: %TRUE if the two attributes have the same value.
+ * Return value: %TRUE if the two attributes have the same value
*/
gboolean
pango_attribute_equal (const PangoAttribute *attr1,
@@ -232,12 +239,13 @@ pango_attr_string_new (const PangoAttrClass *klass,
/**
* pango_attr_family_new:
- * @family: the family or comma separated list of families
+ * @family: the family or comma-separated list of families
*
* Create a new font family attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_family_new (const char *family)
@@ -281,8 +289,9 @@ pango_attr_language_equal (const PangoAttribute *attr1,
*
* Create a new language tag attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_language_new (PangoLanguage *language)
@@ -357,8 +366,9 @@ pango_attr_color_new (const PangoAttrClass *klass,
*
* Create a new foreground color attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_foreground_new (guint16 red,
@@ -383,8 +393,9 @@ pango_attr_foreground_new (guint16 red,
*
* Create a new background color attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_background_new (guint16 red,
@@ -533,12 +544,13 @@ pango_attr_size_new_internal (int size,
/**
* pango_attr_size_new:
- * @size: the font size, in %PANGO_SCALEths of a point.
+ * @size: the font size, in %PANGO_SCALE-ths of a point
*
* Create a new font-size attribute in fractional points.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_size_new (int size)
@@ -548,12 +560,13 @@ pango_attr_size_new (int size)
/**
* pango_attr_size_new_absolute:
- * @size: the font size, in %PANGO_SCALEths of a device unit.
+ * @size: the font size, in %PANGO_SCALE-ths of a device unit
*
* Create a new font-size attribute in device units.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.8
*/
@@ -569,8 +582,9 @@ pango_attr_size_new_absolute (int size)
*
* Create a new font slant style attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_style_new (PangoStyle style)
@@ -591,8 +605,9 @@ pango_attr_style_new (PangoStyle style)
*
* Create a new font weight attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_weight_new (PangoWeight weight)
@@ -635,8 +650,9 @@ pango_attr_variant_new (PangoVariant variant)
*
* Create a new font stretch attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_stretch_new (PangoStretch stretch)
@@ -689,8 +705,9 @@ pango_attr_font_desc_equal (const PangoAttribute *attr1,
* This attribute allows setting family, style, weight, variant,
* stretch, and size simultaneously.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_font_desc_new (const PangoFontDescription *desc)
@@ -712,12 +729,13 @@ pango_attr_font_desc_new (const PangoFontDescription *desc)
/**
* pango_attr_underline_new:
- * @underline: the underline style.
+ * @underline: the underline style
*
* Create a new underline-style attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_underline_new (PangoUnderline underline)
@@ -740,11 +758,12 @@ pango_attr_underline_new (PangoUnderline underline)
*
* Create a new underline color attribute.
*
- * This attribute modifies the color of underlines. If not set, underlines
- * will use the foreground color.
+ * This attribute modifies the color of underlines.
+ * If not set, underlines will use the foreground color.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.8
*/
@@ -765,12 +784,13 @@ pango_attr_underline_color_new (guint16 red,
/**
* pango_attr_strikethrough_new:
- * @strikethrough: %TRUE if the text should be struck-through.
+ * @strikethrough: %TRUE if the text should be struck-through
*
* Create a new strike-through attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_strikethrough_new (gboolean strikethrough)
@@ -793,11 +813,12 @@ pango_attr_strikethrough_new (gboolean strikethrough)
*
* Create a new strikethrough color attribute.
*
- * This attribute modifies the color of strikethrough lines. If not set,
- * strikethrough lines will use the foreground color.
+ * This attribute modifies the color of strikethrough lines.
+ * If not set, strikethrough lines will use the foreground color.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.8
*/
@@ -823,8 +844,9 @@ pango_attr_strikethrough_color_new (guint16 red,
*
* Create a new baseline displacement attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_rise_new (int rise)
@@ -845,11 +867,12 @@ pango_attr_rise_new (int rise)
*
* Create a new font size scale attribute.
*
- * The base font for the affected text will have its size multiplied
- * by @scale_factor.
+ * The base font for the affected text will have
+ * its size multiplied by @scale_factor.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute*
pango_attr_scale_new (double scale_factor)
@@ -867,17 +890,18 @@ pango_attr_scale_new (double scale_factor)
/**
* pango_attr_fallback_new:
* @enable_fallback: %TRUE if we should fall back on other fonts
- * for characters the active font is missing.
+ * for characters the active font is missing
*
* Create a new font fallback attribute.
*
- * If fallback is disabled, characters will only be used from the
- * closest matching font on the system. No fallback will be done to
- * other fonts on the system that might contain the characters in the
- * text.
+ * If fallback is disabled, characters will only be
+ * used from the closest matching font on the system.
+ * No fallback will be done to other fonts on the system
+ * that might contain the characters in the text.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.4
*/
@@ -896,13 +920,14 @@ pango_attr_fallback_new (gboolean enable_fallback)
/**
* pango_attr_letter_spacing_new:
- * @letter_spacing: amount of extra space to add between graphemes
- * of the text, in Pango units.
+ * @letter_spacing: amount of extra space to add between
+ * graphemes of the text, in Pango units
*
* Create a new letter-spacing attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.6
*/
@@ -968,18 +993,21 @@ pango_attr_shape_equal (const PangoAttribute *attr1,
* @ink_rect: ink rectangle to assign to each character
* @logical_rect: logical rectangle to assign to each character
* @data: user data pointer
- * @copy_func: (allow-none): function to copy @data when the
- * attribute is copied. If %NULL, @data is simply copied as a pointer.
- * @destroy_func: (allow-none): function to free @data when the
- * attribute is freed, or %NULL
+ * @copy_func: (nullable): function to copy @data when the
+ * attribute is copied. If %NULL, @data is simply copied
+ * as a pointer
+ * @destroy_func: (nullable): function to free @data when the
+ * attribute is freed
*
* Creates a new shape attribute.
*
- * Like pango_attr_shape_new(), but a user data pointer is also
- * provided; this pointer can be accessed when later rendering the glyph.
+ * Like [ctor@Pango.AttrShape.new], but a user data pointer
+ * is also provided; this pointer can be accessed when later
+ * rendering the glyph.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.8
*/
@@ -1020,12 +1048,14 @@ pango_attr_shape_new_with_data (const PangoRectangle *ink_rect,
*
* Create a new shape attribute.
*
- * A shape is used to impose a particular ink and logical rectangle
- * on the result of shaping a particular glyph. This might be used,
- * for instance, for embedding a picture or a widget inside a `PangoLayout`.
+ * A shape is used to impose a particular ink and logical
+ * rectangle on the result of shaping a particular glyph.
+ * This might be used, for instance, for embedding a picture
+ * or a widget inside a `PangoLayout`.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*/
PangoAttribute *
pango_attr_shape_new (const PangoRectangle *ink_rect,
@@ -1040,12 +1070,13 @@ pango_attr_shape_new (const PangoRectangle *ink_rect,
/**
* pango_attr_gravity_new:
- * @gravity: the gravity value; should not be %PANGO_GRAVITY_AUTO.
+ * @gravity: the gravity value; should not be %PANGO_GRAVITY_AUTO
*
* Create a new gravity attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.16
*/
@@ -1066,12 +1097,13 @@ pango_attr_gravity_new (PangoGravity gravity)
/**
* pango_attr_gravity_hint_new:
- * @hint: the gravity hint value.
+ * @hint: the gravity hint value
*
* Create a new gravity hint attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.16
*/
@@ -1094,8 +1126,9 @@ pango_attr_gravity_hint_new (PangoGravityHint hint)
*
* Create a new font features tag attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.38
*/
@@ -1120,8 +1153,9 @@ pango_attr_font_features_new (const gchar *features)
*
* Create a new foreground alpha attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.38
*/
@@ -1144,8 +1178,9 @@ pango_attr_foreground_alpha_new (guint16 alpha)
*
* Create a new background alpha attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.38
*/
@@ -1171,8 +1206,9 @@ pango_attr_background_alpha_new (guint16 alpha)
* If breaks are disabled, the range will be kept in a
* single run, as far as possible.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.44
*/
@@ -1195,11 +1231,13 @@ pango_attr_allow_breaks_new (gboolean allow_breaks)
*
* Create a new insert-hyphens attribute.
*
- * Pango will insert hyphens when breaking lines in the middle
- * of a word. This attribute can be used to suppress the hyphen.
+ * Pango will insert hyphens when breaking lines in
+ * the middle of a word. This attribute can be used
+ * to suppress the hyphen.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.44
*/
@@ -1223,8 +1261,9 @@ pango_attr_insert_hyphens_new (gboolean insert_hyphens)
* Create a new attribute that influences how invisible
* characters are rendered.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.44
**/
@@ -1247,8 +1286,9 @@ pango_attr_show_new (PangoShowFlags flags)
*
* Create a new overline-style attribute.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.46
*/
@@ -1273,11 +1313,12 @@ pango_attr_overline_new (PangoOverline overline)
*
* Create a new overline color attribute.
*
- * This attribute modifies the color of overlines. If not set, overlines
- * will use the foreground color.
+ * This attribute modifies the color of overlines.
+ * If not set, overlines will use the foreground color.
*
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- * which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
*
* Since: 1.46
*/
@@ -1314,10 +1355,12 @@ _pango_attr_list_init (PangoAttrList *list)
/**
* pango_attr_list_new:
*
- * Create a new empty attribute list with a reference count of one.
+ * Create a new empty attribute list with a reference
+ * count of one.
*
- * Return value: (transfer full): the newly allocated `PangoAttrList`,
- * which should be freed with [method@Pango.AttrList.unref].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttrList`, which should be freed with
+ * [method@Pango.AttrList.unref]
*/
PangoAttrList *
pango_attr_list_new (void)
@@ -1331,9 +1374,10 @@ pango_attr_list_new (void)
/**
* pango_attr_list_ref:
- * @list: (nullable): a `PangoAttrList`, may be %NULL
+ * @list: (nullable): a `PangoAttrList`
*
- * Increase the reference count of the given attribute list by one.
+ * Increase the reference count of the given attribute
+ * list by one.
*
* Return value: The attribute list passed in
*
@@ -1370,11 +1414,13 @@ _pango_attr_list_destroy (PangoAttrList *list)
/**
* pango_attr_list_unref:
- * @list: (nullable): a `PangoAttrList`, may be %NULL
+ * @list: (nullable): a `PangoAttrList`
*
- * Decrease the reference count of the given attribute list by one.
- * If the result is zero, free the attribute list and the attributes
- * it contains.
+ * Decrease the reference count of the given attribute
+ * list by one.
+ *
+ * If the result is zero, free the attribute list
+ * and the attributes it contains.
*/
void
pango_attr_list_unref (PangoAttrList *list)
@@ -1393,13 +1439,14 @@ pango_attr_list_unref (PangoAttrList *list)
/**
* pango_attr_list_copy:
- * @list: (nullable): a `PangoAttrList`, may be %NULL
+ * @list: (nullable): a `PangoAttrList`
*
* Copy @list and return an identical new list.
*
- * Return value: (nullable): the newly allocated `PangoAttrList`,
- * with a reference count of one, which should be freed with
- * [method@Pango.AttrList.unref]. Returns %NULL if @list was %NULL.
+ * Return value: (nullable): the newly allocated
+ * `PangoAttrList`, with a reference count of one,
+ * which should be freed with [method@Pango.AttrList.unref].
+ * Returns %NULL if @list was %NULL.
*/
PangoAttrList *
pango_attr_list_copy (PangoAttrList *list)
@@ -1465,8 +1512,7 @@ pango_attr_list_insert_internal (PangoAttrList *list,
/**
* pango_attr_list_insert:
* @list: a `PangoAttrList`
- * @attr: (transfer full): the attribute to insert. Ownership of this
- * value is assumed by the list.
+ * @attr: (transfer full): the attribute to insert
*
* Insert the given attribute into the `PangoAttrList`.
*
@@ -1486,8 +1532,7 @@ pango_attr_list_insert (PangoAttrList *list,
/**
* pango_attr_list_insert_before:
* @list: a `PangoAttrList`
- * @attr: (transfer full): the attribute to insert. Ownership of this
- * value is assumed by the list.
+ * @attr: (transfer full): the attribute to insert
*
* Insert the given attribute into the `PangoAttrList`.
*
@@ -1507,18 +1552,19 @@ pango_attr_list_insert_before (PangoAttrList *list,
/**
* pango_attr_list_change:
* @list: a `PangoAttrList`
- * @attr: (transfer full): the attribute to insert. Ownership of this
- * value is assumed by the list.
+ * @attr: (transfer full): the attribute to insert
*
* Insert the given attribute into the `PangoAttrList`.
*
- * It will replace any attributes of the same type on that segment
- * and be merged with any adjoining attributes that are identical.
+ * It will replace any attributes of the same type
+ * on that segment and be merged with any adjoining
+ * attributes that are identical.
*
- * This function is slower than [method@Pango.AttrList.insert] for
- * creating an attribute list in order (potentially much slower for
- * large lists). However, [method@Pango.AttrList.insert] is not
- * suitable for continually changing a set of attributes since it
+ * This function is slower than [method@Pango.AttrList.insert]
+ * for creating an attribute list in order (potentially
+ * much slower for large lists). However,
+ * [method@Pango.AttrList.insert] is not suitable for
+ * continually changing a set of attributes since it
* never removes or combines existing attributes.
*/
void
@@ -1748,8 +1794,9 @@ pango_attr_list_update (PangoAttrList *list,
* must be specified since the attributes in @other may only
* be present at some subsection of this range)
*
- * This function opens up a hole in @list, fills it in with attributes
- * from the left, and then merges @other on top of the hole.
+ * This function opens up a hole in @list, fills it
+ * in with attributes from the left, and then merges
+ * @other on top of the hole.
*
* This operation is equivalent to stretching every attribute
* that applies at position @pos in @list by an amount @len,
@@ -1831,9 +1878,9 @@ pango_attr_list_splice (PangoAttrList *list,
* Gets a list of all attributes in @list.
*
* Return value: (element-type Pango.Attribute) (transfer full):
- * a list of all attributes in @list. To free this value, call
- * [mehod@Pango.Attribute.destroy] on each value and g_slist_free()
- * on the list.
+ * a list of all attributes in @list. To free this value,
+ * call [mehod@Pango.Attribute.destroy] on each value and
+ * g_slist_free() on the list.
*
* Since: 1.44
*/
@@ -1863,11 +1910,15 @@ pango_attr_list_get_attributes (PangoAttrList *list)
* @list: a `PangoAttrList`
* @other_list: the other `PangoAttrList`
*
- * Checks whether @list and @other_list contain the same attributes and
- * whether those attributes apply to the same ranges. Beware that this
- * will return wrong values if any list contains duplicates.
+ * Checks whether @list and @other_list contain the same
+ * attributes and whether those attributes apply to the
+ * same ranges.
+ *
+ * Beware that this will return wrong values if any list
+ * contains duplicates.
*
- * Return value: %TRUE if the lists are equal, %FALSE if they aren't.
+ * Return value: %TRUE if the lists are equal, %FALSE if
+ * they aren't
*
* Since: 1.46
*/
@@ -1958,11 +2009,13 @@ _pango_attr_list_get_iterator (PangoAttrList *list,
* @list: a `PangoAttrList`
*
* Create a iterator initialized to the beginning of the list.
+ *
* @list must not be modified until this iterator is freed.
*
- * Return value: (transfer full): the newly allocated `PangoAttrIterator`,
- * which should be freed with [method@Pango.AttrIterator.destroy].
- **/
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttrIterator`, which should be freed with
+ * [method@Pango.AttrIterator.destroy]
+ */
PangoAttrIterator *
pango_attr_list_get_iterator (PangoAttrList *list)
{
@@ -1978,13 +2031,14 @@ pango_attr_list_get_iterator (PangoAttrList *list)
/**
* pango_attr_iterator_range:
- * @iterator: a #PangoAttrIterator
+ * @iterator: a PangoAttrIterator
* @start: (out): location to store the start of the range
* @end: (out): location to store the end of the range
*
- * Get the range of the current segment. Note that the
- * stored return values are signed, not unsigned like
- * the values in `PangoAttribute`. To deal with this API
+ * Get the range of the current segment.
+ *
+ * Note that the stored return values are signed, not unsigned
+ * like the values in `PangoAttribute`. To deal with this API
* oversight, stored return values that wouldn't fit into
* a signed integer are clamped to %G_MAXINT.
*/
@@ -2007,8 +2061,8 @@ pango_attr_iterator_range (PangoAttrIterator *iterator,
*
* Advance the iterator until the next change of style.
*
- * Return value: %FALSE if the iterator is at the end of the list,
- * otherwise %TRUE
+ * Return value: %FALSE if the iterator is at the end
+ * of the list, otherwise %TRUE
*/
gboolean
pango_attr_iterator_next (PangoAttrIterator *iterator)
@@ -2078,8 +2132,9 @@ pango_attr_iterator_next (PangoAttrIterator *iterator)
*
* Copy a `PangoAttrIterator`.
*
- * Return value: (transfer full): the newly allocated `PangoAttrIterator`,
- * which should be freed with [method@Pango.AttrIterator.destroy].
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttrIterator`, which should be freed with
+ * [method@Pango.AttrIterator.destroy]
*/
PangoAttrIterator *
pango_attr_iterator_copy (PangoAttrIterator *iterator)
@@ -2127,14 +2182,16 @@ pango_attr_iterator_destroy (PangoAttrIterator *iterator)
* @iterator: a `PangoAttrIterator`
* @type: the type of attribute to find
*
- * Find the current attribute of a particular type at the iterator
- * location. When multiple attributes of the same type overlap,
- * the attribute whose range starts closest to the current location
- * is used.
+ * Find the current attribute of a particular type
+ * at the iterator location.
*
- * Return value: (nullable) (transfer none): the current attribute of
- * the given type, or %NULL if no attribute of that type applies to
- * the current location.
+ * When multiple attributes of the same type overlap,
+ * the attribute whose range starts closest to the
+ * current location is used.
+ *
+ * Return value: (nullable) (transfer none): the current
+ * attribute of the given type, or %NULL if no attribute
+ * of that type applies to the current location.
*/
PangoAttribute *
pango_attr_iterator_get (PangoAttrIterator *iterator,
@@ -2161,21 +2218,24 @@ pango_attr_iterator_get (PangoAttrIterator *iterator,
/**
* pango_attr_iterator_get_font:
* @iterator: a `PangoAttrIterator`
- * @desc: a `PangoFontDescription` to fill in with the current values.
- * The family name in this structure will be set using
- * [method@Pango.FontDescription.set_family_static] using values from
- * an attribute in the `PangoAttrList` associated with the iterator,
- * so if you plan to keep it around, you must call:
- * pango_font_description_set_family (desc, pango_font_description_get_family (desc)).
- * @language: (allow-none): if non-%NULL, location to store language tag
+ * @desc: a `PangoFontDescription` to fill in with the current
+ * values. The family name in this structure will be set using
+ * [method@Pango.FontDescription.set_family_static] using
+ * values from an attribute in the `PangoAttrList` associated
+ * with the iterator, so if you plan to keep it around, you
+ * must call:
+ * `pango_font_description_set_family (desc, pango_font_description_get_family (desc))`.
+ * @language: (out) (optional): location to store language tag
* for item, or %NULL if none is found.
- * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full):
- * if non-%NULL, location in which to store a list of non-font attributes
- * at the the current position; only the highest priority value of each
- * attribute will be added to this list. In order to free this value, you
- * must call [method@Pango.Attribute.destroy] on each member.
- *
- * Get the font and other attributes at the current iterator position.
+ * @extra_attrs: (out) (optional) (element-type Pango.Attribute) (transfer full):
+ * location in which to store a list of non-font attributes
+ * at the the current position; only the highest priority
+ * value of each attribute will be added to this list. In
+ * order to free this value, you must call
+ * [method@Pango.Attribute.destroy] on each member.
+ *
+ * Get the font and other attributes at the current
+ * iterator position.
*/
void
pango_attr_iterator_get_font (PangoAttrIterator *iterator,
@@ -2324,15 +2384,17 @@ pango_attr_iterator_get_font (PangoAttrIterator *iterator,
/**
* pango_attr_list_filter:
* @list: a `PangoAttrList`
- * @func: (scope call) (closure data): callback function; returns %TRUE
- * if an attribute should be filtered out.
+ * @func: (scope call) (closure data): callback function;
+ * returns %TRUE if an attribute should be filtered out
* @data: (closure): Data to be passed to @func
*
- * Given a `PangoAttrList` and callback function, removes any elements
- * of @list for which @func returns %TRUE and inserts them into a new list.
+ * Given a `PangoAttrList` and callback function, removes
+ * any elements of @list for which @func returns %TRUE and
+ * inserts them into a new list.
*
- * Return value: (transfer full) (nullable): the new `PangoAttrList` or
- * %NULL if no attributes of the given types were found.
+ * Return value: (transfer full) (nullable): the new
+ * `PangoAttrList` or %NULL if no attributes of the
+ * given types were found
*
* Since: 1.2
*/
@@ -2381,9 +2443,9 @@ pango_attr_list_filter (PangoAttrList *list,
* iterator.
*
* Return value: (element-type Pango.Attribute) (transfer full):
- * a list of all attributes for the current range. To free this value,
- * call [method@Pango.Attribute.destroy] on each value and g_slist_free()
- * on the list.
+ * a list of all attributes for the current range. To free
+ * this value, call [method@Pango.Attribute.destroy] on each
+ * value and g_slist_free() on the list.
*
* Since: 1.2
*/
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index db8d8262..d841d715 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -209,28 +209,28 @@ typedef enum
* @PANGO_UNDERLINE_SINGLE: a single underline should be drawn
* @PANGO_UNDERLINE_DOUBLE: a double underline should be drawn
* @PANGO_UNDERLINE_LOW: a single underline should be drawn at a
- * position beneath the ink extents of the text being
- * underlined. This should be used only for underlining
- * single characters, such as for keyboard accelerators.
- * %PANGO_UNDERLINE_SINGLE should be used for extended
- * portions of text.
+ * position beneath the ink extents of the text being
+ * underlined. This should be used only for underlining
+ * single characters, such as for keyboard accelerators.
+ * %PANGO_UNDERLINE_SINGLE should be used for extended
+ * portions of text.
* @PANGO_UNDERLINE_ERROR: an underline indicating an error should
- * be drawn below. The exact style of rendering is up to the
- * `PangoRenderer` in use, but typical styles include wavy
- * or dotted lines.
- * This underline is typically used to indicate an error such
- * as a possible mispelling; in some cases a contrasting color
- * may automatically be used. This type of underlining is
- * available since Pango 1.4.
+ * be drawn below. The exact style of rendering is up to the
+ * `PangoRenderer` in use, but typical styles include wavy
+ * or dotted lines.
+ * This underline is typically used to indicate an error such
+ * as a possible mispelling; in some cases a contrasting color
+ * may automatically be used. This type of underlining is
+ * available since Pango 1.4.
* @PANGO_UNDERLINE_SINGLE_LINE: Like @PANGO_UNDERLINE_SINGLE, but
- * drawn continuously across multiple runs. This type
- * of underlining is available since Pango 1.46.
+ * drawn continuously across multiple runs. This type
+ * of underlining is available since Pango 1.46.
* @PANGO_UNDERLINE_DOUBLE_LINE: Like @PANGO_UNDERLINE_DOUBLE, but
- * drawn continuously across multiple runs. This type
- * of underlining is available since Pango 1.46.
+ * drawn continuously across multiple runs. This type
+ * of underlining is available since Pango 1.46.
* @PANGO_UNDERLINE_ERROR_LINE: Like @PANGO_UNDERLINE_ERROR, but
- * drawn continuously across multiple runs. This type
- * of underlining is available since Pango 1.46.
+ * drawn continuously across multiple runs. This type
+ * of underlining is available since Pango 1.46.
*
* The `PangoUnderline` enumeration is used to specify whether text
* should be underlined, and if so, the type of underlining.
@@ -251,7 +251,7 @@ typedef enum {
* PangoOverline:
* @PANGO_OVERLINE_NONE: no overline should be drawn
* @PANGO_OVERLINE_SINGLE: Draw a single line above the ink
- * extents of the text being underlined.
+ * extents of the text being underlined.
*
* The `PangoOverline` enumeration is used to specify whether text
* should be overlined, and if so, the type of line.
@@ -596,7 +596,7 @@ PangoAttribute *pango_attr_overline_color_new (guint16 red,
* @PANGO_SHOW_SPACES: Render spaces, tabs and newlines visibly
* @PANGO_SHOW_LINE_BREAKS: Render line breaks visibly
* @PANGO_SHOW_IGNORABLES: Render default-ignorable Unicode
- * characters visibly
+ * characters visibly
*
* These flags affect how Pango treats characters that are normally
* not visible in the output.
diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c
index 01da86d3..e85b23e8 100644
--- a/pango/pango-bidi-type.c
+++ b/pango/pango-bidi-type.c
@@ -91,9 +91,9 @@ pango_bidi_type_for_unichar (gunichar ch)
/**
* pango_log2vis_get_embedding_levels:
- * @text: the text to itemize.
- * @length: the number of bytes (not characters) to process, or -1
- * if @text is nul-terminated and the length should be calculated.
+ * @text: the text to itemize.
+ * @length: the number of bytes (not characters) to process, or -1
+ * if @text is nul-terminated and the length should be calculated.
* @pbase_dir: input base direction, and output resolved direction.
*
* Return the bidirectional embedding levels of the input paragraph.
diff --git a/pango/pango-color.c b/pango/pango-color.c
index f616e1f0..b6907035 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -34,18 +34,18 @@ G_DEFINE_BOXED_TYPE (PangoColor, pango_color,
/**
* pango_color_copy:
- * @src: (nullable): color to copy, may be %NULL
+ * @src: (nullable): color to copy
*
* Creates a copy of @src.
*
- * The copy should be freed with pango_color_free(). Primarily
- * used by language bindings, not that useful otherwise (since
- * colors can just be copied by assignment in C).
+ * The copy should be freed with [method@Pango.Color.free].
+ * Primarily used by language bindings, not that useful
+ * otherwise (since colors can just be copied by assignment
+ * in C).
*
- * Return value: (nullable): the newly allocated `PangoColor`, which
- * should be freed with [method@Pango.Color.free], or %NULL if
- * @src was %NULL.
- **/
+ * Return value: (nullable): the newly allocated `PangoColor`,
+ * which should be freed with [method@Pango.Color.free]
+ */
PangoColor*
pango_color_copy (const PangoColor *src)
{
@@ -63,10 +63,10 @@ pango_color_copy (const PangoColor *src)
/**
* pango_color_free:
- * @color: (nullable): an allocated #PangoColor, may be %NULL
+ * @color: (nullable): an allocated `PangoColor`
*
- * Frees a color allocated by pango_color_copy().
- **/
+ * Frees a color allocated by [ctor@Pango.copy].
+ */
void
pango_color_free (PangoColor *color)
{
@@ -78,18 +78,19 @@ pango_color_free (PangoColor *color)
/**
* pango_color_to_string:
- * @color: a #PangoColor
+ * @color: a `PangoColor`
*
* Returns a textual specification of @color.
*
- * The string is in the hexadecimal form `#rrrrggggbbbb`, where
- * `r`, `g` and `b` are hex digits representing the red, green,
- * and blue components respectively.
+ * The string is in the hexadecimal form `#rrrrggggbbbb`,
+ * where `r`, `g` and `b` are hex digits representing the
+ * red, green, and blue components respectively.
*
- * Return value: a newly-allocated text string that must be freed with g_free().
+ * Return value: a newly-allocated text string that must
+ * be freed with g_free().
*
* Since: 1.16
- **/
+ */
gchar *
pango_color_to_string (const PangoColor *color)
{
@@ -211,27 +212,29 @@ hex (const char *spec,
/**
* pango_color_parse_with_alpha:
- * @color: (nullable): a `PangoColor` structure in which to store the
- * result, or %NULL
- * @alpha: (out) (optional): return location for alpha, or %NULL
+ * @color: (nullable): a `PangoColor` structure in which
+ * to store the result
+ * @alpha: (out) (optional): return location for alpha
* @spec: a string specifying the new color
*
* Fill in the fields of a color from a string specification.
*
- * The string can
- * either one of a large set of standard names. (Taken from the CSS Color
- * [specification](https://www.w3.org/TR/css-color-4/#named-colors),
- * or it can be a hexadecimal value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb`
- * or `#rrrrggggbbbb` where `r`, `g` and `b` are hex digits of the red, green,
- * and blue components of the color, respectively. (White in the four
- * forms is `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.)
+ * The string can either one of a large set of standard names.
+ * (Taken from the CSS Color [specification](https://www.w3.org/TR/css-color-4/#named-colors),
+ * or it can be a hexadecimal value in the form `#rgb`,
+ * `#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb` where `r`, `g`
+ * and `b` are hex digits of the red, green, and blue components
+ * of the color, respectively. (White in the four forms is
+ * `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.)
*
* Additionally, parse strings of the form `#rgba`, `#rrggbbaa`,
- * `#rrrrggggbbbbaaaa`, if @alpha is not %NULL, and set @alpha to the value
- * specified by the hex digits for `a`. If no alpha component is found
- * in @spec, @alpha is set to 0xffff (for a solid color).
+ * `#rrrrggggbbbbaaaa`, if @alpha is not %NULL, and set @alpha
+ * to the value specified by the hex digits for `a`. If no alpha
+ * component is found in @spec, @alpha is set to 0xffff (for a
+ * solid color).
*
- * Return value: %TRUE if parsing of the specifier succeeded, otherwise false.
+ * Return value: %TRUE if parsing of the specifier succeeded,
+ * otherwise %FALSE
*
* Since: 1.46
*/
@@ -320,22 +323,23 @@ pango_color_parse_with_alpha (PangoColor *color,
/**
* pango_color_parse:
- * @color: (nullable): a `PangoColor` structure in which to store the
- * result, or %NULL
+ * @color: (nullable): a `PangoColor` structure in which
+ * to store the result
* @spec: a string specifying the new color
*
* Fill in the fields of a color from a string specification.
*
- * The string can either
- * one of a large set of standard names. (Taken from the CSS Color
- * [specification](https://www.w3.org/TR/css-color-4/#named-colors), or it can be
- * a value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb`, where
- * `r`, `g` and `b` are hex digits of the red, green, and blue components of the
- * color, respectively. (White in the four forms is `#fff`, `#ffffff`, `#fffffffff`
- * and `#ffffffffffff`.)
+ * The string can either one of a large set of standard names.
+ * (Taken from the CSS Color [specification](https://www.w3.org/TR/css-color-4/#named-colors),
+ * or it can be a value in the form `#rgb`, `#rrggbb`,
+ * `#rrrgggbbb` or `#rrrrggggbbbb`, where `r`, `g` and `b`
+ * are hex digits of the red, green, and blue components
+ * of the color, respectively. (White in the four forms is
+ * `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.)
*
- * Return value: %TRUE if parsing of the specifier succeeded, otherwise false.
- **/
+ * Return value: %TRUE if parsing of the specifier succeeded,
+ * otherwise %FALSE
+ */
gboolean
pango_color_parse (PangoColor *color,
const char *spec)
diff --git a/pango/pango-context.c b/pango/pango-context.c
index d1e447f7..0db09459 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -169,7 +169,7 @@ update_resolved_gravity (PangoContext *context)
/**
* pango_context_set_matrix:
* @context: a `PangoContext`
- * @matrix: (allow-none): a `PangoMatrix`, or %NULL to unset any existing
+ * @matrix: (nullable): a `PangoMatrix`, or %NULL to unset any existing
* matrix. (No matrix set is the same as setting the identity matrix.)
*
* Sets the transformation matrix that will be applied when rendering
@@ -1549,7 +1549,7 @@ itemize_state_finish (ItemizeState *state)
* @length: the number of bytes (not characters) to process
* after @start_index. This must be >= 0.
* @attrs: the set of attributes that apply to @text.
- * @cached_iter: (allow-none): Cached attribute iterator, or %NULL
+ * @cached_iter: (nullable): Cached attribute iterator, or %NULL
*
* Like `pango_itemize()`, but with an explicitly specified base direction.
*
@@ -1627,7 +1627,7 @@ itemize_with_font (PangoContext *context,
* @length: the number of bytes (not characters) to process
* after @start_index. This must be >= 0.
* @attrs: the set of attributes that apply to @text.
- * @cached_iter: (allow-none): Cached attribute iterator, or %NULL
+ * @cached_iter: (nullable): Cached attribute iterator, or %NULL
*
* Breaks a piece of text into segments with consistent directional
* level and font.
@@ -1749,9 +1749,9 @@ update_metrics_from_items (PangoFontMetrics *metrics,
/**
* pango_context_get_metrics:
* @context: a `PangoContext`
- * @desc: (allow-none): a `PangoFontDescription` structure. %NULL means that the
+ * @desc: (nullable): a `PangoFontDescription` structure. %NULL means that the
* font description from the context will be used.
- * @language: (allow-none): language tag used to determine which script to get
+ * @language: (nullable): language tag used to determine which script to get
* the metrics for. %NULL means that the language tag from the context
* will be used. If no language tag is set on the context, metrics
* for the default language (as determined by [type_func@Pango.Language.get_default]
diff --git a/pango/pango-context.h b/pango/pango-context.h
index 0f775ff4..b44bd623 100644
--- a/pango/pango-context.h
+++ b/pango/pango-context.h
@@ -119,11 +119,6 @@ void pango_context_set_round_glyph_positions (PangoContext
PANGO_AVAILABLE_IN_1_44
gboolean pango_context_get_round_glyph_positions (PangoContext *context);
-
-/* Break a string of Unicode characters into segments with
- * consistent shaping/language engine and bidrectional level.
- * Returns a #GList of #PangoItem's
- */
PANGO_AVAILABLE_IN_ALL
GList *pango_itemize (PangoContext *context,
const char *text,
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index ebd258b2..0bc6187b 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -109,11 +109,10 @@ pango_coverage_class_init (PangoCoverageClass *class)
*
* Create a new `PangoCoverage`
*
- * Return value: the newly allocated `PangoCoverage`,
- * initialized to %PANGO_COVERAGE_NONE
- * with a reference count of one, which
- * should be freed with pango_coverage_unref().
- **/
+ * Return value: the newly allocated `PangoCoverage`, initialized
+ * to %PANGO_COVERAGE_NONE with a reference count of one, which
+ * should be freed with [method@Pango.Coverage.unref].
+ */
PangoCoverage *
pango_coverage_new (void)
{
@@ -127,9 +126,9 @@ pango_coverage_new (void)
* Copy an existing `PangoCoverage`.
*
* Return value: (transfer full): the newly allocated `PangoCoverage`,
- * with a reference count of one, which should be freed
- * with pango_coverage_unref().
- **/
+ * with a reference count of one, which should be freed with
+ * [method@Pango.Coverage.unref].
+ */
PangoCoverage *
pango_coverage_copy (PangoCoverage *coverage)
{
@@ -143,7 +142,7 @@ pango_coverage_copy (PangoCoverage *coverage)
* Increase the reference count on the `PangoCoverage` by one.
*
* Return value: (transfer full): @coverage
- **/
+ */
PangoCoverage *
pango_coverage_ref (PangoCoverage *coverage)
{
@@ -157,7 +156,7 @@ pango_coverage_ref (PangoCoverage *coverage)
* Decrease the reference count on the `PangoCoverage` by one.
*
* If the result is zero, free the coverage and all associated memory.
- **/
+ */
void
pango_coverage_unref (PangoCoverage *coverage)
{
@@ -172,7 +171,7 @@ pango_coverage_unref (PangoCoverage *coverage)
* Determine whether a particular index is covered by @coverage.
*
* Return value: the coverage level of @coverage for character @index_.
- **/
+ */
PangoCoverageLevel
pango_coverage_get (PangoCoverage *coverage,
int index)
@@ -187,7 +186,7 @@ pango_coverage_get (PangoCoverage *coverage,
* @level: the new level for @index_
*
* Modify a particular index within @coverage
- **/
+ */
void
pango_coverage_set (PangoCoverage *coverage,
int index,
@@ -206,7 +205,7 @@ pango_coverage_set (PangoCoverage *coverage,
* the corresponding index in @other.
*
* Deprecated: 1.44: This function does nothing
- **/
+ */
void
pango_coverage_max (PangoCoverage *coverage,
PangoCoverage *other)
@@ -223,7 +222,7 @@ pango_coverage_max (PangoCoverage *coverage,
* Convert a `PangoCoverage` structure into a flat binary format.
*
* Deprecated: 1.44: This returns %NULL
- **/
+ */
void
pango_coverage_to_bytes (PangoCoverage *coverage,
guchar **bytes,
@@ -243,10 +242,10 @@ pango_coverage_to_bytes (PangoCoverage *coverage,
* to a `PangoCoverage`.
*
* Return value: (transfer full) (nullable): a newly allocated
- * `PangoCoverage`, or %NULL if the data was invalid.
+ * `PangoCoverage`, or %NULL if the data was invalid.
*
* Deprecated: 1.44: This returns %NULL
- **/
+ */
PangoCoverage *
pango_coverage_from_bytes (guchar *bytes,
int n_bytes)
diff --git a/pango/pango-coverage.h b/pango/pango-coverage.h
index 67fc6306..dbee7e9f 100644
--- a/pango/pango-coverage.h
+++ b/pango/pango-coverage.h
@@ -32,30 +32,34 @@ G_BEGIN_DECLS
/**
* PangoCoverage:
*
- * A #PangoCoverage structure is a map from Unicode characters
- * to #PangoCoverageLevel values.
+ * A `PangoCoverage` structure is a map from Unicode characters
+ * to [enum@Pango.CoverageLevel] values.
*
- * It is often necessary in Pango to determine if a particular font can
- * represent a particular character, and also how well it can represent
- * that character. The #PangoCoverage is a data structure that is used to
- * represent that information. It is an opaque structure with no public fields.
+ * It is often necessary in Pango to determine if a particular
+ * font can represent a particular character, and also how well
+ * it can represent that character. The `PangoCoverage` is a data
+ * structure that is used to represent that information. It is an
+ * opaque structure with no public fields.
*/
typedef struct _PangoCoverage PangoCoverage;
/**
* PangoCoverageLevel:
- * @PANGO_COVERAGE_NONE: The character is not representable with the font.
- * @PANGO_COVERAGE_FALLBACK: The character is represented in a way that may be
- * comprehensible but is not the correct graphical form.
- * For instance, a Hangul character represented as a
- * a sequence of Jamos, or a Latin transliteration of a Cyrillic word.
- * @PANGO_COVERAGE_APPROXIMATE: The character is represented as basically the correct
- * graphical form, but with a stylistic variant inappropriate for
- * the current script.
- * @PANGO_COVERAGE_EXACT: The character is represented as the correct graphical form.
+ * @PANGO_COVERAGE_NONE: The character is not representable with
+ * the font.
+ * @PANGO_COVERAGE_FALLBACK: The character is represented in a
+ * way that may be comprehensible but is not the correct
+ * graphical form. For instance, a Hangul character represented
+ * as a a sequence of Jamos, or a Latin transliteration of a
+ * Cyrillic word.
+ * @PANGO_COVERAGE_APPROXIMATE: The character is represented as
+ * basically the correct graphical form, but with a stylistic
+ * variant inappropriate for the current script.
+ * @PANGO_COVERAGE_EXACT: The character is represented as the
+ * correct graphical form.
*
- * `PangoCoverageLevel` is used to indicate how well a font can represent
- * a particular Unicode character for a particular script.
+ * `PangoCoverageLevel` is used to indicate how well a font can
+ * represent a particular Unicode character for a particular script.
*
* Since 1.44, only %PANGO_COVERAGE_NONE and %PANGO_COVERAGE_EXACT
* will be returned.
diff --git a/pango/pango-engine.h b/pango/pango-engine.h
index 16b39c3f..b634fd88 100644
--- a/pango/pango-engine.h
+++ b/pango/pango-engine.h
@@ -60,7 +60,7 @@ typedef struct _PangoEngineClass PangoEngineClass;
/**
* PangoEngine:
*
- * #PangoEngine is the base class for all types of language and
+ * `PangoEngine` is the base class for all types of language and
* script specific engines. It has no functionality by itself.
*
* Deprecated: 1.38
@@ -74,7 +74,7 @@ struct _PangoEngine
/**
* PangoEngineClass:
*
- * Class structure for #PangoEngine
+ * Class structure for `PangoEngine`
*
* Deprecated: 1.38
**/
@@ -91,7 +91,7 @@ GType pango_engine_get_type (void) G_GNUC_CONST;
* PANGO_ENGINE_TYPE_LANG:
*
* A string constant defining the engine type for language engines.
- * These engines derive from #PangoEngineLang.
+ * These engines derive from `PangoEngineLang`.
*
* Deprecated: 1.38
*/
@@ -109,10 +109,10 @@ typedef struct _PangoEngineLangClass PangoEngineLangClass;
/**
* PangoEngineLang:
*
- * The #PangoEngineLang class is implemented by engines that
+ * The `PangoEngineLang` class is implemented by engines that
* customize the rendering-system independent part of the
* Pango pipeline for a particular script or language. For
- * instance, a custom #PangoEngineLang could be provided for
+ * instance, a custom `PangoEngineLang` could be provided for
* Thai to implement the dictionary-based word boundary
* lookups needed for that language.
*
@@ -133,7 +133,7 @@ struct _PangoEngineLang
* but in newer versions, pango_default_break() is always called and
* this is called after that to allow tailoring the breaking results.
*
- * Class structure for #PangoEngineLang
+ * Class structure for `PangoEngineLang`
*
* Deprecated: 1.38
**/
@@ -158,7 +158,7 @@ GType pango_engine_lang_get_type (void) G_GNUC_CONST;
* PANGO_ENGINE_TYPE_SHAPE:
*
* A string constant defining the engine type for shaping engines.
- * These engines derive from #PangoEngineShape.
+ * These engines derive from `PangoEngineShape`.
*
* Deprecated: 1.38
*/
@@ -176,13 +176,13 @@ typedef struct _PangoEngineShapeClass PangoEngineShapeClass;
/**
* PangoEngineShape:
*
- * The #PangoEngineShape class is implemented by engines that
+ * The `PangoEngineShape` class is implemented by engines that
* customize the rendering-system dependent part of the
* Pango pipeline for a particular script or language.
- * A #PangoEngineShape implementation is then specific to both
+ * A `PangoEngineShape` implementation is then specific to both
* a particular rendering system or group of rendering systems
* and to a particular script. For instance, there is one
- * #PangoEngineShape implementation to handle shaping Arabic
+ * `PangoEngineShape` implementation to handle shaping Arabic
* for Fontconfig-based backends.
*
* Deprecated: 1.38
@@ -194,9 +194,9 @@ struct _PangoEngineShape
/**
* PangoEngineShapeClass:
- * @script_shape: Given a font, a piece of text, and a #PangoAnalysis
+ * @script_shape: Given a font, a piece of text, and a `PangoAnalysis`
* structure, converts characters to glyphs and positions the
- * resulting glyphs. The results are stored in the #PangoGlyphString
+ * resulting glyphs. The results are stored in the `PangoGlyphString`
* that is passed in. (The implementation should resize it
* appropriately using pango_glyph_string_set_size()). All fields
* of the @log_clusters and @glyphs array must be filled in, with
@@ -205,7 +205,7 @@ struct _PangoEngineShape
* using the @log_clusters array. Each input character must occur in one
* of the output logical clusters;
* if no rendering is desired for a character, this may involve
- * inserting glyphs with the #PangoGlyph ID #PANGO_GLYPH_EMPTY, which
+ * inserting glyphs with the `PangoGlyph` ID %PANGO_GLYPH_EMPTY, which
* is guaranteed never to render. If the shaping fails for any reason,
* the shaper should return with an empty (zero-size) glyph string.
* If the shaper has not set the size on the glyph string yet, simply
@@ -215,7 +215,7 @@ struct _PangoEngineShape
* implementation simply returns the coverage information for the
* font itself unmodified.
*
- * Class structure for #PangoEngineShape
+ * Class structure for `PangoEngineShape`
*
* Deprecated: 1.38
**/
@@ -247,7 +247,7 @@ typedef struct _PangoEngineScriptInfo PangoEngineScriptInfo;
/**
* PangoEngineScriptInfo:
- * @script: a #PangoScript. The value %PANGO_SCRIPT_COMMON has
+ * @script: a `PangoScript`. The value %PANGO_SCRIPT_COMMON has
* the special meaning here of "all scripts"
* @langs: a semicolon separated list of languages that this
* engine handles for this script. This may be empty,
@@ -259,7 +259,7 @@ typedef struct _PangoEngineScriptInfo PangoEngineScriptInfo;
* indicates that this engine is specific to all
* languages for this range.
*
- * The #PangoEngineScriptInfo structure contains
+ * The `PangoEngineScriptInfo` structure contains
* information about how the shaper covers a particular script.
*
* Deprecated: 1.38
@@ -278,7 +278,7 @@ struct _PangoEngineScriptInfo
* @scripts: array of scripts this engine supports.
* @n_scripts: number of items in @scripts.
*
- * The #PangoEngineInfo structure contains information about a particular
+ * The `PangoEngineInfo` structure contains information about a particular
* engine. It contains the following fields:
*
* Deprecated: 1.38
@@ -307,7 +307,7 @@ void script_engine_list (PangoEngineInfo **engines,
/**
* script_engine_init: (skip)
- * @module: a #GTypeModule structure used to associate any
+ * @module: a `GTypeModule` structure used to associate any
* GObject types created in this module with the module.
*
* Do not use.
@@ -374,7 +374,7 @@ prefix ## _register_type (GTypeModule *module) \
* @instance_init: (nullable): Instance initialization function for the new type, or %NULL
*
* Outputs the necessary code for GObject type registration for a
- * #PangoEngineLang class defined in a module. Two static symbols
+ * `PangoEngineLang` class defined in a module. Two static symbols
* are defined.
*
* <programlisting>
@@ -405,7 +405,7 @@ prefix ## _register_type (GTypeModule *module) \
* @instance_init: (nullable): Instance initialization function for the new type, or %NULL
*
* Outputs the necessary code for GObject type registration for a
- * #PangoEngineShape class defined in a module. Two static symbols
+ * `PangoEngineShape` class defined in a module. Two static symbols
* are defined.
*
* <programlisting>
diff --git a/pango/pango-fontmap.c b/pango/pango-fontmap.c
index bc18a7da..525dd923 100644
--- a/pango/pango-fontmap.c
+++ b/pango/pango-fontmap.c
@@ -118,8 +118,9 @@ pango_font_map_load_font (PangoFontMap *fontmap,
/**
* pango_font_map_list_families:
* @fontmap: a `PangoFontMap`
- * @families: (out) (array length=n_families) (transfer container): location to store a pointer to an array of `PangoFontFamily` *.
- * This array should be freed with g_free().
+ * @families: (out) (array length=n_families) (transfer container): location to
+ * store a pointer to an array of `PangoFontFamily` *.
+ * This array should be freed with g_free().
* @n_families: (out): location to store the number of elements in @families
*
* List all families for a fontmap.
@@ -291,10 +292,10 @@ pango_font_map_real_load_fontset (PangoFontMap *fontmap,
* @fontmap: a `PangoFontMap`
*
* Returns the render ID for shape engines for this fontmap.
- * See the `render_type` field of #PangoEngineInfo.
+ * See the `render_type` field of `PangoEngineInfo`.
*
- * Return value: the ID string for shape engines for this fontmap.
- * Owned by Pango, should not be modified or freed.
+ * Return value (transfer none): the ID string for shape engines
+ * for this fontmap
*
* Since: 1.4
* Deprecated: 1.38
diff --git a/pango/pango-fontmap.h b/pango/pango-fontmap.h
index 64b04da3..aec18eeb 100644
--- a/pango/pango-fontmap.h
+++ b/pango/pango-fontmap.h
@@ -27,23 +27,6 @@
G_BEGIN_DECLS
-/**
- * PANGO_TYPE_FONT_MAP:
- *
- * The #GObject type for #PangoFontMap.
- */
-/**
- * PANGO_FONT_MAP:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFontMap.
- */
-/**
- * PANGO_IS_FONT_MAP:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFontMap.
- */
#define PANGO_TYPE_FONT_MAP (pango_font_map_get_type ())
#define PANGO_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_MAP, PangoFontMap))
#define PANGO_IS_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_MAP))
@@ -70,7 +53,7 @@ struct _PangoFontMap
/**
* PangoFontMapClass:
- * @parent_class: parent #GObjectClass.
+ * @parent_class: parent `GObjectClass`
* @load_font: a function to load a font with a given description. See
* pango_font_map_load_font().
* @list_families: A function to list available font families. See
@@ -83,8 +66,8 @@ struct _PangoFontMap
* See pango_font_map_get_serial().
* @changed: See pango_font_map_changed()
*
- * The #PangoFontMapClass structure holds the virtual functions for
- * a particular #PangoFontMap implementation.
+ * The `PangoFontMapClass` structure holds the virtual functions for
+ * a particular `PangoFontMap` implementation.
*/
struct _PangoFontMapClass
{
diff --git a/pango/pango-fontset.c b/pango/pango-fontset.c
index 6f3bdcbf..a7cda5ad 100644
--- a/pango/pango-fontset.c
+++ b/pango/pango-fontset.c
@@ -55,9 +55,8 @@ pango_fontset_class_init (PangoFontsetClass *class)
* Returns the font in the fontset that contains the best glyph for a
* Unicode character.
*
- * Return value: (transfer full): a `PangoFont`. The caller must call
- * g_object_unref() when finished with the font.
- **/
+ * Return value: (transfer full): a `PangoFont`
+ */
PangoFont *
pango_fontset_get_font (PangoFontset *fontset,
guint wc)
@@ -70,13 +69,12 @@ pango_fontset_get_font (PangoFontset *fontset,
/**
* pango_fontset_get_metrics:
- * @fontset: a #PangoFontset
+ * @fontset: a `PangoFontset`
*
* Get overall metric information for the fonts in the fontset.
*
- * Return value: a #PangoFontMetrics object. The caller must call pango_font_metrics_unref()
- * when finished using the object.
- **/
+ * Return value: a `PangoFontMetrics` object
+ */
PangoFontMetrics *
pango_fontset_get_metrics (PangoFontset *fontset)
{
@@ -97,7 +95,7 @@ pango_fontset_get_metrics (PangoFontset *fontset)
* If @func returns %TRUE, that stops the iteration.
*
* Since: 1.4
- **/
+ */
void
pango_fontset_foreach (PangoFontset *fontset,
PangoFontsetForeachFunc func,
@@ -238,9 +236,8 @@ struct _PangoFontsetSimpleClass
*
* Creates a new `PangoFontsetSimple` for the given language.
*
- * Return value: the newly allocated `PangoFontsetSimple`, which should
- * be freed with g_object_unref().
- **/
+ * Return value: the newly allocated `PangoFontsetSimple`
+ */
PangoFontsetSimple *
pango_fontset_simple_new (PangoLanguage *language)
{
@@ -307,7 +304,7 @@ pango_fontset_simple_finalize (GObject *object)
* @font: a `PangoFont`.
*
* Adds a font to the fontset.
- **/
+ */
void
pango_fontset_simple_append (PangoFontsetSimple *fontset,
PangoFont *font)
@@ -322,8 +319,8 @@ pango_fontset_simple_append (PangoFontsetSimple *fontset,
*
* Returns the number of fonts in the fontset.
*
- * Return value: the size of @fontset.
- **/
+ * Return value: the size of @fontset
+ */
int
pango_fontset_simple_size (PangoFontsetSimple *fontset)
{
diff --git a/pango/pango-fontset.h b/pango/pango-fontset.h
index 2b2018dd..33ca87eb 100644
--- a/pango/pango-fontset.h
+++ b/pango/pango-fontset.h
@@ -33,11 +33,6 @@ G_BEGIN_DECLS
* PangoFontset
*/
-/**
- * PANGO_TYPE_FONTSET:
- *
- * The #GObject type for #PangoFontset.
- */
#define PANGO_TYPE_FONTSET (pango_fontset_get_type ())
#define PANGO_FONTSET(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONTSET, PangoFontset))
#define PANGO_IS_FONTSET(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONTSET))
@@ -86,7 +81,7 @@ struct _PangoFontset
/**
* PangoFontsetClass:
- * @parent_class: parent #GObjectClass.
+ * @parent_class: parent `GObjectClass`
* @get_font: a function to get the font in the fontset that contains the
* best glyph for the given Unicode character; see pango_fontset_get_font().
* @get_metrics: a function to get overall metric information for the fonts
@@ -95,8 +90,8 @@ struct _PangoFontset
* @foreach: a function to loop over the fonts in the fontset. See
* pango_fontset_foreach().
*
- * The #PangoFontsetClass structure holds the virtual functions for
- * a particular #PangoFontset implementation.
+ * The `PangoFontsetClass` structure holds the virtual functions for
+ * a particular `PangoFontset` implementation.
*/
struct _PangoFontsetClass
{
@@ -123,11 +118,6 @@ struct _PangoFontsetClass
};
/**
- * PANGO_TYPE_FONTSET_SIMPLE:
- *
- * The #GObject type for #PangoFontsetSimple.
- */
-/**
* PangoFontsetSimple:
*
* `PangoFontsetSimple` is a implementation of the abstract
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index 08bb8762..cbda8f09 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -32,27 +32,27 @@
* pango_glyph_item_split:
* @orig: a `PangoItem`
* @text: text to which positions in @orig apply
- * @split_index: byte index of position to split item, relative to the start of the item
+ * @split_index: byte index of position to split item, relative to the
+ * start of the item
*
* Modifies @orig to cover only the text after @split_index, and
* returns a new item that covers the text before @split_index that
* used to be in @orig.
*
- * You can think of @split_index as the length of
- * the returned item. @split_index may not be 0, and it may not be
- * greater than or equal to the length of @orig (that is, there must
- * be at least one byte assigned to each item, you can't create a
- * zero-length item).
+ * You can think of @split_index as the length of the returned item.
+ * @split_index may not be 0, and it may not be greater than or equal
+ * to the length of @orig (that is, there must be at least one byte
+ * assigned to each item, you can't create a zero-length item).
*
* This function is similar in function to pango_item_split() (and uses
* it internally.)
*
* Return value: the newly allocated item representing text before
- * @split_index, which should be freed
- * with pango_glyph_item_free().
+ * @split_index, which should be freed
+ * with pango_glyph_item_free().
*
* Since: 1.2
- **/
+ */
PangoGlyphItem *
pango_glyph_item_split (PangoGlyphItem *orig,
const char *text,
@@ -134,16 +134,16 @@ pango_glyph_item_split (PangoGlyphItem *orig,
/**
* pango_glyph_item_copy:
- * @orig: (nullable): a `PangoGlyphItem`, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`
*
* Make a deep copy of an existing `PangoGlyphItem` structure.
*
- * Return value: (nullable): the newly allocated `PangoGlyphItem`, which should
- * be freed with pango_glyph_item_free(), or %NULL
- * if @orig was %NULL.
+ * Return value: (nullable): the newly allocated `PangoGlyphItem`,
+ * which should be freed with pango_glyph_item_free(), or %NULL
+ * if @orig was %NULL.
*
* Since: 1.20
- **/
+ */
PangoGlyphItem *
pango_glyph_item_copy (PangoGlyphItem *orig)
{
@@ -162,12 +162,12 @@ pango_glyph_item_copy (PangoGlyphItem *orig)
/**
* pango_glyph_item_free:
- * @glyph_item: (nullable): a `PangoGlyphItem`, may be %NULL
+ * @glyph_item: (nullable): a `PangoGlyphItem`
*
* Frees a `PangoGlyphItem` and resources to which it points.
*
* Since: 1.6
- **/
+ */
void
pango_glyph_item_free (PangoGlyphItem *glyph_item)
{
@@ -189,7 +189,7 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item,
/**
* pango_glyph_item_iter_copy:
- * @orig: (nullable): a `PangoGlyphItem`Iter, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`Iter
*
* Make a shallow copy of an existing `PangoGlyphItemIter` structure.
*
@@ -198,7 +198,7 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item,
* if @orig was %NULL.
*
* Since: 1.22
- **/
+ */
PangoGlyphItemIter *
pango_glyph_item_iter_copy (PangoGlyphItemIter *orig)
{
@@ -216,12 +216,12 @@ pango_glyph_item_iter_copy (PangoGlyphItemIter *orig)
/**
* pango_glyph_item_iter_free:
- * @iter: (nullable): a `PangoGlyphItemIter`, may be %NULL
+ * @iter: (nullable): a `PangoGlyphItemIter`
*
* Frees a `PangoGlyphItem`Iter.
*
* Since: 1.22
- **/
+ */
void
pango_glyph_item_iter_free (PangoGlyphItemIter *iter)
{
@@ -247,7 +247,7 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItemIter, pango_glyph_item_iter,
* %FALSE if we were already on the last cluster.
*
* Since: 1.22
- **/
+ */
gboolean
pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter)
{
@@ -337,7 +337,7 @@ pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter)
* %FALSE if we were already on the first cluster.
*
* Since: 1.22
- **/
+ */
gboolean
pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter)
{
@@ -433,7 +433,7 @@ pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter)
* Return value: %FALSE if there are no clusters in the glyph item
*
* Since: 1.22
- **/
+ */
gboolean
pango_glyph_item_iter_init_start (PangoGlyphItemIter *iter,
PangoGlyphItem *glyph_item,
@@ -472,7 +472,7 @@ pango_glyph_item_iter_init_start (PangoGlyphItemIter *iter,
* Return value: %FALSE if there are no clusters in the glyph item
*
* Since: 1.22
- **/
+ */
gboolean
pango_glyph_item_iter_init_end (PangoGlyphItemIter *iter,
PangoGlyphItem *glyph_item,
@@ -514,7 +514,7 @@ append_attrs (PangoGlyphItem *glyph_item,
g_slist_concat (glyph_item->item->analysis.extra_attrs, attrs);
}
-/* Make a deep copy of a #GSList of PangoAttribute
+/* Make a deep copy of a GSList of PangoAttribute
*/
static GSList *
attr_slist_copy (GSList *attrs)
@@ -564,11 +564,10 @@ split_before_cluster_start (ApplyAttrsState *state)
* Splits a shaped item (`PangoGlyphItem`) into multiple items based
* on an attribute list.
*
- * The idea is that if you have attributes
- * that don't affect shaping, such as color or underline, to avoid
- * affecting shaping, you filter them out ([method@Pango.AttrList.filter]),
- * apply the shaping process and then reapply them to the result using
- * this function.
+ * The idea is that if you have attributes that don't affect shaping,
+ * such as color or underline, to avoid affecting shaping, you filter
+ * them out ([method@Pango.AttrList.filter]), apply the shaping process
+ * and then reapply them to the result using this function.
*
* All attributes that start or end inside a cluster are applied
* to that cluster; for instance, if half of a cluster is underlined
@@ -586,7 +585,7 @@ split_before_cluster_start (ApplyAttrsState *state)
* g_slist_free().
*
* Since: 1.2
- **/
+ */
GSList *
pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item,
const char *text,
@@ -721,7 +720,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item,
* @glyph_item: a `PangoGlyphItem`
* @text: text that @glyph_item corresponds to
* (glyph_item->item->offset is an offset from the
- * start of @text)
+ * start of @text)
* @log_attrs: (array): logical attributes for the item
* (the first logical attribute refers to the position
* before the first character in the item)
@@ -803,22 +802,21 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
* @glyph_item: a `PangoGlyphItem`
* @text: text that @glyph_item corresponds to
* (glyph_item->item->offset is an offset from the
- * start of @text)
+ * start of @text)
* @logical_widths: (array): an array whose length is the number of
- * characters in glyph_item (equal to
- * glyph_item->item->num_chars) to be filled in with
- * the resulting character widths.
+ * characters in glyph_item (equal to glyph_item->item->num_chars)
+ * to be filled in with the resulting character widths.
*
- * Given a `PangoGlyphItem` and the corresponding text, determine the width
- * corresponding to each character.
+ * Given a `PangoGlyphItem` and the corresponding text, determine the
+ * width corresponding to each character.
*
- * When multiple characters compose a single cluster, the width of the entire
- * cluster is divided equally among the characters.
+ * When multiple characters compose a single cluster, the width of the
+ * entire cluster is divided equally among the characters.
*
* See also [method@Pango.GlyphString.get_logical_widths].
*
* Since: 1.26
- **/
+ */
void
pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
const char *text,
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index 8a1dbff4..6c2f9249 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -49,11 +49,6 @@ struct _PangoGlyphItem
PangoGlyphString *glyphs;
};
-/**
- * PANGO_TYPE_GLYPH_ITEM:
- *
- * The #GObject type for #PangoGlyphItem.
- */
#define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
PANGO_AVAILABLE_IN_ALL
@@ -144,13 +139,6 @@ struct _PangoGlyphItemIter
int end_char;
};
-/**
- * PANGO_TYPE_GLYPH_ITEM_ITER:
- *
- * The #GObject type for #PangoGlyphItemIter.
- *
- * Since: 1.22
- */
#define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
PANGO_AVAILABLE_IN_1_22
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 7c1bf7b5..abab5572 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -109,9 +109,9 @@ struct _PangoGlyphInfo
* PangoGlyphString:
* @num_glyphs: number of the glyphs in this glyph string.
* @glyphs: (array length=num_glyphs): array of glyph information
- * for the glyph string.
+ * for the glyph string.
* @log_clusters: logical cluster info, indexed by the byte index
- * within the text corresponding to the glyph string.
+ * within the text corresponding to the glyph string.
*
* A `PangoGlyphString` is used to store strings of glyphs with geometry
* and visual attribute information.
@@ -129,11 +129,6 @@ struct _PangoGlyphString {
gint space;
};
-/**
- * PANGO_TYPE_GLYPH_STRING:
- *
- * The #GObject type for #PangoGlyphString.
- */
#define PANGO_TYPE_GLYPH_STRING (pango_glyph_string_get_type ())
PANGO_AVAILABLE_IN_ALL
@@ -207,13 +202,13 @@ void pango_shape_full (const char *item_text,
* PangoShapeFlags:
* @PANGO_SHAPE_NONE: Default value.
* @PANGO_SHAPE_ROUND_POSITIONS: Round glyph positions
- * and widths to whole device units. This option should
- * be set if the target renderer can't do subpixel
- * positioning of glyphs.
+ * and widths to whole device units. This option should
+ * be set if the target renderer can't do subpixel
+ * positioning of glyphs.
*
* Flags influencing the shaping process.
*
- * `PangoShapeFlags` can be passed to pango_shape_with_flags().
+ * `PangoShapeFlags` can be passed to [func@Pango.shape_with_flags].
*/
typedef enum {
PANGO_SHAPE_NONE = 0,
diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c
index a21749b6..f01a7349 100644
--- a/pango/pango-gravity.c
+++ b/pango/pango-gravity.c
@@ -29,7 +29,7 @@
* pango_gravity_to_rotation:
* @gravity: gravity to query, should not be %PANGO_GRAVITY_AUTO
*
- * Converts a #PangoGravity value to its natural rotation in radians.
+ * Converts a `PangoGravity` value to its natural rotation in radians.
*
* Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians.
* So, to call [method@Pango.Matrix,rotate] with the output of this function
@@ -232,7 +232,7 @@ get_script_properties (PangoScript script)
/**
* pango_gravity_get_for_script:
- * @script: #PangoScript to query
+ * @script: `PangoScript` to query
* @base_gravity: base gravity of the paragraph
* @hint: orientation hint
*
@@ -245,7 +245,7 @@ get_script_properties (PangoScript script)
* pass %PANGO_GRAVITY_AUTO and %PANGO_GRAVITY_HINT_STRONG in.
*
* Return value: resolved gravity suitable to use for a run of text
- * with @script.
+ * with @script
*
* Since: 1.16
*/
@@ -265,7 +265,7 @@ pango_gravity_get_for_script (PangoScript script,
/**
* pango_gravity_get_for_script_and_width:
- * @script: #PangoScript to query
+ * @script: `PangoScript` to query
* @wide: %TRUE for wide characters as returned by g_unichar_iswide()
* @base_gravity: base gravity of the paragraph
* @hint: orientation hint
diff --git a/pango/pango-gravity.h b/pango/pango-gravity.h
index a3aa7f19..178b018f 100644
--- a/pango/pango-gravity.h
+++ b/pango/pango-gravity.h
@@ -61,13 +61,13 @@ typedef enum {
/**
* PangoGravityHint:
* @PANGO_GRAVITY_HINT_NATURAL: scripts will take their natural gravity based
- * on the base gravity and the script. This is the default.
+ * on the base gravity and the script. This is the default.
* @PANGO_GRAVITY_HINT_STRONG: always use the base gravity set, regardless of
- * the script.
+ * the script.
* @PANGO_GRAVITY_HINT_LINE: for scripts not in their natural direction (eg.
- * Latin in East gravity), choose per-script gravity such that every script
- * respects the line progression. This means, Latin and Arabic will take
- * opposite gravities and both flow top-to-bottom for example.
+ * Latin in East gravity), choose per-script gravity such that every script
+ * respects the line progression. This means, Latin and Arabic will take
+ * opposite gravities and both flow top-to-bottom for example.
*
* `PangoGravityHint` defines how horizontal scripts should behave in a
* vertical context.
@@ -77,7 +77,7 @@ typedef enum {
* See also [enum@Pango.Gravity]
*
* Since: 1.16
- **/
+ */
typedef enum {
PANGO_GRAVITY_HINT_NATURAL,
PANGO_GRAVITY_HINT_STRONG,
@@ -86,29 +86,30 @@ typedef enum {
/**
* PANGO_GRAVITY_IS_VERTICAL:
- * @gravity: the #PangoGravity to check
+ * @gravity: the `PangoGravity` to check
*
- * Whether a #PangoGravity represents vertical writing directions.
+ * Whether a `PangoGravity` represents vertical writing directions.
*
* Returns: %TRUE if @gravity is %PANGO_GRAVITY_EAST or %PANGO_GRAVITY_WEST,
- * %FALSE otherwise.
+ * %FALSE otherwise.
*
* Since: 1.16
- **/
+ */
#define PANGO_GRAVITY_IS_VERTICAL(gravity) \
((gravity) == PANGO_GRAVITY_EAST || (gravity) == PANGO_GRAVITY_WEST)
/**
* PANGO_GRAVITY_IS_IMPROPER:
- * @gravity: the #PangoGravity to check
+ * @gravity: the `PangoGravity` to check
*
- * Whether a #PangoGravity represents a gravity that results in reversal of text direction.
+ * Whether a `PangoGravity` represents a gravity that results in reversal
+ * of text direction.
*
* Returns: %TRUE if @gravity is %PANGO_GRAVITY_WEST or %PANGO_GRAVITY_NORTH,
- * %FALSE otherwise.
+ * %FALSE otherwise.
*
* Since: 1.32
- **/
+ */
#define PANGO_GRAVITY_IS_IMPROPER(gravity) \
((gravity) == PANGO_GRAVITY_WEST || (gravity) == PANGO_GRAVITY_NORTH)
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 2f79acec..355b9b99 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -279,8 +279,7 @@ _pango_get_lc_ctype (void)
*
* Note that the default language can change over the life of an application.
*
- * Return value: (transfer none): the default language as a
- * `PangoLanguage`, must not be freed.
+ * Return value: (transfer none): the default language as a `PangoLanguage`
*
* Since: 1.16
**/
@@ -306,7 +305,7 @@ pango_language_get_default (void)
/**
* pango_language_from_string:
- * @language: (allow-none): a string representing a language tag, or %NULL
+ * @language: (nullable): a string representing a language tag, or %NULL
*
* Convert a language tag to a `PangoLanguage`.
*
@@ -318,12 +317,11 @@ pango_language_get_default (void)
* lowercase, mapping '_' to '-', and stripping all characters other
* than letters and '-'.
*
- * Use [type_func@Pango.Language.get_default] if you want to get the `PangoLanguage`
- * for the current locale of the process.
+ * Use [type_func@Pango.Language.get_default] if you want to get the
+ * `PangoLanguage` for the current locale of the process.
*
* Return value: (transfer none) (nullable): an opaque pointer to a
- * `PangoLanguage` structure, or %NULL if @language was %NULL. The
- * returned pointer will be valid forever after, and should not be freed.
+ * `PangoLanguage` structure, or %NULL if @language was %NULL
*/
PangoLanguage *
pango_language_from_string (const char *language)
@@ -376,8 +374,7 @@ out:
*
* Gets the RFC-3066 format string representing the given language tag.
*
- * Returns: a string representing the language tag. This is owned by
- * Pango and should not be freed.
+ * Returns (transfer none): a string representing the language tag
*/
const char *
(pango_language_to_string) (PangoLanguage *language)
@@ -397,12 +394,11 @@ const char *
* Checks if a language tag matches one of the elements in a list of
* language ranges.
*
- * A language tag is considered to match a range
- * in the list if the range is '*', the range is exactly the tag,
- * or the range is a prefix of the tag, and the character after it
- * in the tag is '-'.
+ * A language tag is considered to match a range in the list if the
+ * range is '*', the range is exactly the tag, or the range is a prefix
+ * of the tag, and the character after it in the tag is '-'.
*
- * Return value: %TRUE if a match was found.
+ * Return value: %TRUE if a match was found
*/
gboolean
pango_language_matches (PangoLanguage *language,
@@ -585,8 +581,7 @@ static const LangInfo lang_texts[] = {
* pango_language_get_sample_string (pango_language_from_string ("xx"))
* ```
*
- * Return value: the sample string. This value is owned by Pango
- * and should not be freed.
+ * Return value: (transfer none): the sample string
*/
const char *
pango_language_get_sample_string (PangoLanguage *language)
@@ -618,9 +613,9 @@ pango_language_get_sample_string (PangoLanguage *language)
/**
* pango_language_get_scripts:
- * @language: (allow-none): a `PangoLanguage`, or %NULL
- * @num_scripts: (out caller-allocates) (allow-none): location to
- * return number of scripts, or %NULL
+ * @language: (nullable): a `PangoLanguage`
+ * @num_scripts: (out caller-allocates) (optional): location to
+ * return number of scripts
*
* Determines the scripts used to to write @language.
*
@@ -639,19 +634,18 @@ pango_language_get_sample_string (PangoLanguage *language)
* though, except that it is positive if the return value is not
* %NULL, and it is a small number.
*
- * The [method@Pango.Language.includes_script] function uses this function
- * internally.
+ * The [method@Pango.Language.includes_script] function uses this
+ * function internally.
*
* Note: while the return value is declared as `PangoScript`, the
* returned values are from the `GUnicodeScript` enumeration, which
* may have more values. Callers need to handle unknown values.
*
- * Return value: (array length=num_scripts) (nullable): An array of
- * `PangoScript` values, with the number of entries in the array
- * stored in @num_scripts, or %NULL if Pango does not have any
- * information about this particular language tag (also the case
- * if @language is %NULL). The returned array is owned by Pango
- * and should not be modified or freed.
+ * Return value: (transfer none) (array length=num_scripts) (nullable):
+ * An array of `PangoScript` values, with the number of entries in
+ * the array stored in @num_scripts, or %NULL if Pango does not have
+ * any information about this particular language tag (also the case
+ * if @language is %NULL).
*
* Since: 1.22
*/
@@ -694,10 +688,11 @@ pango_language_get_scripts (PangoLanguage *language,
* @script: a `PangoScript`
*
* Determines if @script is one of the scripts used to
- * write @language. The returned value is conservative;
- * if nothing is known about the language tag @language,
- * %TRUE will be returned, since, as far as Pango knows,
- * @script might be used to write @language.
+ * write @language.
+ *
+ * The returned value is conservative; if nothing is known about
+ * the language tag @language, %TRUE will be returned, since, as
+ * far as Pango knows, @script might be used to write @language.
*
* This routine is used in Pango's itemization process when
* determining if a supplied language tag is relevant to
@@ -843,17 +838,18 @@ out:
*
* Returns the list of languages that the user prefers.
*
- * The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE` environment
- * variables, in order of preference. Note that this list does not necessarily
- * include the language returned by [type_func@Pango.Language.get_default].
+ * The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE`
+ * environment variables, in order of preference. Note that this
+ * list does not necessarily include the language returned by
+ * [type_func@Pango.Language.get_default].
*
* When choosing language-specific resources, such as the sample
- * text returned by [method@Pango.Language.get_sample_string], you should
- * first try the default language, followed by the languages returned
- * by this function.
+ * text returned by [method@Pango.Language.get_sample_string],
+ * you should first try the default language, followed by the
+ * languages returned by this function.
*
- * Returns: (transfer none) (nullable): a %NULL-terminated array of
- * `PangoLanguage`*
+ * Returns: (transfer none) (nullable): a %NULL-terminated array
+ * of `PangoLanguage`*
*
* Since: 1.48
*/
@@ -872,9 +868,10 @@ pango_language_get_preferred (void)
*
* Finds a language tag that is reasonably representative of @script.
*
- * The language will usually be the most widely spoken or used language written
- * in that script: for instance, the sample language for %PANGO_SCRIPT_CYRILLIC
- * is ru (Russian), the sample language for %PANGO_SCRIPT_ARABIC is ar.
+ * The language will usually be the most widely spoken or used language
+ * written in that script: for instance, the sample language for
+ * %PANGO_SCRIPT_CYRILLIC is ru (Russian), the sample language for
+ * %PANGO_SCRIPT_ARABIC is ar.
*
* For some scripts, no sample language will be returned because
* there is no language that is sufficiently representative. The
@@ -900,7 +897,7 @@ pango_language_get_preferred (void)
* context language is not feasible.
*
* Return value: (nullable): a `PangoLanguage` that is representative
- * of the script, or %NULL if no such language exists.
+ * of the script
*
* Since: 1.4
*/
diff --git a/pango/pango-language.h b/pango/pango-language.h
index 16e6512c..b000c5b8 100644
--- a/pango/pango-language.h
+++ b/pango/pango-language.h
@@ -31,11 +31,6 @@ G_BEGIN_DECLS
typedef struct _PangoLanguage PangoLanguage;
-/**
- * PANGO_TYPE_LANGUAGE:
- *
- * The #GObject type for #PangoLanguage.
- */
#define PANGO_TYPE_LANGUAGE (pango_language_get_type ())
PANGO_AVAILABLE_IN_ALL
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index ca70ebe5..1ac44986 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -256,8 +256,7 @@ pango_layout_finalize (GObject *object)
* Create a new `PangoLayout` object with attributes initialized to
* default values for a particular `PangoContext`.
*
- * Return value: the newly allocated `PangoLayout`, with a reference
- * count of one, which should be freed with g_object_unref().
+ * Return value: the newly allocated `PangoLayout`
*/
PangoLayout *
pango_layout_new (PangoContext *context)
@@ -284,9 +283,7 @@ pango_layout_new (PangoContext *context)
* The attribute list, tab array, and text from the original layout
* are all copied by value.
*
- * Return value: (transfer full): the newly allocated `PangoLayout`,
- * with a reference count of one, which should be freed
- * with g_object_unref().
+ * Return value: (transfer full): the newly allocated `PangoLayout`
*/
PangoLayout*
pango_layout_copy (PangoLayout *src)
@@ -321,9 +318,7 @@ pango_layout_copy (PangoLayout *src)
*
* Retrieves the `PangoContext` used for this layout.
*
- * Return value: (transfer none): the `PangoContext` for the layout.
- * This does not have an additional refcount added, so if you want to
- * keep a copy of this around, you must reference it yourself.
+ * Return value: (transfer none): the `PangoContext` for the layout
*/
PangoContext *
pango_layout_get_context (PangoLayout *layout)
@@ -507,7 +502,7 @@ pango_layout_get_wrap (PangoLayout *layout)
* to be wrapped.
*
* Return value: %TRUE if any paragraphs had to be wrapped, %FALSE
- * otherwise.
+ * otherwise
*
* Since: 1.16
*/
@@ -523,8 +518,8 @@ pango_layout_is_wrapped (PangoLayout *layout)
/**
* pango_layout_set_indent:
- * @layout: a `PangoLayout`.
- * @indent: the amount by which to indent.
+ * @layout: a `PangoLayout`
+ * @indent: the amount by which to indent
*
* Sets the width in Pango units to indent each paragraph.
*
@@ -556,7 +551,7 @@ pango_layout_set_indent (PangoLayout *layout,
*
* A negative value indicates a hanging indentation.
*
- * Return value: the indent in Pango units.
+ * Return value: the indent in Pango units
*/
int
pango_layout_get_indent (PangoLayout *layout)
@@ -567,7 +562,7 @@ pango_layout_get_indent (PangoLayout *layout)
/**
* pango_layout_set_spacing:
- * @layout: a `PangoLayout`.
+ * @layout: a `PangoLayout`
* @spacing: the amount of spacing
*
* Sets the amount of spacing in Pango unit between
@@ -575,7 +570,7 @@ pango_layout_get_indent (PangoLayout *layout)
*
* When placing lines with spacing, Pango arranges things so that
*
- * line2.top = line1.bottom + spacing
+ * line2.top = line1.bottom + spacing
*
* Note: Since 1.44, Pango defaults to using the line height
* (as determined by the font) for placing lines. The @spacing
@@ -602,7 +597,7 @@ pango_layout_set_spacing (PangoLayout *layout,
*
* Gets the amount of spacing between the lines of the layout.
*
- * Return value: the spacing in Pango units.
+ * Return value: the spacing in Pango units
*/
int
pango_layout_get_spacing (PangoLayout *layout)
@@ -665,9 +660,10 @@ pango_layout_get_line_spacing (PangoLayout *layout)
/**
* pango_layout_set_attributes:
* @layout: a `PangoLayout`
- * @attrs: (allow-none) (transfer none): a #PangoAttrList, can be %NULL
+ * @attrs: (nullable) (transfer none): a `PangoAttrList`
*
* Sets the text attributes for a layout object.
+ *
* References @attrs, so the caller can unref its reference.
*/
void
@@ -708,8 +704,7 @@ pango_layout_set_attributes (PangoLayout *layout,
*
* Gets the attribute list for the layout, if any.
*
- * Return value: (transfer none) (nullable): a `PangoAttrList` or %NULL
- * if none was set.
+ * Return value: (transfer none) (nullable): a `PangoAttrList`
*/
PangoAttrList*
pango_layout_get_attributes (PangoLayout *layout)
@@ -722,13 +717,13 @@ pango_layout_get_attributes (PangoLayout *layout)
/**
* pango_layout_set_font_description:
* @layout: a `PangoLayout`
- * @desc: (allow-none): the new `PangoFontDescription`, or %NULL
+ * @desc: (nullable): the new `PangoFontDescription`
* to unset the current font description
*
* Sets the default font description for the layout.
*
- * If no font description is set on the layout, the font description from
- * the layout's context is used.
+ * If no font description is set on the layout, the
+ * font description from the layout's context is used.
*/
void
pango_layout_set_font_description (PangoLayout *layout,
@@ -755,10 +750,11 @@ pango_layout_set_font_description (PangoLayout *layout,
*
* Gets the font description for the layout, if any.
*
- * Return value: (nullable): a pointer to the layout's font
- * description, or %NULL if the font description from the layout's
- * context is inherited. This value is owned by the layout and must
- * not be modified or freed.
+ * Return value: (transfer none) (nullable): a pointer to the
+ * layout's font description, or %NULL if the font description
+ * from the layout's context is inherited.
+ * This value is owned by the layout and must not be modified
+ * or freed.
*
* Since: 1.8
*/
@@ -773,7 +769,7 @@ pango_layout_get_font_description (PangoLayout *layout)
/**
* pango_layout_set_justify:
* @layout: a `PangoLayout`
- * @justify: whether the lines in the layout should be justified.
+ * @justify: whether the lines in the layout should be justified
*
* Sets whether each complete line should be stretched to fill the
* entire width of the layout.
@@ -807,7 +803,7 @@ pango_layout_set_justify (PangoLayout *layout,
* Gets whether each complete line should be stretched to fill the entire
* width of the layout.
*
- * Return value: the justify.
+ * Return value: the justify value
*/
gboolean
pango_layout_get_justify (PangoLayout *layout)
@@ -820,7 +816,7 @@ pango_layout_get_justify (PangoLayout *layout)
* pango_layout_set_auto_dir:
* @layout: a `PangoLayout`
* @auto_dir: if %TRUE, compute the bidirectional base direction
- * from the layout's contents.
+ * from the layout's contents
*
* Sets whether to calculate the base direction
* for the layout according to its contents.
@@ -866,7 +862,7 @@ pango_layout_set_auto_dir (PangoLayout *layout,
* See [method@Pango.Layout.set_auto_dir].
*
* Return value: %TRUE if the bidirectional base direction
- * is computed from the layout's contents, %FALSE otherwise.
+ * is computed from the layout's contents, %FALSE otherwise
*
* Since: 1.4
*/
@@ -906,7 +902,7 @@ pango_layout_set_alignment (PangoLayout *layout,
* Gets the alignment for the layout: how partial lines are
* positioned within the horizontal space available.
*
- * Return value: the alignment.
+ * Return value: the alignment
*/
PangoAlignment
pango_layout_get_alignment (PangoLayout *layout)
@@ -919,7 +915,7 @@ pango_layout_get_alignment (PangoLayout *layout)
/**
* pango_layout_set_tabs:
* @layout: a `PangoLayout`
- * @tabs: (allow-none): a `PangoTabArray`, or %NULL
+ * @tabs: (nullable): a `PangoTabArray`
*
* Sets the tabs to use for @layout, overriding the default tabs.
*
@@ -956,8 +952,7 @@ pango_layout_set_tabs (PangoLayout *layout,
*
* The return value should be freed with [method@Pango.TabArray.free].
*
- * Return value: (nullable): a copy of the tabs for this layout,
- * or %NULL.
+ * Return value: (nullable): a copy of the tabs for this layout
*/
PangoTabArray*
pango_layout_get_tabs (PangoLayout *layout)
@@ -1005,8 +1000,8 @@ pango_layout_set_single_paragraph_mode (PangoLayout *layout,
*
* See [method@Pango.Layout.set_single_paragraph_mode].
*
- * Return value: %TRUE if the layout does not break paragraphs at
- * paragraph separator characters, %FALSE otherwise.
+ * Return value: %TRUE if the layout does not break paragraphs
+ * at paragraph separator characters, %FALSE otherwise
*/
gboolean
pango_layout_get_single_paragraph_mode (PangoLayout *layout)
@@ -1032,6 +1027,7 @@ pango_layout_get_single_paragraph_mode (PangoLayout *layout)
* force it to be layed out in multiple paragraphs, then whether
* each paragraph is ellipsized separately or the entire layout
* is ellipsized as a whole depends on the set height of the layout.
+ *
* See [method@Pango.Layout.set_height] for details.
*
* Since: 1.6
@@ -1062,7 +1058,7 @@ pango_layout_set_ellipsize (PangoLayout *layout,
* Use [method@Pango.Layout.is_ellipsized] to query whether any
* paragraphs were actually ellipsized.
*
- * Return value: the current ellipsization mode for @layout.
+ * Return value: the current ellipsization mode for @layout
*
* Since: 1.6
*/
@@ -1085,8 +1081,8 @@ pango_layout_get_ellipsize (PangoLayout *layout)
* and there are paragraphs exceeding that width that have to be
* ellipsized.
*
- * Return value: %TRUE if any paragraphs had to be ellipsized, %FALSE
- * otherwise.
+ * Return value: %TRUE if any paragraphs had to be ellipsized,
+ * %FALSE otherwise
*
* Since: 1.16
*/
@@ -1187,11 +1183,12 @@ pango_layout_set_text (PangoLayout *layout,
* pango_layout_get_text:
* @layout: a `PangoLayout`
*
- * Gets the text in the layout. The returned text should not
- * be freed or modified.
+ * Gets the text in the layout.
*
- * Return value: the text in the @layout.
- **/
+ * The returned text should not be freed or modified.
+ *
+ * Return value: (transfer none): the text in the @layout
+ */
const char*
pango_layout_get_text (PangoLayout *layout)
{
@@ -1230,14 +1227,15 @@ pango_layout_get_character_count (PangoLayout *layout)
* @layout: a `PangoLayout`
* @markup: marked-up text
* @length: length of marked-up text in bytes, or -1 if @markup is
- * null-terminated
+ * `NUL`-terminated
*
* Sets the layout text and attribute list from marked-up text.
*
* See [Pango Markup](pango_markup.html)).
+ *
* Replaces the current text and attribute list.
*
- * This is the Same as [method@Pango.Layout.set_markup_with_accel],
+ * This is the same as [method@Pango.Layout.set_markup_with_accel],
* but the markup text isn't scanned for accelerators.
*/
void
@@ -1253,14 +1251,15 @@ pango_layout_set_markup (PangoLayout *layout,
* @layout: a `PangoLayout`
* @markup: marked-up text (see [Pango Markup](pango_markup.html))
* @length: length of marked-up text in bytes, or -1 if @markup is
- * null-terminated
+ * `NUL`-terminated
* @accel_marker: marker for accelerators in the text
- * @accel_char: (out caller-allocates) (allow-none): return location
- * for first located accelerator, or %NULL
+ * @accel_char: (out caller-allocates) (optional): return location
+ * for first located accelerator
*
* Sets the layout text and attribute list from marked-up text.
*
* See [Pango Markup](pango_markup.html)).
+ *
* Replaces the current text and attribute list.
*
* If @accel_marker is nonzero, the given character will mark the
@@ -1314,7 +1313,7 @@ pango_layout_set_markup_with_accel (PangoLayout *layout,
* used in combination with %PANGO_ATTR_FALLBACK, to check if a
* certain font supports all the characters in the string.
*
- * Return value: The number of unknown glyphs in @layout.
+ * Return value: The number of unknown glyphs in @layout
*
* Since: 1.16
*/
@@ -1430,7 +1429,7 @@ pango_layout_get_serial (PangoLayout *layout)
* pango_layout_get_log_attrs:
* @layout: a `PangoLayout`
* @attrs: (out)(array length=n_attrs)(transfer container):
- * location to store a pointer to an array of logical attributes
+ * location to store a pointer to an array of logical attributes.
* This value must be freed with g_free().
* @n_attrs: (out): location to store the number of the attributes in the
* array. (The stored value will be one more than the total number
@@ -1505,7 +1504,7 @@ pango_layout_get_log_attrs_readonly (PangoLayout *layout,
*
* Retrieves the count of lines for the @layout.
*
- * Return value: the line count.
+ * Return value: the line count
*/
int
pango_layout_get_line_count (PangoLayout *layout)
@@ -1580,7 +1579,7 @@ pango_layout_get_lines_readonly (PangoLayout *layout)
* pango_layout_get_line:
* @layout: a `PangoLayout`
* @line: the index of a line, which must be between 0 and
- * `pango_layout_get_line_count(layout) - 1`, inclusive.
+ * `pango_layout_get_line_count(layout) - 1`, inclusive.
*
* Retrieves a particular line from a `PangoLayout`.
*
@@ -1621,7 +1620,7 @@ pango_layout_get_line (PangoLayout *layout,
* pango_layout_get_line_readonly:
* @layout: a `PangoLayout`
* @line: the index of a line, which must be between 0 and
- * `pango_layout_get_line_count(layout) - 1`, inclusive.
+ * `pango_layout_get_line_count(layout) - 1`, inclusive.
*
* Retrieves a particular line from a `PangoLayout`.
*
@@ -1664,8 +1663,8 @@ pango_layout_get_line_readonly (PangoLayout *layout,
* @line: a `PangoLayoutLine`
* @index_: byte offset of a grapheme within the layout
* @trailing: an integer indicating the edge of the grapheme to retrieve
- * the position of. If > 0, the trailing edge of the grapheme,
- * if 0, the leading of the grapheme.
+ * the position of. If > 0, the trailing edge of the grapheme,
+ * if 0, the leading of the grapheme
* @x_pos: (out): location to store the x_offset (in Pango units)
*
* Converts an index within a line to a X position.
@@ -1809,14 +1808,14 @@ pango_layout_index_to_line_and_extents (PangoLayout *layout,
/**
* pango_layout_index_to_line_x:
* @layout: a `PangoLayout`
- * @index_: the byte index of a grapheme within the layout.
+ * @index_: the byte index of a grapheme within the layout
* @trailing: an integer indicating the edge of the grapheme to retrieve the
* position of. If > 0, the trailing edge of the grapheme, if 0,
- * the leading of the grapheme.
- * @line: (out) (allow-none): location to store resulting line index. (which will
- * between 0 and pango_layout_get_line_count(layout) - 1), or %NULL
- * @x_pos: (out) (allow-none): location to store resulting position within line
- * (%PANGO_SCALE units per device unit), or %NULL
+ * the leading of the grapheme
+ * @line: (out) (optional): location to store resulting line index. (which will
+ * between 0 and pango_layout_get_line_count(layout) - 1)
+ * @x_pos: (out) (optional): location to store resulting position within line
+ * (%PANGO_SCALE units per device unit)
*
* Converts from byte @index_ within the @layout to line and X position.
*
@@ -1867,12 +1866,12 @@ pango_layout_index_to_line_x (PangoLayout *layout,
* @strong: whether the moving cursor is the strong cursor or the
* weak cursor. The strong cursor is the cursor corresponding
* to text insertion in the base direction for the layout.
- * @old_index: the byte index of the grapheme for the old index
+ * @old_index: the byte index of the grapheme for the old index
* @old_trailing: if 0, the cursor was at the leading edge of the
* grapheme indicated by @old_index, if > 0, the cursor
* was at the trailing edge.
- * @direction: direction to move cursor. A negative
- * value indicates motion to the left.
+ * @direction: direction to move cursor. A negative
+ * value indicates motion to the left
* @new_index: (out): location to store the new cursor byte index.
* A value of -1 indicates that the cursor has been moved off the
* beginning of the layout. A value of %G_MAXINT indicates that
@@ -2051,7 +2050,7 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
/**
* pango_layout_xy_to_index:
* @layout: a `PangoLayout`
- * @x: the X offset (in Pango units) from the left edge of the layout.
+ * @x: the X offset (in Pango units) from the left edge of the layout
* @y: the Y offset (in Pango units) from the top edge of the layout
* @index_: (out): location to store calculated byte index
* @trailing: (out): location to store a integer indicating where
@@ -2062,15 +2061,14 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
* Converts from X and Y position within a layout to the byte index to the
* character at that logical position.
*
- * If the Y position is not inside the
- * layout, the closest position is chosen (the position will be clamped
- * inside the layout). If the X position is not within the layout, then
- * the start or the end of the line is chosen as described for
- * [method@Pango.LayoutLine.x_to_index]. If either the X or Y positions
- * were not inside the layout, then the function returns %FALSE; on an
- * exact hit, it returns %TRUE.
+ * If the Y position is not inside the layout, the closest position is
+ * chosen (the position will be clamped inside the layout). If the X position
+ * is not within the layout, then the start or the end of the line is
+ * chosen as described for [method@Pango.LayoutLine.x_to_index]. If either
+ * the X or Y positions were not inside the layout, then the function returns
+ * %FALSE; on an exact hit, it returns %TRUE.
*
- * Return value: %TRUE if the coordinates were inside text, %FALSE otherwise.
+ * Return value: %TRUE if the coordinates were inside text, %FALSE otherwise
*/
gboolean
pango_layout_xy_to_index (PangoLayout *layout,
@@ -2416,10 +2414,8 @@ pango_layout_get_direction (PangoLayout *layout,
* pango_layout_get_cursor_pos:
* @layout: a `PangoLayout`
* @index_: the byte index of the cursor
- * @strong_pos: (out) (allow-none): location to store the strong
- * cursor position (may be %NULL)
- * @weak_pos: (out) (allow-none): location to store the weak cursor
- * position (may be %NULL)
+ * @strong_pos: (out) (optional): location to store the strong cursor position
+ * @weak_pos: (out) (optional): location to store the weak cursor position
*
* Given an index within a layout, determines the positions that of the
* strong and weak cursors if the insertion point is at that index.
@@ -2858,10 +2854,10 @@ pango_layout_get_extents_internal (PangoLayout *layout,
/**
* pango_layout_get_extents:
* @layout: a `PangoLayout`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of the
- * layout as drawn or %NULL to indicate that the result is not needed.
- * @logical_rect: (out) (allow-none):rectangle used to store the logical
- * extents of the layout or %NULL to indicate that the result is not needed.
+ * @ink_rect: (out) (optional): rectangle used to store the extents of the
+ * layout as drawn
+ * @logical_rect: (out) (optional):rectangle used to store the logical
+ * extents of the layout
*
* Computes the logical and ink extents of @layout.
*
@@ -2887,17 +2883,17 @@ pango_layout_get_extents (PangoLayout *layout,
/**
* pango_layout_get_pixel_extents:
* @layout: a `PangoLayout`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of the
- * layout as drawn or %NULL to indicate that the result is not needed.
- * @logical_rect: (out) (allow-none): rectangle used to store the logical
- * extents of the layout or %NULL to indicate that the result is not needed.
+ * @ink_rect: (out) (optional): rectangle used to store the extents of the
+ * layout as drawn
+ * @logical_rect: (out) (optional): rectangle used to store the logical
+ * extents of the layout
*
* Computes the logical and ink extents of @layout in device units.
*
* This function just calls [method@Pango.Layout.get_extents] followed by
* two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect
* such that the rounded rectangles fully contain the unrounded one (that is,
- * passes them as first argument to `pango_extents_to_pixels()`).
+ * passes them as first argument to [func@Pango.extents_to_pixels]).
*/
void
pango_layout_get_pixel_extents (PangoLayout *layout,
@@ -2914,8 +2910,8 @@ pango_layout_get_pixel_extents (PangoLayout *layout,
/**
* pango_layout_get_size:
* @layout: a `PangoLayout`
- * @width: (out) (allow-none): location to store the logical width, or %NULL
- * @height: (out) (allow-none): location to store the logical height, or %NULL
+ * @width: (out) (optional): location to store the logical width
+ * @height: (out) (optional): location to store the logical height
*
* Determines the logical width and height of a `PangoLayout` in Pango
* units.
@@ -2940,15 +2936,15 @@ pango_layout_get_size (PangoLayout *layout,
/**
* pango_layout_get_pixel_size:
* @layout: a `PangoLayout`
- * @width: (out) (allow-none): location to store the logical width, or %NULL
- * @height: (out) (allow-none): location to store the logical height, or %NULL
+ * @width: (out) (optional): location to store the logical width
+ * @height: (out) (optional): location to store the logical height
*
* Determines the logical width and height of a `PangoLayout` in device
* units.
*
* [method@Pango.Layout.get_size] returns the width and height
- * scaled by %PANGO_SCALE. This is simply a convenience function around
- * [method@Pango.Layout.get_pixel_extents].
+ * scaled by %PANGO_SCALE. This is simply a convenience function
+ * around [method@Pango.Layout.get_pixel_extents].
*/
void
pango_layout_get_pixel_size (PangoLayout *layout,
@@ -2972,7 +2968,7 @@ pango_layout_get_pixel_size (PangoLayout *layout,
*
* Gets the Y position of baseline of the first line in @layout.
*
- * Return value: baseline of first line, from top of @layout.
+ * Return value: baseline of first line, from top of @layout
*
* Since: 1.22
*/
@@ -4456,7 +4452,7 @@ pango_layout_check_lines (PangoLayout *layout)
/**
* pango_layout_line_ref:
- * @line: (nullable): a `PangoLayoutLine`, may be %NULL
+ * @line: (nullable): a `PangoLayoutLine`
*
* Increase the reference count of a `PangoLayoutLine` by one.
*
@@ -4482,6 +4478,7 @@ pango_layout_line_ref (PangoLayoutLine *line)
* @line: a `PangoLayoutLine`
*
* Decrease the reference count of a `PangoLayoutLine` by one.
+ *
* If the result is zero, the line and all associated memory
* will be freed.
*/
@@ -4512,21 +4509,22 @@ G_DEFINE_BOXED_TYPE (PangoLayoutLine, pango_layout_line,
* @line: a `PangoLayoutLine`
* @x_pos: the X offset (in Pango units) from the left edge of the line.
* @index_: (out): location to store calculated byte index for the grapheme
- * in which the user clicked.
+ * in which the user clicked
* @trailing: (out): location to store an integer indicating where in the
* grapheme the user clicked. It will either be zero, or the number of
* characters in the grapheme. 0 represents the leading edge of the grapheme.
*
* Converts from x offset to the byte index of the corresponding character
- * within the text of the layout. If @x_pos is outside the line, @index_ and
- * @trailing will point to the very first or very last position in the line.
- * This determination is based on the resolved direction of the paragraph;
- * for example, if the resolved direction is right-to-left, then an X position
- * to the right of the line (after it) results in 0 being stored in @index_
- * and @trailing. An X position to the left of the line results in @index_
- * pointing to the (logical) last grapheme in the line and @trailing being
- * set to the number of characters in that grapheme. The reverse is true for
- * a left-to-right line.
+ * within the text of the layout.
+ *
+ * If @x_pos is outside the line, @index_ and @trailing will point to the very
+ * first or very last position in the line. This determination is based on the
+ * resolved direction of the paragraph; for example, if the resolved direction
+ * is right-to-left, then an X position to the right of the line (after it)
+ * results in 0 being stored in @index_ and @trailing. An X position to the
+ * left of the line results in @index_ pointing to the (logical) last grapheme
+ * in the line and @trailing being set to the number of characters in that
+ * grapheme. The reverse is true for a left-to-right line.
*
* Return value: %FALSE if @x_pos was outside the line, %TRUE if inside
*/
@@ -4742,9 +4740,10 @@ pango_layout_line_get_width (PangoLayoutLine *line)
* width `(*ranges)[2*n + 1] - (*ranges)[2*n]`. This array must be freed
* with g_free(). The coordinates are relative to the layout and are in
* Pango units.
- * @n_ranges: The number of ranges stored in @ranges.
+ * @n_ranges: The number of ranges stored in @ranges
*
* Gets a list of visual ranges corresponding to a given logical range.
+ *
* This list is not necessarily minimal - there may be consecutive
* ranges which are adjacent. The ranges will be sorted from left to
* right. The ranges are with respect to the left edge of the entire
@@ -5240,14 +5239,15 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line,
/**
* pango_layout_line_get_extents:
* @line: a `PangoLayoutLine`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of
+ * @ink_rect: (out) (optional): rectangle used to store the extents of
* the glyph string as drawn, or %NULL
- * @logical_rect: (out) (allow-none):rectangle used to store the logical
+ * @logical_rect: (out) (optional): rectangle used to store the logical
* extents of the glyph string, or %NULL
*
- * Computes the logical and ink extents of a layout line. See
- * [method@Pango.Font.get_glyph_extents] for details about the
- * interpretation of the rectangles.
+ * Computes the logical and ink extents of a layout line.
+ *
+ * See [method@Pango.Font.get_glyph_extents] for details
+ * about the interpretation of the rectangles.
*/
void
pango_layout_line_get_extents (PangoLayoutLine *line,
@@ -5260,7 +5260,7 @@ pango_layout_line_get_extents (PangoLayoutLine *line,
/**
* pango_layout_line_get_height:
* @line: a `PangoLayoutLine`
- * @height: (out) (allow-none): return location for the line height
+ * @height: (out) (optional): return location for the line height
*
* Computes the height of the line, i.e. the distance between
* this and the previous lines baseline.
@@ -5294,10 +5294,10 @@ pango_layout_line_new (PangoLayout *layout)
/**
* pango_layout_line_get_pixel_extents:
* @layout_line: a `PangoLayoutLine`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of
- * the glyph string as drawn, or %NULL
- * @logical_rect: (out) (allow-none): rectangle used to store the logical
- * extents of the glyph string, or %NULL
+ * @ink_rect: (out) (optional): rectangle used to store the extents of
+ * the glyph string as drawn
+ * @logical_rect: (out) (optional): rectangle used to store the logical
+ * extents of the glyph string
*
* Computes the logical and ink extents of @layout_line in device units.
*
@@ -6161,13 +6161,11 @@ update_run (PangoLayoutIter *iter,
/**
* pango_layout_iter_copy:
- * @iter: (nullable): a `PangoLayoutIter`, may be %NULL
+ * @iter: (nullable): a `PangoLayoutIter`
*
* Copies a `PangoLayoutIter`.
*
- * Return value: (nullable): the newly allocated `PangoLayoutIter`,
- * which should be freed with [method@Pango.LayoutIter.free],
- * or %NULL if @iter was %NULL.
+ * Return value: (nullable): the newly allocated `PangoLayoutIter`
*
* Since: 1.20
*/
@@ -6227,8 +6225,7 @@ G_DEFINE_BOXED_TYPE (PangoLayoutIter, pango_layout_iter,
*
* Returns an iterator to iterate over the visual extents of the layout.
*
- * Return value: the new `PangoLayoutIter` that should be freed using
- * [method@Pango.LayoutIter.free].
+ * Return value: the new `PangoLayoutIter`
*/
PangoLayoutIter*
pango_layout_get_iter (PangoLayout *layout)
@@ -6327,12 +6324,14 @@ pango_layout_iter_free (PangoLayoutIter *iter)
* pango_layout_iter_get_index:
* @iter: a `PangoLayoutIter`
*
- * Gets the current byte index. Note that iterating forward by char
- * moves in visual order, not logical order, so indexes may not be
- * sequential. Also, the index may be equal to the length of the text
- * in the layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]).
+ * Gets the current byte index.
+ *
+ * Note that iterating forward by char moves in visual order,
+ * not logical order, so indexes may not be sequential. Also,
+ * the index may be equal to the length of the text in the
+ * layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]).
*
- * Return value: current byte index.
+ * Return value: current byte index
*/
int
pango_layout_iter_get_index (PangoLayoutIter *iter)
@@ -6347,15 +6346,17 @@ pango_layout_iter_get_index (PangoLayoutIter *iter)
* pango_layout_iter_get_run:
* @iter: a `PangoLayoutIter`
*
- * Gets the current run. When iterating by run, at the end of each
- * line, there's a position with a %NULL run, so this function can return
- * %NULL. The %NULL run at the end of each line ensures that all lines have
- * at least one run, even lines consisting of only a newline.
+ * Gets the current run.
+ *
+ * When iterating by run, at the end of each line, there's a position
+ * with a %NULL run, so this function can return %NULL. The %NULL run
+ * at the end of each line ensures that all lines have at least one run,
+ * even lines consisting of only a newline.
*
* Use the faster [method@Pango.LayoutIter.get_run_readonly] if you do not
* plan to modify the contents of the run (glyphs, glyph widths, etc.).
*
- * Return value: (transfer none) (nullable): the current run.
+ * Return value: (transfer none) (nullable): the current run
*/
PangoLayoutRun*
pango_layout_iter_get_run (PangoLayoutIter *iter)
@@ -6372,17 +6373,19 @@ pango_layout_iter_get_run (PangoLayoutIter *iter)
* pango_layout_iter_get_run_readonly:
* @iter: a `PangoLayoutIter`
*
- * Gets the current run. When iterating by run, at the end of each
- * line, there's a position with a %NULL run, so this function can return
- * %NULL. The %NULL run at the end of each line ensures that all lines have
- * at least one run, even lines consisting of only a newline.
+ * Gets the current run for read-only access.
+ *
+ * When iterating by run, at the end of each line, there's a position
+ * with a %NULL run, so this function can return %NULL. The %NULL run
+ * at the end of each line ensures that all lines have at least one run,
+ * even lines consisting of only a newline.
*
* This is a faster alternative to [method@Pango.LayoutIter.get_run],
* but the user is not expected to modify the contents of the run (glyphs,
* glyph widths, etc.).
*
* Return value: (transfer none) (nullable): the current run, that
- * should not be modified.
+ * should not be modified
*
* Since: 1.16
*/
@@ -6414,7 +6417,7 @@ _pango_layout_iter_get_line (PangoLayoutIter *iter)
* you do not plan to modify the contents of the line (glyphs,
* glyph widths, etc.).
*
- * Return value: (transfer none): the current line.
+ * Return value: (transfer none): the current line
*/
PangoLayoutLine*
pango_layout_iter_get_line (PangoLayoutIter *iter)
@@ -6438,7 +6441,7 @@ pango_layout_iter_get_line (PangoLayoutIter *iter)
* (glyphs, glyph widths, etc.).
*
* Return value: (transfer none): the current line, that should not be
- * modified.
+ * modified
*
* Since: 1.16
*/
@@ -6457,7 +6460,7 @@ pango_layout_iter_get_line_readonly (PangoLayoutIter *iter)
*
* Determines whether @iter is on the last line of the layout.
*
- * Return value: %TRUE if @iter is on the last line.
+ * Return value: %TRUE if @iter is on the last line
*/
gboolean
pango_layout_iter_at_last_line (PangoLayoutIter *iter)
@@ -6474,7 +6477,7 @@ pango_layout_iter_at_last_line (PangoLayoutIter *iter)
*
* Gets the layout associated with a `PangoLayoutIter`.
*
- * Return value: (transfer none): the layout associated with @iter.
+ * Return value: (transfer none): the layout associated with @iter
*
* Since: 1.20
*/
@@ -6595,9 +6598,10 @@ next_cluster_internal (PangoLayoutIter *iter,
* @iter: a `PangoLayoutIter`
*
* Moves @iter forward to the next character in visual order.
+ *
* If @iter was already at the end of the layout, returns %FALSE.
*
- * Return value: whether motion was possible.
+ * Return value: whether motion was possible
*/
gboolean
pango_layout_iter_next_char (PangoLayoutIter *iter)
@@ -6639,9 +6643,10 @@ pango_layout_iter_next_char (PangoLayoutIter *iter)
* @iter: a `PangoLayoutIter`
*
* Moves @iter forward to the next cluster in visual order.
+ *
* If @iter was already at the end of the layout, returns %FALSE.
*
- * Return value: whether motion was possible.
+ * Return value: whether motion was possible
*/
gboolean
pango_layout_iter_next_cluster (PangoLayoutIter *iter)
@@ -6654,9 +6659,10 @@ pango_layout_iter_next_cluster (PangoLayoutIter *iter)
* @iter: a `PangoLayoutIter`
*
* Moves @iter forward to the next run in visual order.
+ *
* If @iter was already at the end of the layout, returns %FALSE.
*
- * Return value: whether motion was possible.
+ * Return value: whether motion was possible
*/
gboolean
pango_layout_iter_next_run (PangoLayoutIter *iter)
@@ -6698,9 +6704,10 @@ pango_layout_iter_next_run (PangoLayoutIter *iter)
* @iter: a `PangoLayoutIter`
*
* Moves @iter forward to the start of the next line.
+ *
* If @iter is already on the last line, returns %FALSE.
*
- * Return value: whether motion was possible.
+ * Return value: whether motion was possible
*/
gboolean
pango_layout_iter_next_line (PangoLayoutIter *iter)
@@ -6743,10 +6750,12 @@ pango_layout_iter_next_line (PangoLayoutIter *iter)
* @logical_rect: (out caller-allocates): rectangle to fill with
* logical extents
*
- * Gets the extents of the current character, in layout coordinates
- * (origin is the top left of the entire layout). Only logical extents
- * can sensibly be obtained for characters; ink extents make sense only
- * down to the level of clusters.
+ * Gets the extents of the current character, in layout coordinates.
+ *
+ * Layout coordinates have the origin at the top left of the entire layout.
+ *
+ * Only logical extents can sensibly be obtained for characters;
+ * ink extents make sense only down to the level of clusters.
*/
void
pango_layout_iter_get_char_extents (PangoLayoutIter *iter,
@@ -6791,11 +6800,12 @@ pango_layout_iter_get_char_extents (PangoLayoutIter *iter,
/**
* pango_layout_iter_get_cluster_extents:
* @iter: a `PangoLayoutIter`
- * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
- * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
+ * @ink_rect: (out) (optional): rectangle to fill with ink extents
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents
+ *
+ * Gets the extents of the current cluster, in layout coordinates.
*
- * Gets the extents of the current cluster, in layout coordinates
- * (origin is the top left of the entire layout).
+ * Layout coordinates have the origin at the top left of the entire layout.
*/
void
pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter,
@@ -6838,11 +6848,12 @@ pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter,
/**
* pango_layout_iter_get_run_extents:
* @iter: a `PangoLayoutIter`
- * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
- * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
+ * @ink_rect: (out) (optional): rectangle to fill with ink extents
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents
*
- * Gets the extents of the current run in layout coordinates
- * (origin is the top left of the entire layout).
+ * Gets the extents of the current run in layout coordinates.
+ *
+ * Layout coordinates have the origin at the top left of the entire layout.
*/
void
pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
@@ -6894,15 +6905,15 @@ pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
/**
* pango_layout_iter_get_line_extents:
* @iter: a `PangoLayoutIter`
- * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
- * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
- *
- * Obtains the extents of the current line. @ink_rect or @logical_rect
- * can be %NULL if you aren't interested in them. Extents are in layout
- * coordinates (origin is the top-left corner of the entire
- * `PangoLayout`). Thus the extents returned by this function will be
- * the same width/height but not at the same x/y as the extents
- * returned from [method@Pango.LayoutLine.get_extents].
+ * @ink_rect: (out) (optional): rectangle to fill with ink extents
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents
+ *
+ * Obtains the extents of the current line.
+ *
+ * Extents are in layout coordinates (origin is the top-left corner
+ * of the entire `PangoLayout`). Thus the extents returned by this
+ * function will be the same width/height but not at the same x/y
+ * as the extents returned from [method@Pango.LayoutLine.get_extents].
*/
void
pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
@@ -6933,16 +6944,17 @@ pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
/**
* pango_layout_iter_get_line_yrange:
* @iter: a `PangoLayoutIter`
- * @y0_: (out) (allow-none): start of line, or %NULL
- * @y1_: (out) (allow-none): end of line, or %NULL
+ * @y0_: (out) (optional): start of line
+ * @y1_: (out) (optional): end of line
*
* Divides the vertical space in the `PangoLayout` being iterated over
* between the lines in the layout, and returns the space belonging to
- * the current line. A line's range includes the line's logical extents,
- * plus half of the spacing above and below the line, if
- * [method@Pango.Layout.set_spacing] has been called to set layout spacing.
- * The Y positions are in layout coordinates (origin at top left of the
- * entire layout).
+ * the current line.
+ *
+ * A line's range includes the line's logical extents. plus half of the
+ * spacing above and below the line, if [method@Pango.Layout.set_spacing]
+ * has been called to set layout spacing. The Y positions are in layout
+ * coordinates (origin at top left of the entire layout).
*
* Note: Since 1.44, Pango uses line heights for placing lines, and there
* may be gaps between the ranges returned by this function.
@@ -6991,9 +7003,11 @@ pango_layout_iter_get_line_yrange (PangoLayoutIter *iter,
* @iter: a `PangoLayoutIter`
*
* Gets the Y position of the current line's baseline, in layout
- * coordinates (origin at top left of the entire layout).
+ * coordinates.
+ *
+ * Layout coordinates have the origin at the top left of the entire layout.
*
- * Return value: baseline of current line.
+ * Return value: baseline of current line
*/
int
pango_layout_iter_get_baseline (PangoLayoutIter *iter)
@@ -7007,16 +7021,15 @@ pango_layout_iter_get_baseline (PangoLayoutIter *iter)
/**
* pango_layout_iter_get_layout_extents:
* @iter: a `PangoLayoutIter`
- * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
- * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
+ * @ink_rect: (out) (optional): rectangle to fill with ink extents
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents
*
* Obtains the extents of the `PangoLayout` being iterated over.
- * @ink_rect or @logical_rect can be %NULL if you aren't interested in them.
*/
void
-pango_layout_iter_get_layout_extents (PangoLayoutIter *iter,
- PangoRectangle *ink_rect,
- PangoRectangle *logical_rect)
+pango_layout_iter_get_layout_extents (PangoLayoutIter *iter,
+ PangoRectangle *ink_rect,
+ PangoRectangle *logical_rect)
{
if (ITER_IS_INVALID (iter))
return;
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 4a464230..f310e7a3 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -100,11 +100,11 @@ typedef enum {
/**
* PangoLayoutLine:
- * @layout: (allow-none): the layout this line belongs to, might be %NULL
+ * @layout: (nullable): the layout this line belongs to, might be %NULL
* @start_index: start of line as byte index into layout->text
* @length: length of line in bytes
- * @runs: (allow-none) (element-type Pango.LayoutRun): list of runs in the
- * line, from left to right
+ * @runs: (nullable) (element-type Pango.LayoutRun): list of runs in the
+ * line, from left to right
* @is_paragraph_start: #TRUE if this is the first line of the paragraph
* @resolved_dir: #Resolved PangoDirection of line
*
diff --git a/pango/pango-markup.c b/pango/pango-markup.c
index eca3e630..3728d3b3 100644
--- a/pango/pango-markup.c
+++ b/pango/pango-markup.c
@@ -602,9 +602,9 @@ pango_markup_parser_new_internal (char accel_marker,
* @markup_text: markup to parse (see the Pango Markup docs)
* @length: length of @markup_text, or -1 if nul-terminated
* @accel_marker: character that precedes an accelerator, or 0 for none
- * @attr_list: (out) (allow-none): address of return location for a `PangoAttrList`, or %NULL
- * @text: (out) (allow-none): address of return location for text with tags stripped, or %NULL
- * @accel_char: (out) (allow-none): address of return location for accelerator char, or %NULL
+ * @attr_list: (out) (optional): address of return location for a `PangoAttrList`, or %NULL
+ * @text: (out) (optional): address of return location for text with tags stripped, or %NULL
+ * @accel_char: (out) (optional): address of return location for accelerator char, or %NULL
* @error: address of return location for errors, or %NULL
*
* Parses marked-up text to create a plain-text string and an attribute list.
@@ -726,9 +726,9 @@ pango_markup_parser_new (gunichar accel_marker)
/**
* pango_markup_parser_finish:
* @context: A valid parse context that was returned from [func@markup_parser_new]
- * @attr_list: (out) (allow-none): address of return location for a `PangoAttrList`, or %NULL
- * @text: (out) (allow-none): address of return location for text with tags stripped, or %NULL
- * @accel_char: (out) (allow-none): address of return location for accelerator char, or %NULL
+ * @attr_list: (out) (optional): address of return location for a `PangoAttrList`, or %NULL
+ * @text: (out) (optional): address of return location for text with tags stripped, or %NULL
+ * @accel_char: (out) (optional): address of return location for accelerator char, or %NULL
* @error: address of return location for errors, or %NULL
*
* Finishes parsing markup.
diff --git a/pango/pango-matrix.c b/pango/pango-matrix.c
index 731c3a26..471a5e51 100644
--- a/pango/pango-matrix.c
+++ b/pango/pango-matrix.c
@@ -188,7 +188,7 @@ pango_matrix_concat (PangoMatrix *matrix,
/**
* pango_matrix_get_font_scale_factor:
- * @matrix: (allow-none): a `PangoMatrix`, may be %NULL
+ * @matrix: (nullable): a `PangoMatrix`, may be %NULL
*
* Returns the scale factor of a matrix on the height of the font.
*
@@ -212,8 +212,8 @@ pango_matrix_get_font_scale_factor (const PangoMatrix *matrix)
/**
* pango_matrix_get_font_scale_factors:
* @matrix: (nullable): a `PangoMatrix`, or %NULL
- * @xscale: (out) (allow-none): output scale factor in the x direction, or %NULL
- * @yscale: (out) (allow-none): output scale factor perpendicular to the x direction, or %NULL
+ * @xscale: (out) (optional): output scale factor in the x direction, or %NULL
+ * @yscale: (out) (optional): output scale factor perpendicular to the x direction, or %NULL
*
* Calculates the scale factor of a matrix on the width and height of the font.
*
@@ -332,7 +332,7 @@ pango_matrix_transform_point (const PangoMatrix *matrix,
/**
* pango_matrix_transform_rectangle:
* @matrix: (nullable): a `PangoMatrix`, or %NULL
- * @rect: (inout) (allow-none): in/out bounding box in Pango units, or %NULL
+ * @rect: (inout) (optional): in/out bounding box in Pango units, or %NULL
*
* First transforms @rect using @matrix, then calculates the bounding box
* of the transformed rectangle.
@@ -412,7 +412,7 @@ pango_matrix_transform_rectangle (const PangoMatrix *matrix,
/**
* pango_matrix_transform_pixel_rectangle:
* @matrix: (nullable): a `PangoMatrix`, or %NULL
- * @rect: (inout) (allow-none): in/out bounding box in device units, or %NULL
+ * @rect: (inout) (optional): in/out bounding box in device units, or %NULL
*
* First transforms the @rect using @matrix, then calculates the bounding box
* of the transformed rectangle.
diff --git a/pango/pango-matrix.h b/pango/pango-matrix.h
index c3ff5414..d4277401 100644
--- a/pango/pango-matrix.h
+++ b/pango/pango-matrix.h
@@ -60,17 +60,12 @@ struct _PangoMatrix
double y0;
};
-/**
- * PANGO_TYPE_MATRIX:
- *
- * The GObject type for #PangoMatrix
- **/
#define PANGO_TYPE_MATRIX (pango_matrix_get_type ())
/**
* PANGO_MATRIX_INIT:
*
- * Constant that can be used to initialize a PangoMatrix to
+ * Constant that can be used to initialize a `PangoMatrix` to
* the identity transform.
*
* ```
diff --git a/pango/pango-modules.h b/pango/pango-modules.h
index 54b347a2..5bd707b4 100644
--- a/pango/pango-modules.h
+++ b/pango/pango-modules.h
@@ -45,7 +45,7 @@ typedef struct _PangoIncludedModule PangoIncludedModule;
* @exit: a function to finalize the module.
* @create: a function to create an engine, given the engine name.
*
- * The #PangoIncludedModule structure for a statically linked module
+ * The `PangoIncludedModule` structure for a statically linked module
* contains the functions that would otherwise be loaded from a dynamically
* loaded module.
*
diff --git a/pango/pango-ot-buffer.c b/pango/pango-ot-buffer.c
index bec4365a..c48edae2 100644
--- a/pango/pango-ot-buffer.c
+++ b/pango/pango-ot-buffer.c
@@ -38,16 +38,16 @@ G_DEFINE_BOXED_TYPE (PangoOTBuffer, pango_ot_buffer,
pango_ot_buffer_destroy)
/**
- * pango_ot_buffer_new
- * @font: a #PangoFcFont
+ * pango_ot_buffer_new:
+ * @font: a `PangoFcFont`
*
- * Creates a new #PangoOTBuffer for the given OpenType font.
+ * Creates a new `PangoOTBuffer` for the given OpenType font.
*
- * Return value: the newly allocated #PangoOTBuffer, which should
- * be freed with pango_ot_buffer_destroy().
+ * Return value: the newly allocated `PangoOTBuffer`, which should
+ * be freed with [method@PangoOT.Buffer.destroy].
*
* Since: 1.4
- **/
+ */
PangoOTBuffer *
pango_ot_buffer_new (PangoFcFont *font)
{
@@ -59,13 +59,13 @@ pango_ot_buffer_new (PangoFcFont *font)
}
/**
- * pango_ot_buffer_destroy
- * @buffer: a #PangoOTBuffer
+ * pango_ot_buffer_destroy:
+ * @buffer: a `PangoOTBuffer`
*
- * Destroys a #PangoOTBuffer and free all associated memory.
+ * Destroys a `PangoOTBuffer` and free all associated memory.
*
* Since: 1.4
- **/
+ */
void
pango_ot_buffer_destroy (PangoOTBuffer *buffer)
{
@@ -74,13 +74,13 @@ pango_ot_buffer_destroy (PangoOTBuffer *buffer)
}
/**
- * pango_ot_buffer_clear
- * @buffer: a #PangoOTBuffer
+ * pango_ot_buffer_clear:
+ * @buffer: a `PangoOTBuffer`
*
- * Empties a #PangoOTBuffer, make it ready to add glyphs to.
+ * Empties a `PangoOTBuffer`, make it ready to add glyphs to.
*
* Since: 1.4
- **/
+ */
void
pango_ot_buffer_clear (PangoOTBuffer *buffer)
{
@@ -88,17 +88,19 @@ pango_ot_buffer_clear (PangoOTBuffer *buffer)
}
/**
- * pango_ot_buffer_add_glyph
- * @buffer: a #PangoOTBuffer
- * @glyph: the glyph index to add, like a #PangoGlyph
+ * pango_ot_buffer_add_glyph:
+ * @buffer: a `PangoOTBuffer`
+ * @glyph: the glyph index to add, like a `PangoGlyph`
* @properties: the glyph properties
* @cluster: the cluster that this glyph belongs to
*
- * Appends a glyph to a #PangoOTBuffer, with @properties identifying which
- * features should be applied on this glyph. See pango_ot_ruleset_add_feature().
+ * Appends a glyph to a `PangoOTBuffer`, with @properties identifying which
+ * features should be applied on this glyph.
+ *
+ * See [method@PangoOT.Ruleset.add_feature].
*
* Since: 1.4
- **/
+ */
void
pango_ot_buffer_add_glyph (PangoOTBuffer *buffer,
guint glyph,
@@ -109,15 +111,17 @@ pango_ot_buffer_add_glyph (PangoOTBuffer *buffer,
}
/**
- * pango_ot_buffer_set_rtl
- * @buffer: a #PangoOTBuffer
+ * pango_ot_buffer_set_rtl:
+ * @buffer: a `PangoOTBuffer`
* @rtl: %TRUE for right-to-left text
*
- * Sets whether glyphs will be rendered right-to-left. This setting
- * is needed for proper horizontal positioning of right-to-left scripts.
+ * Sets whether glyphs will be rendered right-to-left.
+ *
+ * This setting is needed for proper horizontal positioning
+ * of right-to-left scripts.
*
* Since: 1.4
- **/
+ */
void
pango_ot_buffer_set_rtl (PangoOTBuffer *buffer,
gboolean rtl)
@@ -127,37 +131,38 @@ pango_ot_buffer_set_rtl (PangoOTBuffer *buffer,
/**
* pango_ot_buffer_set_zero_width_marks
- * @buffer: a #PangoOTBuffer
+ * @buffer: a `PangoOTBuffer`
* @zero_width_marks: %TRUE if characters with a mark class should
- * be forced to zero width.
+ * be forced to zero width
*
* Sets whether characters with a mark class should be forced to zero width.
+ *
* This setting is needed for proper positioning of Arabic accents,
* but will produce incorrect results with standard OpenType Indic
* fonts.
*
* Since: 1.6
- **/
+ */
void
-pango_ot_buffer_set_zero_width_marks (PangoOTBuffer *buffer,
- gboolean zero_width_marks)
+pango_ot_buffer_set_zero_width_marks (PangoOTBuffer *buffer,
+ gboolean zero_width_marks)
{
}
/**
* pango_ot_buffer_get_glyphs
- * @buffer: a #PangoOTBuffer
+ * @buffer: a `PangoOTBuffer`
* @glyphs: (array length=n_glyphs) (out) (optional): location to
- * store the array of glyphs, or %NULL
- * @n_glyphs: (out) (optional): location to store the number of
- * glyphs, or %NULL
+ * store the array of glyphs
+ * @n_glyphs: (out) (optional): location to store the number of glyphs
+ *
+ * Gets the glyph array contained in a `PangoOTBuffer`.
*
- * Gets the glyph array contained in a #PangoOTBuffer. The glyphs are
- * owned by the buffer and should not be freed, and are only valid as long
- * as buffer is not modified.
+ * The glyphs are owned by the buffer and should not be freed,
+ * and are only valid as long as buffer is not modified.
*
* Since: 1.4
- **/
+ */
void
pango_ot_buffer_get_glyphs (const PangoOTBuffer *buffer,
PangoOTGlyph **glyphs,
@@ -172,15 +177,17 @@ pango_ot_buffer_get_glyphs (const PangoOTBuffer *buffer,
/**
* pango_ot_buffer_output
- * @buffer: a #PangoOTBuffer
- * @glyphs: a #PangoGlyphString
+ * @buffer: a `PangoOTBuffer`
+ * @glyphs: a `PangoGlyphString`
+ *
+ * Exports the glyphs in a `PangoOTBuffer` into a `PangoGlyphString`.
*
- * Exports the glyphs in a #PangoOTBuffer into a #PangoGlyphString. This is
- * typically used after the OpenType layout processing is over, to convert the
- * resulting glyphs into a generic Pango glyph string.
+ * This is typically used after the OpenType layout processing
+ * is over, to convert the resulting glyphs into a generic Pango
+ * glyph string.
*
* Since: 1.4
- **/
+ */
void
pango_ot_buffer_output (const PangoOTBuffer *buffer,
PangoGlyphString *glyphs)
diff --git a/pango/pango-ot-info.c b/pango/pango-ot-info.c
index 891ae323..821c4f8b 100644
--- a/pango/pango-ot-info.c
+++ b/pango/pango-ot-info.c
@@ -64,15 +64,15 @@ pango_ot_info_finalizer (void *object)
/**
* pango_ot_info_get:
- * @face: a FT_Face
+ * @face: a `FT_Face`
*
- * Returns the #PangoOTInfo structure for the given FreeType font face.
+ * Returns the `PangoOTInfo` structure for the given FreeType font face.
*
- * Return value: (transfer none): the #PangoOTInfo for @face. This object
- * will have the same lifetime as @face.
+ * Return value: (transfer none): the `PangoOTInfo` for @face.
+ * This object will have the same lifetime as @face.
*
* Since: 1.2
- **/
+ */
PangoOTInfo *
pango_ot_info_get (FT_Face face)
{
@@ -110,24 +110,24 @@ get_hb_table_type (PangoOTTableType table_type)
/**
* pango_ot_info_find_script:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @script_tag: the tag of the script to find.
- * @script_index: (out) (optional): location to store the index of the
- * script, or %NULL.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @script_tag: the tag of the script to find
+ * @script_index: (out) (optional): location to store the index of the script
+ *
+ * Finds the index of a script.
*
- * Finds the index of a script. If not found, tries to find the 'DFLT'
- * and then 'dflt' scripts and return the index of that in @script_index.
- * If none of those is found either, %PANGO_OT_NO_SCRIPT is placed in
- * @script_index.
+ * If not found, tries to find the 'DFLT' and then 'dflt' scripts and
+ * return the index of that in @script_index. If none of those is found
+ * either, %PANGO_OT_NO_SCRIPT is placed in @script_index.
*
* All other functions taking an input script_index parameter know
* how to handle %PANGO_OT_NO_SCRIPT, so one can ignore the return
* value of this function completely and proceed, to enjoy the automatic
* fallback to the 'DFLT'/'dflt' script.
*
- * Return value: %TRUE if the script was found.
- **/
+ * Return value: %TRUE if the script was found
+ */
gboolean
pango_ot_info_find_script (PangoOTInfo *info,
PangoOTTableType table_type,
@@ -143,26 +143,26 @@ pango_ot_info_find_script (PangoOTInfo *info,
/**
* pango_ot_info_find_language:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @script_index: the index of the script whose languages are searched.
- * @language_tag: the tag of the language to find.
- * @language_index: (out) (optional): location to store the index of
- * the language, or %NULL.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @script_index: the index of the script whose languages are searched
+ * @language_tag: the tag of the language to find
+ * @language_index: (out) (optional): location to store the index of the language
* @required_feature_index: (out) (optional): location to store the
- * required feature index of the language, or %NULL.
+ * required feature index of the language
*
* Finds the index of a language and its required feature index.
- * If the language is not found, sets @language_index to
- * PANGO_OT_DEFAULT_LANGUAGE and the required feature of the default language
- * system is returned in required_feature_index. For best compatibility with
- * some fonts, also searches the language system tag 'dflt' before falling
- * back to the default language system, but that is transparent to the user.
- * The user can simply ignore the return value of this function to
- * automatically fall back to the default language system.
*
- * Return value: %TRUE if the language was found.
- **/
+ * If the language is not found, sets @language_index to %PANGO_OT_DEFAULT_LANGUAGE
+ * and the required feature of the default language system is returned in
+ * required_feature_index. For best compatibility with some fonts, also
+ * searches the language system tag 'dflt' before falling back to the default
+ * language system, but that is transparent to the user. The user can simply
+ * ignore the return value of this function to automatically fall back to the
+ * default language system.
+ *
+ * Return value: %TRUE if the language was found
+ */
gboolean
pango_ot_info_find_language (PangoOTInfo *info,
PangoOTTableType table_type,
@@ -194,27 +194,29 @@ pango_ot_info_find_language (PangoOTInfo *info,
/**
* pango_ot_info_find_feature:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @feature_tag: the tag of the feature to find.
- * @script_index: the index of the script.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @feature_tag: the tag of the feature to find
+ * @script_index: the index of the script
* @language_index: the index of the language whose features are searched,
- * or %PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script.
+ * or %PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script
* @feature_index: (out) (optional): location to store the index of
- * the feature, or %NULL.
+ * the feature
*
- * Finds the index of a feature. If the feature is not found, sets
- * @feature_index to PANGO_OT_NO_FEATURE, which is safe to pass to
- * pango_ot_ruleset_add_feature() and similar functions.
+ * Finds the index of a feature.
*
- * In the future, this may set @feature_index to an special value that if used
- * in pango_ot_ruleset_add_feature() will ask Pango to synthesize the
- * requested feature based on Unicode properties and data. However, this
- * function will still return %FALSE in those cases. So, users may want to
+ * If the feature is not found, sets @feature_index to PANGO_OT_NO_FEATURE,
+ * which is safe to pass to [method@PangoOT.Ruleset.add_feature] and similar
+ * functions.
+ *
+ * In the future, this may set @feature_index to an special value that if
+ * used in [method@PangoOT.Ruleset.add_feature] will ask Pango to synthesize
+ * the requested feature based on Unicode properties and data. However, this
+ * function will still return %FALSE in those cases. So, users may want to
* ignore the return value of this function in certain cases.
*
- * Return value: %TRUE if the feature was found.
- **/
+ * Return value: %TRUE if the feature was found
+ */
gboolean
pango_ot_info_find_feature (PangoOTInfo *info,
PangoOTTableType table_type,
@@ -234,14 +236,14 @@ pango_ot_info_find_feature (PangoOTInfo *info,
/**
* pango_ot_info_list_scripts:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
*
* Obtains the list of available scripts.
*
- * Return value: a newly-allocated zero-terminated array containing the tags of the
- * available scripts. Should be freed using g_free().
- **/
+ * Return value: a newly-allocated zero-terminated
+ * array containing the tags of the available scripts
+ */
PangoOTTag *
pango_ot_info_list_scripts (PangoOTInfo *info,
PangoOTTableType table_type)
@@ -260,16 +262,16 @@ pango_ot_info_list_scripts (PangoOTInfo *info,
/**
* pango_ot_info_list_languages:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @script_index: the index of the script to list languages for.
- * @language_tag: unused parameter.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @script_index: the index of the script to list languages for
+ * @language_tag: unused parameter
*
* Obtains the list of available languages for a given script.
*
- * Return value: a newly-allocated zero-terminated array containing the tags of the
- * available languages. Should be freed using g_free().
- **/
+ * Return value: a newly-allocated zero-terminated
+ * array containing the tags of the available languages
+ */
PangoOTTag *
pango_ot_info_list_languages (PangoOTInfo *info,
PangoOTTableType table_type,
@@ -290,19 +292,19 @@ pango_ot_info_list_languages (PangoOTInfo *info,
/**
* pango_ot_info_list_features:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @tag: unused parameter.
- * @script_index: the index of the script to obtain information about.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @tag: unused parameter
+ * @script_index: the index of the script to obtain information about
* @language_index: the index of the language to list features for, or
- * %PANGO_OT_DEFAULT_LANGUAGE, to list features for the default
- * language of the script.
+ * %PANGO_OT_DEFAULT_LANGUAGE, to list features for the default
+ * language of the script
*
* Obtains the list of features for the given language of the given script.
*
- * Return value: a newly-allocated zero-terminated array containing the tags of the
- * available features. Should be freed using g_free().
- **/
+ * Return value: a newly-allocated zero-terminated
+ * array containing the tags of the available features
+ */
PangoOTTag *
pango_ot_info_list_features (PangoOTInfo *info,
PangoOTTableType table_type,
diff --git a/pango/pango-ot-private.h b/pango/pango-ot-private.h
index 7ba44c6a..9a88c3f4 100644
--- a/pango/pango-ot-private.h
+++ b/pango/pango-ot-private.h
@@ -38,10 +38,10 @@ typedef struct _PangoOTInfoClass PangoOTInfoClass;
/**
* PangoOTInfo:
*
- * The #PangoOTInfo struct contains the various
+ * The `PangoOTInfo` struct contains the various
* tables associated with an OpenType font. It contains only private fields and
* should only be accessed via the pango_ot_info_… functions
- * which are documented below. To obtain a #PangoOTInfo,
+ * which are documented below. To obtain a `PangoOTInfo`,
* use pango_ot_info_get().
*/
struct _PangoOTInfo
@@ -73,11 +73,11 @@ struct _PangoOTRulesetClass
/**
* PangoOTBuffer:
*
- * The #PangoOTBuffer structure is used to store strings of glyphs associated
- * with a #PangoFcFont, suitable for OpenType layout processing. It contains
+ * The `PangoOTBuffer` structure is used to store strings of glyphs associated
+ * with a `PangoFcFont`, suitable for OpenType layout processing. It contains
* only private fields and should only be accessed via the
* pango_ot_buffer_… functions which are documented below.
- * To obtain a #PangoOTBuffer, use pango_ot_buffer_new().
+ * To obtain a `PangoOTBuffer`, use pango_ot_buffer_new().
*/
struct _PangoOTBuffer
{
diff --git a/pango/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c
index 9cf4cfb0..82a6ceca 100644
--- a/pango/pango-ot-ruleset.c
+++ b/pango/pango-ot-ruleset.c
@@ -28,14 +28,17 @@ static void pango_ot_ruleset_finalize (GObject *object);
/**
* PangoOTRuleset:
*
- * The #PangoOTRuleset structure holds a
- * set of features selected from the tables in an OpenType font.
- * (A feature is an operation such as adjusting glyph positioning
+ * The `PangoOTRuleset` structure holds a set of features selected
+ * from the tables in an OpenType font.
+ *
+ * A feature is an operation such as adjusting glyph positioning
* that should be applied to a text feature such as a certain
- * type of accent.) A #PangoOTRuleset
- * is created with pango_ot_ruleset_new(), features are added
- * to it with pango_ot_ruleset_add_feature(), then it is
- * applied to a #PangoGlyphString with pango_ot_ruleset_shape().
+ * type of accent.
+ *
+ * A `PangoOTRuleset` is created with [ctor@PangoOT.Ruleset.new],
+ * features are added to it with [method@PangoOT.Ruleset.add_feature],
+ * then it is applied to a `PangoGlyphString` with
+ * [method@PangoOT.Ruleset.position].
*/
G_DEFINE_TYPE (PangoOTRuleset, pango_ot_ruleset, G_TYPE_OBJECT);
@@ -60,22 +63,24 @@ pango_ot_ruleset_finalize (GObject *object)
/**
* pango_ot_ruleset_get_for_description:
- * @info: a #PangoOTInfo.
- * @desc: a #PangoOTRulesetDescription.
+ * @info: a `PangoOTInfo`
+ * @desc: a `PangoOTRulesetDescription`
*
* Returns a ruleset for the given OpenType info and ruleset
- * description. Rulesets are created on demand using
- * pango_ot_ruleset_new_from_description().
+ * description.
+ *
+ * Rulesets are created on demand using
+ * [ctor@PangoOT.Ruleset.new_from_description].
* The returned ruleset should not be modified or destroyed.
*
* The static feature map members of @desc should be alive as
* long as @info is.
*
- * Return value: the #PangoOTRuleset for @desc. This object will have
- * the same lifetime as @info.
+ * Return value: the `PangoOTRuleset` for @desc. This object will have
+ * the same lifetime as @info.
*
* Since: 1.18
- **/
+ */
const PangoOTRuleset *
pango_ot_ruleset_get_for_description (PangoOTInfo *info,
const PangoOTRulesetDescription *desc)
@@ -90,13 +95,12 @@ pango_ot_ruleset_get_for_description (PangoOTInfo *info,
/**
* pango_ot_ruleset_new:
- * @info: a #PangoOTInfo.
+ * @info: a `PangoOTInfo`
*
- * Creates a new #PangoOTRuleset for the given OpenType info.
+ * Creates a new `PangoOTRuleset` for the given OpenType info.
*
- * Return value: the newly allocated #PangoOTRuleset, which
- * should be freed with g_object_unref().
- **/
+ * Return value: the newly allocated `PangoOTRuleset`
+ */
PangoOTRuleset *
pango_ot_ruleset_new (PangoOTInfo *info)
{
@@ -105,48 +109,46 @@ pango_ot_ruleset_new (PangoOTInfo *info)
/**
* pango_ot_ruleset_new_for:
- * @info: a #PangoOTInfo.
- * @script: a #PangoScript.
- * @language: a #PangoLanguage.
+ * @info: a `PangoOTInfo`
+ * @script: a `PangoScript`
+ * @language: a `PangoLanguage`
*
- * Creates a new #PangoOTRuleset for the given OpenType info, script, and
+ * Creates a new `PangoOTRuleset` for the given OpenType info, script, and
* language.
*
* This function is part of a convenience scheme that highly simplifies
- * using a #PangoOTRuleset to represent features for a specific pair of script
+ * using a `PangoOTRuleset` to represent features for a specific pair of script
* and language. So one can use this function passing in the script and
* language of interest, and later try to add features to the ruleset by just
* specifying the feature name or tag, without having to deal with finding
* script, language, or feature indices manually.
*
- * In excess to what pango_ot_ruleset_new() does, this function will:
+ * In addition to what [ctor@PangoOT.Ruleset.new] does, this function will:
*
- * * Find the #PangoOTTag script and language tags associated with
- * @script and @language using pango_ot_tag_from_script() and
- * pango_ot_tag_from_language(),
+ * * Find the `PangoOTTag` script and language tags associated with
+ * @script and @language using [func@PangoOT.tag_from_script] and
+ * [func@PangoOT.tag_from_language],
*
* * For each of table types %PANGO_OT_TABLE_GSUB and %PANGO_OT_TABLE_GPOS,
* find the script index of the script tag found and the language
* system index of the language tag found in that script system, using
- * pango_ot_info_find_script() and pango_ot_info_find_language(),
+ * [method@PangoOT.Info.find_script] and [method@PangoOT.Info.find_language],
*
- * * For found language-systems, if they have required feature
- * index, add that feature to the ruleset using
- * pango_ot_ruleset_add_feature(),
+ * * For found language-systems, if they have required feature index,
+ * add that feature to the ruleset using [method@PangoOT.Ruleset.add_feature],
*
* * Remember found script and language indices for both table types,
- * and use them in future pango_ot_ruleset_maybe_add_feature() and
- * pango_ot_ruleset_maybe_add_features().
+ * and use them in future [method@PangoOT.Ruleset.maybe_add_feature] and
+ * [method@PangoOT.Ruleset.maybe_add_features].
*
- * Because of the way return values of pango_ot_info_find_script() and
- * pango_ot_info_find_language() are ignored, this function automatically
+ * Because of the way return values of [method@PangoOT.Info.find_script] and
+ * [method@PangoOT.Info.find_language] are ignored, this function automatically
* finds and uses the 'DFLT' script and the default language-system.
*
- * Return value: the newly allocated #PangoOTRuleset, which
- * should be freed with g_object_unref().
+ * Return value: the newly allocated `PangoOTRuleset`
*
* Since: 1.18
- **/
+ */
PangoOTRuleset *
pango_ot_ruleset_new_for (PangoOTInfo *info,
PangoScript script,
@@ -157,24 +159,23 @@ pango_ot_ruleset_new_for (PangoOTInfo *info,
/**
* pango_ot_ruleset_new_from_description:
- * @info: a #PangoOTInfo.
- * @desc: a #PangoOTRulesetDescription.
+ * @info: a `PangoOTInfo`
+ * @desc: a `PangoOTRulesetDescription`
*
- * Creates a new #PangoOTRuleset for the given OpenType infor and
+ * Creates a new `PangoOTRuleset` for the given OpenType info and
* matching the given ruleset description.
*
- * This is a convenience function that calls pango_ot_ruleset_new_for() and
- * adds the static GSUB/GPOS features to the resulting ruleset, followed by
- * adding other features to both GSUB and GPOS.
+ * This is a convenience function that calls [ctor@PangoOT.Ruleset.new_for]
+ * and adds the static GSUB/GPOS features to the resulting ruleset,
+ * followed by adding other features to both GSUB and GPOS.
*
* The static feature map members of @desc should be alive as
* long as @info is.
*
- * Return value: the newly allocated #PangoOTRuleset, which
- * should be freed with g_object_unref().
+ * Return value: the newly allocated `PangoOTRuleset`
*
* Since: 1.18
- **/
+ */
PangoOTRuleset *
pango_ot_ruleset_new_from_description (PangoOTInfo *info,
const PangoOTRulesetDescription *desc)
@@ -184,15 +185,15 @@ pango_ot_ruleset_new_from_description (PangoOTInfo *info,
/**
* pango_ot_ruleset_add_feature:
- * @ruleset: a #PangoOTRuleset.
- * @table_type: the table type to add a feature to.
- * @feature_index: the index of the feature to add.
- * @property_bit: the property bit to use for this feature. Used to identify
- * the glyphs that this feature should be applied to, or
- * %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
+ * @ruleset: a `PangoOTRuleset`
+ * @table_type: the table type to add a feature to
+ * @feature_index: the index of the feature to add
+ * @property_bit: the property bit to use for this feature. Used to
+ * identify the glyphs that this feature should be applied to, or
+ * %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
*
* Adds a feature to the ruleset.
- **/
+ */
void
pango_ot_ruleset_add_feature (PangoOTRuleset *ruleset,
PangoOTTableType table_type,
@@ -203,26 +204,26 @@ pango_ot_ruleset_add_feature (PangoOTRuleset *ruleset,
/**
* pango_ot_ruleset_maybe_add_feature:
- * @ruleset: a #PangoOTRuleset.
- * @table_type: the table type to add a feature to.
- * @feature_tag: the tag of the feature to add.
- * @property_bit: the property bit to use for this feature. Used to identify
- * the glyphs that this feature should be applied to, or
- * %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
+ * @ruleset: a `PangoOTRuleset`
+ * @table_type: the table type to add a feature to
+ * @feature_tag: the tag of the feature to add
+ * @property_bit: the property bit to use for this feature. Used to
+ * identify the glyphs that this feature should be applied to, or
+ * %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
*
* This is a convenience function that first tries to find the feature
- * using pango_ot_info_find_feature() and the ruleset script and language
- * passed to pango_ot_ruleset_new_for(),
- * and if the feature is found, adds it to the ruleset.
+ * using [method@PangoOT.Info.find_feature] and the ruleset script and
+ * language passed to [ctor@PangoOT.Ruleset.new_for] and if the feature
+ * is found, adds it to the ruleset.
*
- * If @ruleset was not created using pango_ot_ruleset_new_for(), this function
- * does nothing.
+ * If @ruleset was not created using [ctor@PangoOT.Ruleset.new_for],
+ * this function does nothing.
*
* Return value: %TRUE if the feature was found and added to ruleset,
- * %FALSE otherwise.
+ * %FALSE otherwise
*
* Since: 1.18
- **/
+ */
gboolean
pango_ot_ruleset_maybe_add_feature (PangoOTRuleset *ruleset,
PangoOTTableType table_type,
@@ -234,21 +235,21 @@ pango_ot_ruleset_maybe_add_feature (PangoOTRuleset *ruleset,
/**
* pango_ot_ruleset_maybe_add_features:
- * @ruleset: a #PangoOTRuleset.
- * @table_type: the table type to add features to.
- * @features: array of feature name and property bits to add.
- * @n_features: number of feature records in @features array.
+ * @ruleset: a `PangoOTRuleset`
+ * @table_type: the table type to add features to
+ * @features: array of feature name and property bits to add
+ * @n_features: number of feature records in @features array
*
- * This is a convenience function that
- * for each feature in the feature map array @features
- * converts the feature name to a #PangoOTTag feature tag using PANGO_OT_TAG_MAKE()
- * and calls pango_ot_ruleset_maybe_add_feature() on it.
+ * This is a convenience function that for each feature in the feature map
+ * array @features converts the feature name to a `PangoOTTag` feature tag
+ * using PANGO_OT_TAG_MAKE() and calls [method@PangoOT.Ruleset.maybe_add_feature]
+ * on it.
*
* Return value: The number of features in @features that were found
- * and added to @ruleset.
+ * and added to @ruleset
*
* Since: 1.18
- **/
+ */
guint
pango_ot_ruleset_maybe_add_features (PangoOTRuleset *ruleset,
PangoOTTableType table_type,
@@ -260,18 +261,16 @@ pango_ot_ruleset_maybe_add_features (PangoOTRuleset *ruleset,
/**
* pango_ot_ruleset_get_feature_count:
- * @ruleset: a #PangoOTRuleset.
- * @n_gsub_features: (out) (optional): location to store number of
- * GSUB features, or %NULL.
- * @n_gpos_features: (out) (optional): location to store number of
- * GPOS features, or %NULL.
+ * @ruleset: a `PangoOTRuleset`
+ * @n_gsub_features: (out) (optional): location to store number of GSUB features
+ * @n_gpos_features: (out) (optional): location to store number of GPOS features
*
* Gets the number of GSUB and GPOS features in the ruleset.
*
- * Return value: Total number of features in the @ruleset.
+ * Return value: Total number of features in the @ruleset
*
* Since: 1.18
- **/
+ */
guint
pango_ot_ruleset_get_feature_count (const PangoOTRuleset *ruleset,
guint *n_gsub_features,
@@ -282,14 +281,14 @@ pango_ot_ruleset_get_feature_count (const PangoOTRuleset *ruleset,
/**
* pango_ot_ruleset_substitute:
- * @ruleset: a #PangoOTRuleset.
- * @buffer: a #PangoOTBuffer.
+ * @ruleset: a `PangoOTRuleset`
+ * @buffer: a `PangoOTBuffer`
*
- * Performs the OpenType GSUB substitution on @buffer using the features
- * in @ruleset
+ * Performs the OpenType GSUB substitution on @buffer using
+ * the features in @ruleset.
*
* Since: 1.4
- **/
+ */
void
pango_ot_ruleset_substitute (const PangoOTRuleset *ruleset,
PangoOTBuffer *buffer)
@@ -298,14 +297,14 @@ pango_ot_ruleset_substitute (const PangoOTRuleset *ruleset,
/**
* pango_ot_ruleset_position:
- * @ruleset: a #PangoOTRuleset.
- * @buffer: a #PangoOTBuffer.
+ * @ruleset: a `PangoOTRuleset`
+ * @buffer: a `PangoOTBuffer`
*
- * Performs the OpenType GPOS positioning on @buffer using the features
- * in @ruleset
+ * Performs the OpenType GPOS positioning on @buffer using
+ * the features in @ruleset.
*
* Since: 1.4
- **/
+ */
void
pango_ot_ruleset_position (const PangoOTRuleset *ruleset,
PangoOTBuffer *buffer)
@@ -319,13 +318,13 @@ pango_ot_ruleset_position (const PangoOTRuleset *ruleset,
* pango_ot_ruleset_description_hash:
* @desc: a ruleset description
*
- * Computes a hash of a #PangoOTRulesetDescription structure suitable
+ * Computes a hash of a `PangoOTRulesetDescription` structure suitable
* to be used, for example, as an argument to g_hash_table_new().
*
- * Return value: the hash value.
+ * Return value: the hash value
*
* Since: 1.18
- **/
+ */
guint
pango_ot_ruleset_description_hash (const PangoOTRulesetDescription *desc)
{
@@ -338,16 +337,18 @@ pango_ot_ruleset_description_hash (const PangoOTRulesetDescription *desc)
* @desc2: a ruleset description
*
* Compares two ruleset descriptions for equality.
+ *
* Two ruleset descriptions are considered equal if the rulesets
- * they describe are provably identical. This means that their
- * script, language, and all feature sets should be equal. For static feature
- * sets, the array addresses are compared directly, while for other
- * features, the list of features is compared one by one.
- * (Two ruleset descriptions may result in identical rulesets
+ * they describe are provably identical. This means that their
+ * script, language, and all feature sets should be equal.
+ *
+ * For static feature sets, the array addresses are compared directly,
+ * while for other features, the list of features is compared one by
+ * one.(Two ruleset descriptions may result in identical rulesets
* being created, but still compare %FALSE.)
*
* Return value: %TRUE if two ruleset descriptions are identical,
- * %FALSE otherwise.
+ * %FALSE otherwise
*
* Since: 1.18
**/
@@ -367,15 +368,15 @@ G_DEFINE_BOXED_TYPE (PangoOTRulesetDescription, pango_ot_ruleset_description,
* @desc: ruleset description to copy
*
* Creates a copy of @desc, which should be freed with
- * pango_ot_ruleset_description_free(). Primarily used internally
- * by pango_ot_ruleset_get_for_description() to cache rulesets for
- * ruleset descriptions.
+ * [method@PangoOT.RulesetDescription.free].
+ *
+ * Primarily used internally by [type_func@PangoOT.Ruleset.get_for_description]
+ * to cache rulesets for ruleset descriptions.
*
- * Return value: the newly allocated #PangoOTRulesetDescription, which
- * should be freed with pango_ot_ruleset_description_free().
+ * Return value: the newly allocated `PangoOTRulesetDescription`
*
* Since: 1.18
- **/
+ */
PangoOTRulesetDescription *
pango_ot_ruleset_description_copy (const PangoOTRulesetDescription *desc)
{
@@ -392,15 +393,15 @@ pango_ot_ruleset_description_copy (const PangoOTRulesetDescription *desc)
/**
* pango_ot_ruleset_description_free:
- * @desc: an allocated #PangoOTRulesetDescription
+ * @desc: an allocated `PangoOTRulesetDescription`
*
- * Frees a ruleset description allocated by
+ * Frees a ruleset description allocated by
* pango_ot_ruleset_description_copy().
*
* Since: 1.18
- **/
+ */
void
-pango_ot_ruleset_description_free (PangoOTRulesetDescription *desc)
+pango_ot_ruleset_description_free (PangoOTRulesetDescription *desc)
{
g_slice_free (PangoOTRulesetDescription, desc);
}
diff --git a/pango/pango-ot-tag.c b/pango/pango-ot-tag.c
index 5f50b77c..65f9c89d 100644
--- a/pango/pango-ot-tag.c
+++ b/pango/pango-ot-tag.c
@@ -25,7 +25,7 @@
/**
* pango_ot_tag_from_script:
- * @script: A #PangoScript
+ * @script: A `PangoScript`
*
* Finds the OpenType script tag corresponding to @script.
*
@@ -34,11 +34,11 @@
* 'DFLT' script tag that is also defined as
* %PANGO_OT_TAG_DEFAULT_SCRIPT.
*
- * Note that multiple #PangoScript values may map to the same
+ * Note that multiple `PangoScript` values may map to the same
* OpenType script tag. In particular, %PANGO_SCRIPT_HIRAGANA
* and %PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'.
*
- * Return value: #PangoOTTag corresponding to @script or
+ * Return value: `PangoOTTag` corresponding to @script or
* %PANGO_OT_TAG_DEFAULT_SCRIPT if none found.
*
* Since: 1.18
@@ -62,21 +62,21 @@ pango_ot_tag_from_script (PangoScript script)
/**
* pango_ot_tag_to_script:
- * @script_tag: A #PangoOTTag OpenType script tag
+ * @script_tag: A `PangoOTTag` OpenType script tag
*
- * Finds the #PangoScript corresponding to @script_tag.
+ * Finds the `PangoScript` corresponding to @script_tag.
*
* The 'DFLT' script tag is mapped to %PANGO_SCRIPT_COMMON.
*
* Note that an OpenType script tag may correspond to multiple
- * #PangoScript values. In such cases, the #PangoScript value
+ * `PangoScript` values. In such cases, the `PangoScript` value
* with the smallest value is returned.
* In particular, %PANGO_SCRIPT_HIRAGANA
* and %PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'.
* This function will return %PANGO_SCRIPT_HIRAGANA for
* 'kana'.
*
- * Return value: #PangoScript corresponding to @script_tag or
+ * Return value: `PangoScript` corresponding to @script_tag or
* %PANGO_SCRIPT_UNKNOWN if none found.
*
* Since: 1.18
@@ -90,11 +90,11 @@ pango_ot_tag_to_script (PangoOTTag script_tag)
/**
* pango_ot_tag_from_language:
- * @language: (nullable): A #PangoLanguage, or %NULL
+ * @language: (nullable): A `PangoLanguage`
*
* Finds the OpenType language-system tag best describing @language.
*
- * Return value: #PangoOTTag best matching @language or
+ * Return value: `PangoOTTag` best matching @language or
* %PANGO_OT_TAG_DEFAULT_LANGUAGE if none found or if @language
* is %NULL.
*
@@ -119,12 +119,12 @@ pango_ot_tag_from_language (PangoLanguage *language)
/**
* pango_ot_tag_to_language:
- * @language_tag: A #PangoOTTag OpenType language-system tag
+ * @language_tag: A `PangoOTTag` OpenType language-system tag
*
- * Finds a #PangoLanguage corresponding to @language_tag.
+ * Finds a `PangoLanguage` corresponding to @language_tag.
*
- * Return value: #PangoLanguage best matching @language_tag or
- * #PangoLanguage corresponding to the string "xx" if none found.
+ * Return value: `PangoLanguage` best matching @language_tag or
+ * `PangoLanguage` corresponding to the string "xx" if none found.
*
* Since: 1.18
**/
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index 6390538b..37380e71 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -40,7 +40,7 @@ G_BEGIN_DECLS
/**
* PangoOTTag:
*
- * The #PangoOTTag typedef is used to represent TrueType and OpenType
+ * The `PangoOTTag` typedef is used to represent TrueType and OpenType
* four letter tags inside Pango. Use PANGO_OT_TAG_MAKE()
* or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create PangoOTTags manually.
*/
@@ -53,14 +53,14 @@ typedef guint32 PangoOTTag;
* @c3: Third character.
* @c4: Fourth character.
*
- * Creates a #PangoOTTag from four characters. This is similar and
+ * Creates a `PangoOTTag` from four characters. This is similar and
* compatible with the FT_MAKE_TAG() macro from FreeType.
*/
/**
* PANGO_OT_TAG_MAKE_FROM_STRING:
* @s: The string representation of the tag.
*
- * Creates a #PangoOTTag from a string. The string should be at least
+ * Creates a `PangoOTTag` from a string. The string should be at least
* four characters long (pad with space characters if needed), and need
* not be nul-terminated. This is a convenience wrapper around
* PANGO_OT_TAG_MAKE(), but cannot be used in certain situations, for
@@ -147,7 +147,7 @@ typedef enum
/**
* PANGO_OT_TAG_DEFAULT_SCRIPT:
*
- * This is a #PangoOTTag representing the special script tag 'DFLT'. It is
+ * This is a `PangoOTTag` representing the special script tag 'DFLT'. It is
* returned as script tag by pango_ot_tag_from_script() if the requested script
* is not found.
*
@@ -156,7 +156,7 @@ typedef enum
/**
* PANGO_OT_TAG_DEFAULT_LANGUAGE:
*
- * This is a #PangoOTTag representing a special language tag 'dflt'. It is
+ * This is a `PangoOTTag` representing a special language tag 'dflt'. It is
* returned as language tag by pango_ot_tag_from_language() if the requested
* language is not found. It is safe to pass this value to
* pango_ot_info_find_language() as that function falls back to returning default
@@ -178,7 +178,7 @@ typedef enum
* @ligID: a ligature index value, set by the OpenType layout engine.
* @internal: for Pango internal use
*
- * The #PangoOTGlyph structure represents a single glyph together with
+ * The `PangoOTGlyph` structure represents a single glyph together with
* information used for OpenType layout processing of the glyph.
* It contains the following fields.
*/
@@ -199,9 +199,9 @@ struct _PangoOTGlyph
* @property_bit: the property bit to use for this feature. See
* pango_ot_ruleset_add_feature() for details.
*
- * The #PangoOTFeatureMap typedef is used to represent an OpenType
+ * The `PangoOTFeatureMap` typedef is used to represent an OpenType
* feature with the property bit associated with it. The feature tag is
- * represented as a char array instead of a #PangoOTTag for convenience.
+ * represented as a char array instead of a `PangoOTTag` for convenience.
*
* Since: 1.18
*/
@@ -213,8 +213,8 @@ struct _PangoOTFeatureMap
/**
* PangoOTRulesetDescription:
- * @script: a #PangoScript.
- * @language: a #PangoLanguage.
+ * @script: a `PangoScript`
+ * @language: a `PangoLanguage`
* @static_gsub_features: (nullable): static map of GSUB features,
* or %NULL.
* @n_static_gsub_features: length of @static_gsub_features, or 0.
@@ -227,8 +227,8 @@ struct _PangoOTFeatureMap
* struct.
* @n_other_features: length of @other_features, or 0.
*
- * The #PangoOTRuleset structure holds all the information needed
- * to build a complete #PangoOTRuleset from an OpenType font.
+ * The `PangoOTRuleset` structure holds all the information needed
+ * to build a complete `PangoOTRuleset` from an OpenType font.
* The main use of this struct is to act as the key for a per-font
* hash of rulesets. The user populates a ruleset description and
* gets the ruleset using pango_ot_ruleset_get_for_description()
diff --git a/pango/pango-renderer.c b/pango/pango-renderer.c
index 8f3c9846..c36f1921 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -153,7 +153,7 @@ pango_renderer_finalize (GObject *gobject)
* @x: X position of left edge of baseline, in user space coordinates
* in Pango units.
* @y: Y position of left edge of baseline, in user space coordinates
- * in Pango units.
+ * in Pango units.
*
* Draws @layout with the specified `PangoRenderer`.
*
@@ -557,7 +557,7 @@ draw_shaped_glyphs (PangoRenderer *renderer,
* @x: X position of left edge of baseline, in user space coordinates
* in Pango units.
* @y: Y position of left edge of baseline, in user space coordinates
- * in Pango units.
+ * in Pango units.
*
* Draws @line with the specified `PangoRenderer`.
*
@@ -750,7 +750,7 @@ pango_renderer_draw_layout_line (PangoRenderer *renderer,
* @x: X position of left edge of baseline, in user space coordinates
* in Pango units.
* @y: Y position of left edge of baseline, in user space coordinates
- * in Pango units.
+ * in Pango units.
*
* Draws the glyphs in @glyphs with the specified `PangoRenderer`.
*
@@ -801,12 +801,12 @@ pango_renderer_default_draw_glyphs (PangoRenderer *renderer,
/**
* pango_renderer_draw_glyph_item:
* @renderer: a `PangoRenderer`
- * @text: (allow-none): the UTF-8 text that @glyph_item refers to, or %NULL
+ * @text: (nullable): the UTF-8 text that @glyph_item refers to, or %NULL
* @glyph_item: a `PangoGlyphItem`
* @x: X position of left edge of baseline, in user space coordinates
* in Pango units.
* @y: Y position of left edge of baseline, in user space coordinates
- * in Pango units.
+ * in Pango units.
*
* Draws the glyphs in @glyph_item with the specified `PangoRenderer`,
* embedding the text associated with the glyphs in the output if the
@@ -1206,7 +1206,7 @@ pango_renderer_draw_trapezoid (PangoRenderer *renderer,
/**
* pango_renderer_draw_glyph:
* @renderer: a `PangoRenderer`
- * @font: a #PangoFont
+ * @font: a `PangoFont`
* @glyph: the glyph index of a single glyph
* @x: X coordinate of left edge of baseline of glyph
* @y: Y coordinate of left edge of baseline of glyph
@@ -1237,16 +1237,17 @@ pango_renderer_draw_glyph (PangoRenderer *renderer,
* @renderer: a `PangoRenderer`
*
* Does initial setup before rendering operations on @renderer.
- *
+ *
* [method@Pango.Renderer.deactivate] should be called when done drawing.
* Calls such as [method@Pango.Renderer.draw_layout] automatically
- * activate the layout before drawing on it. Calls to
- * `pango_renderer_activate()` and `pango_renderer_deactivate()`
- * can be nested and the renderer will only be initialized and
- * deinitialized once.
+ * activate the layout before drawing on it.
+ *
+ * Calls to [method@Pango.Renderer.activate] and
+ * [method@Pango.Renderer.deactivate] can be nested and the
+ * renderer will only be initialized and deinitialized once.
*
* Since: 1.8
- **/
+ */
void
pango_renderer_activate (PangoRenderer *renderer)
{
@@ -1288,7 +1289,7 @@ pango_renderer_deactivate (PangoRenderer *renderer)
* pango_renderer_set_color:
* @renderer: a `PangoRenderer`
* @part: the part to change the color of
- * @color: (allow-none): the new color or %NULL to unset the current color
+ * @color: (nullable): the new color or %NULL to unset the current color
*
* Sets the color for part of the rendering.
*
@@ -1552,7 +1553,7 @@ pango_renderer_default_prepare_run (PangoRenderer *renderer,
/**
* pango_renderer_set_matrix:
* @renderer: a `PangoRenderer`
- * @matrix: (allow-none): a `PangoMatrix`, or %NULL to unset any existing matrix.
+ * @matrix: (nullable): a `PangoMatrix`, or %NULL to unset any existing matrix
* (No matrix set is the same as setting the identity matrix.)
*
* Sets the transformation matrix that will be applied when rendering.
diff --git a/pango/pango-renderer.h b/pango/pango-renderer.h
index 98c4cfb0..16a1bbd4 100644
--- a/pango/pango-renderer.h
+++ b/pango/pango-renderer.h
@@ -44,7 +44,7 @@ typedef struct _PangoRendererPrivate PangoRendererPrivate;
* @PANGO_RENDER_PART_STRIKETHROUGH: strikethrough lines
* @PANGO_RENDER_PART_OVERLINE: overlines
*
- * #PangoRenderPart defines different items to render for such
+ * `PangoRenderPart` defines different items to render for such
* purposes as setting colors.
*
* Since: 1.8
@@ -62,8 +62,8 @@ typedef enum
/**
* PangoRenderer:
* @matrix: (nullable): the current transformation matrix for
- * the Renderer; may be %NULL, which should be treated the
- * same as the identity matrix.
+ * the Renderer; may be %NULL, which should be treated the
+ * same as the identity matrix.
*
* `PangoRenderer` is a base class for objects that can render text
* provided as `PangoGlyphString` or `PangoLayout`.
@@ -92,12 +92,12 @@ struct _PangoRenderer
/**
* PangoRendererClass:
- * @draw_glyphs: draws a #PangoGlyphString
+ * @draw_glyphs: draws a `PangoGlyphString`
* @draw_rectangle: draws a rectangle
* @draw_error_underline: draws a squiggly line that approximately
* covers the given rectangle in the style of an underline used to
* indicate a spelling error.
- * @draw_shape: draw content for a glyph shaped with #PangoAttrShape.
+ * @draw_shape: draw content for a glyph shaped with `PangoAttrShape`
* @x, @y are the coordinates of the left edge of the baseline,
* in user coordinates.
* @draw_trapezoid: draws a trapezoidal filled area
@@ -107,9 +107,9 @@ struct _PangoRenderer
* @begin: Do renderer-specific initialization before drawing
* @end: Do renderer-specific cleanup after drawing
* @prepare_run: updates the renderer for a new run
- * @draw_glyph_item: draws a #PangoGlyphItem
+ * @draw_glyph_item: draws a `PangoGlyphItem`
*
- * Class structure for #PangoRenderer.
+ * Class structure for `PangoRenderer`.
*
* The following vfuncs take user space coordinates in Pango units
* and have default implementations:
diff --git a/pango/pango-script.c b/pango/pango-script.c
index 7116a0a4..fc7c6332 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -122,14 +122,16 @@ _pango_script_iter_init (PangoScriptIter *iter,
* @text: a UTF-8 string
* @length: length of @text, or -1 if @text is nul-terminated.
*
- * Create a new #PangoScriptIter, used to break a string of
- * Unicode text into runs by Unicode script. No copy is made of
- * @text, so the caller needs to make sure it remains valid until
- * the iterator is freed with pango_script_iter_free().
+ * Create a new `PangoScriptIter`, used to break a string of
+ * Unicode text into runs by Unicode script.
+ *
+ * No copy is made of @text, so the caller needs to make
+ * sure it remains valid until the iterator is freed with
+ * [method@Pango.ScriptIter.free].
*
* Return value: the new script iterator, initialized
* to point at the first range in the text, which should be
- * freed with pango_script_iter_free(). If the string is
+ * freed with [method@Pango.ScriptIter.free]. If the string is
* empty, it will point at an empty range.
*
* Since: 1.4
@@ -154,12 +156,12 @@ _pango_script_iter_fini (PangoScriptIter *iter)
/**
* pango_script_iter_free:
- * @iter: a #PangoScriptIter
+ * @iter: a `PangoScriptIter`
*
- * Frees a #PangoScriptIter created with pango_script_iter_new().
+ * Frees a `PangoScriptIter`.
*
* Since: 1.4
- **/
+ */
void
pango_script_iter_free (PangoScriptIter *iter)
{
@@ -169,22 +171,22 @@ pango_script_iter_free (PangoScriptIter *iter)
/**
* pango_script_iter_get_range:
- * @iter: a #PangoScriptIter
- * @start: (out) (allow-none): location to store start position of the range, or %NULL
- * @end: (out) (allow-none): location to store end position of the range, or %NULL
- * @script: (out) (allow-none): location to store script for range, or %NULL
+ * @iter: a `PangoScriptIter`
+ * @start: (out) (optional): location to store start position of the range
+ * @end: (out) (optional): location to store end position of the range
+ * @script: (out) (optional): location to store script for range
*
* Gets information about the range to which @iter currently points.
* The range is the set of locations p where *start <= p < *end.
* (That is, it doesn't include the character stored at *end)
*
* Note that while the type of the @script argument is declared
- * as PangoScript, as of Pango 1.18, this function simply returns
+ * as `PangoScript`, as of Pango 1.18, this function simply returns
* GUnicodeScript values. Callers must be prepared to handle unknown
* values.
*
* Since: 1.4
- **/
+ */
void
pango_script_iter_get_range (PangoScriptIter *iter,
const char **start,
@@ -292,16 +294,17 @@ get_pair_index (gunichar ch)
/**
* pango_script_iter_next:
- * @iter: a #PangoScriptIter
+ * @iter: a `PangoScriptIter`
+ *
+ * Advances a `PangoScriptIter` to the next range.
*
- * Advances a #PangoScriptIter to the next range. If @iter
- * is already at the end, it is left unchanged and %FALSE
- * is returned.
+ * If @iter is already at the end, it is left unchanged
+ * and %FALSE is returned.
*
- * Return value: %TRUE if @iter was successfully advanced.
+ * Return value: %TRUE if @iter was successfully advanced
*
* Since: 1.4
- **/
+ */
gboolean
pango_script_iter_next (PangoScriptIter *iter)
{
diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c
index 2c2717ee..1bb65621 100644
--- a/pango/pango-tabs.c
+++ b/pango/pango-tabs.c
@@ -292,8 +292,8 @@ pango_tab_array_set_tab (PangoTabArray *tab_array,
* pango_tab_array_get_tab:
* @tab_array: a `PangoTabArray`
* @tab_index: tab stop index
- * @alignment: (out) (allow-none): location to store alignment, or %NULL
- * @location: (out) (allow-none): location to store tab position, or %NULL
+ * @alignment: (out) (optional): location to store alignment, or %NULL
+ * @location: (out) (optional): location to store tab position, or %NULL
*
* Gets the alignment and position of a tab stop.
*/
@@ -317,9 +317,9 @@ pango_tab_array_get_tab (PangoTabArray *tab_array,
/**
* pango_tab_array_get_tabs:
* @tab_array: a `PangoTabArray`
- * @alignments: (out) (allow-none): location to store an array of tab
+ * @alignments: (out) (optional): location to store an array of tab
* stop alignments, or %NULL
- * @locations: (out) (allow-none) (array): location to store an array
+ * @locations: (out) (optional) (array): location to store an array
* of tab positions, or %NULL
*
* If non-%NULL, @alignments and @locations are filled with allocated
diff --git a/pango/pango-types.h b/pango/pango-types.h
index 2998d8ec..a7bcd747 100644
--- a/pango/pango-types.h
+++ b/pango/pango-types.h
@@ -150,41 +150,49 @@ struct _PangoRectangle
*/
/**
* PANGO_ASCENT:
- * @rect: a #PangoRectangle
+ * @rect: a `PangoRectangle`
*
- * Extracts the *ascent* from a #PangoRectangle
- * representing glyph extents. The ascent is the distance from the
- * baseline to the highest point of the character. This is positive if the
+ * Extracts the *ascent* from a `PangoRectangle`
+ * representing glyph extents.
+ *
+ * The ascent is the distance from the baseline to the
+ * highest point of the character. This is positive if the
* glyph ascends above the baseline.
*/
/**
* PANGO_DESCENT:
- * @rect: a #PangoRectangle
+ * @rect: a `PangoRectangle`
+ *
+ * Extracts the *descent* from a `PangoRectangle`
+ * representing glyph extents.
*
- * Extracts the *descent* from a #PangoRectangle
- * representing glyph extents. The descent is the distance from the
- * baseline to the lowest point of the character. This is positive if the
+ * The descent is the distance from the baseline to the
+ * lowest point of the character. This is positive if the
* glyph descends below the baseline.
*/
/**
* PANGO_LBEARING:
- * @rect: a #PangoRectangle
+ * @rect: a `PangoRectangle`
*
- * Extracts the *left bearing* from a #PangoRectangle
- * representing glyph extents. The left bearing is the distance from the
- * horizontal origin to the farthest left point of the character.
- * This is positive for characters drawn completely to the right of the
- * glyph origin.
+ * Extracts the *left bearing* from a `PangoRectangle`
+ * representing glyph extents.
+ *
+ * The left bearing is the distance from the horizontal
+ * origin to the farthest left point of the character.
+ * This is positive for characters drawn completely to
+ * the right of the glyph origin.
*/
/**
* PANGO_RBEARING:
- * @rect: a #PangoRectangle
+ * @rect: a `PangoRectangle`
+ *
+ * Extracts the *right bearing* from a `PangoRectangle`
+ * representing glyph extents.
*
- * Extracts the *right bearing* from a #PangoRectangle
- * representing glyph extents. The right bearing is the distance from the
- * horizontal origin to the farthest right point of the character.
- * This is positive except for characters drawn completely to the left of the
- * horizontal origin.
+ * The right bearing is the distance from the horizontal
+ * origin to the farthest right point of the character.
+ * This is positive except for characters drawn completely
+ * to the left of the horizontal origin.
*/
#define PANGO_ASCENT(rect) (-(rect).y)
#define PANGO_DESCENT(rect) ((rect).y + (rect).height)
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index 5283da35..0057859e 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -61,7 +61,7 @@
* Returns: The encoded version of Pango library available at run time.
*
* Since: 1.16
- **/
+ */
int
pango_version (void)
{
@@ -81,7 +81,7 @@ pango_version (void)
* be modified or freed.
*
* Since: 1.16
- **/
+ */
const char *
pango_version_string (void)
{
@@ -90,9 +90,9 @@ pango_version_string (void)
/**
* pango_version_check:
- * @required_major: the required major version.
- * @required_minor: the required minor version.
- * @required_micro: the required major version.
+ * @required_major: the required major version
+ * @required_minor: the required minor version
+ * @required_micro: the required major version
*
* Checks that the Pango library in use is compatible with the
* given version.
@@ -118,7 +118,7 @@ pango_version_string (void)
* be modified or freed.
*
* Since: 1.16
- **/
+ */
const gchar*
pango_version_check (int required_major,
int required_minor,
@@ -145,7 +145,7 @@ pango_version_check (int required_major,
* Return value: A newly-allocated string that must be freed with g_free()
*
* Deprecated: 1.38
- **/
+ */
char *
pango_trim_string (const char *str)
{
@@ -177,10 +177,10 @@ _pango_trim_string (const char *str)
* white space and substituting ~/ with $HOME/.
*
* Return value: (transfer full) (array zero-terminated=1): a list of
- * strings to be freed with g_strfreev()
+ * strings to be freed with g_strfreev()
*
* Deprecated: 1.38
- **/
+ */
char **
pango_split_file_list (const char *str)
{
@@ -238,7 +238,7 @@ pango_split_file_list (const char *str)
/**
* pango_read_line:
* @stream: a stdio stream
- * @str: #GString buffer into which to write the result
+ * @str: `GString` buffer into which to write the result
*
* Reads an entire line from a file into a buffer.
*
@@ -254,7 +254,7 @@ pango_split_file_list (const char *str)
* a line number counter which doesn't combine lines with '\')
*
* Deprecated: 1.38
- **/
+ */
gint
pango_read_line (FILE *stream, GString *str)
{
@@ -355,10 +355,10 @@ pango_read_line (FILE *stream, GString *str)
* Skips 0 or more characters of white space.
*
* Return value: %FALSE if skipping the white space leaves
- * the position at a '\0' character.
+ * the position at a '\0' character.
*
* Deprecated: 1.38
- **/
+ */
gboolean
pango_skip_space (const char **pos)
{
@@ -375,17 +375,17 @@ pango_skip_space (const char **pos)
/**
* pango_scan_word:
* @pos: (inout): in/out string position
- * @out: a #GString into which to write the result
+ * @out: a `GString` into which to write the result
*
- * Scans a word into a #GString buffer.
+ * Scans a word into a `GString` buffer.
*
* A word consists of [A-Za-z_] followed by zero or more
* [A-Za-z_0-9]. Leading white space is skipped.
*
- * Return value: %FALSE if a parse error occurred.
+ * Return value: %FALSE if a parse error occurred
*
* Deprecated: 1.38
- **/
+ */
gboolean
pango_scan_word (const char **pos, GString *out)
{
@@ -420,18 +420,18 @@ pango_scan_word (const char **pos, GString *out)
/**
* pango_scan_string:
* @pos: (inout): in/out string position
- * @out: a #GString into which to write the result
+ * @out: a `GString` into which to write the result
*
- * Scans a string into a #GString buffer.
+ * Scans a string into a `GString` buffer.
*
* The string may either be a sequence of non-white-space characters,
* or a quoted string with '"'. Instead a quoted string, '\"' represents
* a literal quote. Leading white space outside of quotes is skipped.
*
- * Return value: %FALSE if a parse error occurred.
+ * Return value: %FALSE if a parse error occurred
*
* Deprecated: 1.38
- **/
+ */
gboolean
pango_scan_string (const char **pos, GString *out)
{
@@ -519,10 +519,10 @@ pango_scan_string (const char **pos, GString *out)
*
* Leading white space is skipped.
*
- * Return value: %FALSE if a parse error occurred.
+ * Return value: %FALSE if a parse error occurred
*
* Deprecated: 1.38
- **/
+ */
gboolean
pango_scan_int (const char **pos, int *out)
{
@@ -556,14 +556,14 @@ _pango_scan_int (const char **pos, int *out)
/**
* pango_config_key_get_system:
- * @key: Key to look up, in the form "SECTION/KEY".
+ * @key: Key to look up, in the form "SECTION/KEY"
*
* Do not use. Does not do anything.
*
* Return value: %NULL
*
* Deprecated: 1.38
- **/
+ */
char *
pango_config_key_get_system (const char *key)
{
@@ -572,14 +572,14 @@ pango_config_key_get_system (const char *key)
/**
* pango_config_key_get:
- * @key: Key to look up, in the form "SECTION/KEY".
+ * @key: Key to look up, in the form "SECTION/KEY"
*
* Do not use. Does not do anything.
*
* Return value: %NULL
*
* Deprecated: 1.38
- **/
+ */
char *
pango_config_key_get (const char *key)
{
@@ -672,28 +672,30 @@ parse_int (const char *word,
/**
* pango_parse_enum:
- * @type: enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE.
- * @str: (allow-none): string to parse. May be %NULL.
- * @value: (out) (allow-none): integer to store the result in, or %NULL.
- * @warn: if %TRUE, issue a g_warning() on bad input.
- * @possible_values: (out) (allow-none): place to store list of possible values on failure, or %NULL.
+ * @type: enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE
+ * @str: (nullable): string to parse
+ * @value: (out) (optional): integer to store the result in
+ * @warn: if %TRUE, issue a g_warning() on bad input
+ * @possible_values: (out) (optional): place to store list of possible
+ * values on failure
*
* Parses an enum type and stores the result in @value.
*
- * If @str does not match the nick name of any of the possible values for the
- * enum and is not an integer, %FALSE is returned, a warning is issued
- * if @warn is %TRUE, and a
- * string representing the list of possible values is stored in
- * @possible_values. The list is slash-separated, eg.
- * "none/start/middle/end". If failed and @possible_values is not %NULL,
- * returned string should be freed using g_free().
+ * If @str does not match the nick name of any of the possible values
+ * for the enum and is not an integer, %FALSE is returned, a warning
+ * is issued if @warn is %TRUE, and a string representing the list of
+ * possible values is stored in @possible_values. The list is
+ * slash-separated, eg. "none/start/middle/end".
*
- * Return value: %TRUE if @str was successfully parsed.
+ * If failed and @possible_values is not %NULL, returned string should
+ * be freed using g_free().
+ *
+ * Return value: %TRUE if @str was successfully parsed
*
* Deprecated: 1.38
*
* Since: 1.16
- **/
+ */
gboolean
pango_parse_enum (GType type,
const char *str,
@@ -822,10 +824,10 @@ pango_parse_flags (GType type,
/**
* pango_lookup_aliases:
- * @fontname: an ascii string
- * @families: (out) (array length=n_families): will be set to an array of font family names.
- * this array is owned by pango and should not be freed.
- * @n_families: (out): will be set to the length of the @families array.
+ * @fontname: an ASCII string
+ * @families: (out) (array length=n_families): will be set to an array of
+ * font family names. This array is owned by Pango and should not be freed
+ * @n_families: (out): will be set to the length of the @families array
*
* Look up all user defined aliases for the alias @fontname.
*
@@ -848,14 +850,14 @@ pango_lookup_aliases (const char *fontname,
/**
* pango_find_base_dir:
- * @text: the text to process. Must be valid UTF-8
+ * @text: the text to process. Must be valid UTF-8
* @length: length of @text in bytes (may be -1 if @text is nul-terminated)
*
* Searches a string the first character that has a strong
* direction, according to the Unicode bidirectional algorithm.
*
* Return value: The direction corresponding to the first strong character.
- * If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned.
+ * If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned.
*
* Since: 1.4
*/
@@ -1016,8 +1018,8 @@ pango_units_to_double (int i)
/**
* pango_extents_to_pixels:
- * @inclusive: (allow-none): rectangle to round to pixels inclusively, or %NULL.
- * @nearest: (allow-none): rectangle to round to nearest pixels, or %NULL.
+ * @inclusive: (nullable): rectangle to round to pixels inclusively
+ * @nearest: (nullable): rectangle to round to nearest pixels
*
* Converts extents from Pango units to device units.
*
@@ -1038,7 +1040,7 @@ pango_units_to_double (int i)
* as @nearest.
*
* Since: 1.16
- **/
+ */
void
pango_extents_to_pixels (PangoRectangle *inclusive,
PangoRectangle *nearest)
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index d880f1b3..08a90678 100644
--- a/pango/pangocairo-context.c
+++ b/pango/pangocairo-context.c
@@ -164,9 +164,8 @@ _pango_cairo_update_context (cairo_t *cr,
* match the current transformation and target surface of a Cairo
* context.
*
- * If any layouts have been created for the context,
- * it's necessary to call [method@Pango.Layout.context_changed] on those
- * layouts.
+ * If any layouts have been created for the context, it's necessary
+ * to call [method@Pango.Layout.context_changed] on those layouts.
*
* Since: 1.10
*/
@@ -189,10 +188,9 @@ pango_cairo_update_context (cairo_t *cr,
*
* Sets the resolution for the context.
*
- * This is a scale factor between
- * points specified in a `PangoFontDescription` and Cairo units. The
- * default value is 96, meaning that a 10 point font will be 13
- * units high. (10 * 96. / 72. = 13.3).
+ * This is a scale factor between points specified in a `PangoFontDescription`
+ * and Cairo units. The default value is 96, meaning that a 10 point font will
+ * be 13 units high. (10 * 96. / 72. = 13.3).
*
* Since: 1.10
*/
@@ -209,6 +207,7 @@ pango_cairo_context_set_resolution (PangoContext *context,
* @context: a `PangoContext`, from a pangocairo font map
*
* Gets the resolution for the context.
+ *
* See [func@PangoCairo.context_set_resolution]
*
* Return value: the resolution in "dots per inch". A negative value will
@@ -289,9 +288,8 @@ pango_cairo_context_set_font_options (PangoContext *context,
* Retrieves any font rendering options previously set with
* [func@PangoCairo.context_set_font_options].
*
- * This function
- * does not report options that are derived from the target
- * surface by [func@update_context].
+ * This function does not report options that are derived from
+ * the target surface by [func@update_context].
*
* Return value: (nullable): the font options previously set on the
* context, or %NULL if no options have been set. This value is
@@ -347,10 +345,10 @@ _pango_cairo_context_get_merged_font_options (PangoContext *context)
* pango_cairo_context_set_shape_renderer:
* @context: a `PangoContext`, from a pangocairo font map
* @func: (nullable): Callback function for rendering attributes of
- * type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering.
- * @data: User data that will be passed to @func.
- * @dnotify: Callback that will be called when the
- * context is freed to release @data, or %NULL.
+ * type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering.
+ * @data: (nullable): User data that will be passed to @func.
+ * @dnotify: (nullable): Callback that will be called when the
+ * context is freed to release @data
*
* Sets callback function for context to use for rendering attributes
* of type %PANGO_ATTR_SHAPE.
@@ -382,7 +380,7 @@ pango_cairo_context_set_shape_renderer (PangoContext *context,
/**
* pango_cairo_context_get_shape_renderer: (skip)
* @context: a `PangoContext`, from a pangocairo font map
- * @data: Pointer to #gpointer to return user data
+ * @data: Pointer to `gpointer` to return user data
*
* Sets callback function for context to use for rendering attributes
* of type %PANGO_ATTR_SHAPE.
@@ -438,8 +436,7 @@ pango_cairo_context_get_shape_renderer (PangoContext *context,
* create a layout for use with @cr and do not need to access `PangoContext`
* directly, you can use [func@create_layout] instead.
*
- * Return value: (transfer full): the newly created `PangoContext`.
- * Free with g_object_unref().
+ * Return value: (transfer full): the newly created `PangoContext`
*
* Since: 1.22
*/
@@ -465,9 +462,8 @@ pango_cairo_create_context (cairo_t *cr)
* Creates a layout object set up to match the current transformation
* and target surface of the Cairo context.
*
- * This layout can then be
- * used for text measurement with functions like
- * [method@Pango.Layout.get_size] or drawing with functions like
+ * This layout can then be used for text measurement with functions
+ * like [method@Pango.Layout.get_size] or drawing with functions like
* [func@show_layout]. If you change the transformation or target
* surface for @cr, you need to call [func@update_layout].
*
@@ -476,8 +472,7 @@ pango_cairo_create_context (cairo_t *cr)
* `PangoContext` object for each layout. This might matter in an
* application that was laying out large amounts of text.
*
- * Return value: (transfer full): the newly created `PangoLayout`.
- * Free with g_object_unref().
+ * Return value: (transfer full): the newly created `PangoLayout`
*
* Since: 1.10
*/
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 9e3cfab8..2c552ba1 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -1203,8 +1203,8 @@ pango_cairo_glyph_string_path (cairo_t *cr,
* Adds the text in `PangoLayoutLine` to the current path in the
* specified cairo context.
*
- * The origin of the glyphs (the left edge
- * of the line) will be at the current point of the cairo context.
+ * The origin of the glyphs (the left edge of the line) will be
+ * at the current point of the cairo context.
*
* Since: 1.10
*/
@@ -1226,8 +1226,8 @@ pango_cairo_layout_line_path (cairo_t *cr,
* Adds the text in a `PangoLayout` to the current path in the
* specified cairo context.
*
- * The top-left corner of the `PangoLayout`
- * will be at the current point of the cairo context.
+ * The top-left corner of the `PangoLayout` will be at the
+ * current point of the cairo context.
*
* Since: 1.10
*/
@@ -1253,9 +1253,8 @@ pango_cairo_layout_path (cairo_t *cr,
* approximately covers the given rectangle in the style of an underline used
* to indicate a spelling error.
*
- * The width of the underline is rounded to an
- * integer number of up/down segments and the resulting rectangle is centered
- * in the original rectangle.
+ * The width of the underline is rounded to an integer number of up/down
+ * segments and the resulting rectangle is centered in the original rectangle.
*
* Since: 1.14
*/
diff --git a/pango/pangocoretext.c b/pango/pangocoretext.c
index 5f9cf2df..ccb3f674 100644
--- a/pango/pangocoretext.c
+++ b/pango/pangocoretext.c
@@ -266,7 +266,7 @@ _pango_core_text_font_set_ctfont (PangoCoreTextFont *font,
/**
* pango_core_text_font_get_ctfont:
- * @font: A #PangoCoreTextFont
+ * @font: A `PangoCoreTextFont`
*
* Returns the CTFontRef of a font.
*
diff --git a/pango/pangofc-font-private.h b/pango/pangofc-font-private.h
index 588bd512..532aed2f 100644
--- a/pango/pangofc-font-private.h
+++ b/pango/pangofc-font-private.h
@@ -32,7 +32,7 @@ G_BEGIN_DECLS
*
* A string constant used to identify shape engines that work
* with the fontconfig based backends. See the @engine_type field
- * of #PangoEngineInfo.
+ * of `PangoEngineInfo`.
**/
#define PANGO_RENDER_TYPE_FC "PangoRenderFc"
@@ -46,7 +46,7 @@ G_BEGIN_DECLS
* the reference count for the face by one.
* @unlock_face: Decreases the reference count for the
* FT_Face of the font by one. When the count is zero,
- * the #PangoFcFont subclass is allowed to free the
+ * the `PangoFcFont` subclass is allowed to free the
* FT_Face.
* @has_char: Return %TRUE if the the font contains a glyph
* corresponding to the specified character.
@@ -59,7 +59,7 @@ G_BEGIN_DECLS
* shutdown code that needs to be done when
* pango_fc_font_map_shutdown is called. May be %NULL.
*
- * Class structure for #PangoFcFont.
+ * Class structure for `PangoFcFont`.
**/
struct _PangoFcFontClass
{
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index 5a164343..2bd84276 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -567,7 +567,7 @@ pango_fc_font_unlock_face (PangoFcFont *font)
/**
* pango_fc_font_has_char:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
* @wc: Unicode codepoint to look up
*
* Determines whether @font has a glyph for the codepoint @wc.
@@ -575,7 +575,7 @@ pango_fc_font_unlock_face (PangoFcFont *font)
* Return value: %TRUE if @font has the requested codepoint.
*
* Since: 1.4
- * Deprecated: 1.44: Use pango_font_has_char()
+ * Deprecated: 1.44: Use [method@Pango.Font.has_char]
*/
gboolean
pango_fc_font_has_char (PangoFcFont *font,
@@ -597,7 +597,7 @@ pango_fc_font_has_char (PangoFcFont *font,
/**
* pango_fc_font_get_glyph:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
* @wc: Unicode character to look up
*
* Gets the glyph index for a given Unicode character
@@ -632,11 +632,11 @@ pango_fc_font_get_glyph (PangoFcFont *font,
/**
* pango_fc_font_get_unknown_glyph:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
* @wc: the Unicode character for which a glyph is needed.
*
- * Returns the index of a glyph suitable for drawing @wc as an
- * unknown character.
+ * Returns the index of a glyph suitable for drawing @wc
+ * as an unknown character.
*
* Use PANGO_GET_UNKNOWN_GLYPH() instead.
*
@@ -665,7 +665,7 @@ _pango_fc_font_shutdown (PangoFcFont *font)
/**
* pango_fc_font_kern_glyphs:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
* @glyphs: a `PangoGlyphString`
*
* This function used to adjust each adjacent pair of glyphs
@@ -1043,7 +1043,7 @@ done:
* and its fontmap are valid.
*
* Returns: (transfer none) (nullable): a %NULL-terminated
- * array of `PangoLanguage`*
+ * array of `PangoLanguage`*
*
* Since: 1.48
*/
diff --git a/pango/pangofc-fontmap-private.h b/pango/pangofc-fontmap-private.h
index b32982f2..e081147d 100644
--- a/pango/pangofc-fontmap-private.h
+++ b/pango/pangofc-fontmap-private.h
@@ -83,11 +83,11 @@ const char *pango_fc_font_key_get_variations (const PangoFcFontKey *key)
/**
* PangoFcFontMap:
*
- * #PangoFcFontMap is a base class for font map implementations
+ * `PangoFcFontMap` is a base class for font map implementations
* using the Fontconfig and FreeType libraries. To create a new
* backend using Fontconfig and FreeType, you derive from this class
* and implement a new_font() virtual function that creates an
- * instance deriving from #PangoFcFont.
+ * instance deriving from `PangoFcFont`.
**/
struct _PangoFcFontMap
{
@@ -111,10 +111,10 @@ struct _PangoFcFontMap
* Implementations must call substitute_func if it is
* defined. May be %NULL. Deprecated in favor of
* @font_key_substitute().
- * @new_font: Creates a new #PangoFcFont for the specified
+ * @new_font: Creates a new `PangoFcFont` for the specified
* pattern of the appropriate type for this font map. The
* @pattern argument must be passed to the "pattern" property
- * of #PangoFcFont when you call g_object_new(). Deprecated
+ * of `PangoFcFont` when you call g_object_new(). Deprecated
* in favor of @create_font().
* @get_resolution: Gets the resolution (the scale factor
* between logical and absolute font sizes) that the backend
@@ -138,16 +138,16 @@ struct _PangoFcFontMap
* #FcPattern. This will be called prior to creating a font
* for the pattern. Implementations must call substitute_func
* if it is defined. May be %NULL. (Since: 1.24)
- * @create_font: (nullable): Creates a new #PangoFcFont for
+ * @create_font: (nullable): Creates a new `PangoFcFont` for
* the specified pattern of the appropriate type for this
* font map using information from the font key that is
* passed in. The @pattern member of @font_key can be
* retrieved using pango_fc_font_key_get_pattern() and must
- * be passed to the "pattern" property of #PangoFcFont when
+ * be passed to the "pattern" property of `PangoFcFont` when
* you call g_object_new(). If %NULL, new_font() is used.
* (Since: 1.24)
*
- * Class structure for #PangoFcFontMap.
+ * Class structure for `PangoFcFontMap`.
**/
struct _PangoFcFontMapClass
{
diff --git a/pango/pangofc-fontmap.h b/pango/pangofc-fontmap.h
index 8ae9250e..074bca20 100644
--- a/pango/pangofc-fontmap.h
+++ b/pango/pangofc-fontmap.h
@@ -119,10 +119,9 @@ typedef void (*PangoFcSubstituteFunc) (FcPattern *pattern,
/**
* pango_fc_font_map_set_default_substitute:
* @fontmap: a `PangoFcFontMap`
- * @func: function to call to to do final config tweaking
- * on `FcPattern` objects.
+ * @func: function to call to to do final config tweaking on `FcPattern` objects
* @data: data to pass to @func
- * @notify: function to call when @data is no longer used.
+ * @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
diff --git a/pango/pangoft2-render.c b/pango/pangoft2-render.c
index 45ac5820..f2da8e7f 100644
--- a/pango/pangoft2-render.c
+++ b/pango/pangoft2-render.c
@@ -579,16 +579,18 @@ pango_ft2_renderer_draw_trapezoid (PangoRenderer *renderer,
/**
* pango_ft2_render_layout_subpixel:
- * @bitmap: a FT_Bitmap to render the layout onto
- * @layout: a #PangoLayout
- * @x: the X position of the left of the layout (in Pango units)
- * @y: the Y position of the top of the layout (in Pango units)
+ * @bitmap: a FT_Bitmap to render the layout onto
+ * @layout: a `PangoLayout`
+ * @x: the X position of the left of the layout (in Pango units)
+ * @y: the Y position of the top of the layout (in Pango units)
*
- * Render a #PangoLayout onto a FreeType2 bitmap, with he
+ * Render a `PangoLayout` onto a FreeType2 bitmap, with he
* location specified in fixed-point Pango units rather than
- * pixels. (Using this will avoid extra inaccuracies from
- * rounding to integer pixels multiple times, even if the
- * final glyph positions are integers.)
+ * pixels.
+ *
+ * (Using this will avoid extra inaccuracies from rounding
+ * to integer pixels multiple times, even if the final glyph
+ * positions are integers.)
*
* Since: 1.6
*/
@@ -616,12 +618,12 @@ pango_ft2_render_layout_subpixel (FT_Bitmap *bitmap,
/**
* pango_ft2_render_layout:
- * @bitmap: a FT_Bitmap to render the layout onto
- * @layout: a #PangoLayout
- * @x: the X position of the left of the layout (in pixels)
- * @y: the Y position of the top of the layout (in pixels)
+ * @bitmap: a FT_Bitmap to render the layout onto
+ * @layout: a `PangoLayout`
+ * @x: the X position of the left of the layout (in pixels)
+ * @y: the Y position of the top of the layout (in pixels)
*
- * Render a #PangoLayout onto a FreeType2 bitmap
+ * Render a `PangoLayout` onto a FreeType2 bitmap
*/
void
pango_ft2_render_layout (FT_Bitmap *bitmap,
@@ -634,16 +636,18 @@ pango_ft2_render_layout (FT_Bitmap *bitmap,
/**
* pango_ft2_render_layout_line_subpixel:
- * @bitmap: a FT_Bitmap to render the line onto
- * @line: a #PangoLayoutLine
- * @x: the x position of start of string (in Pango units)
- * @y: the y position of baseline (in Pango units)
+ * @bitmap: a FT_Bitmap to render the line onto
+ * @line: a `PangoLayoutLine`
+ * @x: the x position of start of string (in Pango units)
+ * @y: the y position of baseline (in Pango units)
*
- * Render a #PangoLayoutLine onto a FreeType2 bitmap, with he
+ * Render a `PangoLayoutLine` onto a FreeType2 bitmap, with he
* location specified in fixed-point Pango units rather than
- * pixels. (Using this will avoid extra inaccuracies from
- * rounding to integer pixels multiple times, even if the
- * final glyph positions are integers.)
+ * pixels.
+ *
+ * (Using this will avoid extra inaccuracies from rounding
+ * to integer pixels multiple times, even if the final glyph
+ * positions are integers.)
*
* Since: 1.6
*/
@@ -671,12 +675,12 @@ pango_ft2_render_layout_line_subpixel (FT_Bitmap *bitmap,
/**
* pango_ft2_render_layout_line:
- * @bitmap: a FT_Bitmap to render the line onto
- * @line: a #PangoLayoutLine
- * @x: the x position of start of string (in pixels)
- * @y: the y position of baseline (in pixels)
+ * @bitmap: a FT_Bitmap to render the line onto
+ * @line: a `PangoLayoutLine`
+ * @x: the x position of start of string (in pixels)
+ * @y: the y position of baseline (in pixels)
*
- * Render a #PangoLayoutLine onto a FreeType2 bitmap
+ * Render a `PangoLayoutLine` onto a FreeType2 bitmap
*/
void
pango_ft2_render_layout_line (FT_Bitmap *bitmap,
@@ -689,25 +693,26 @@ pango_ft2_render_layout_line (FT_Bitmap *bitmap,
/**
* pango_ft2_render_transformed:
- * @bitmap: the FreeType2 bitmap onto which to draw the string
- * @font: the font in which to draw the string
- * @matrix: (nullable): a #PangoMatrix, or %NULL to use an identity
- * transformation
- * @glyphs: the glyph string to draw
- * @x: the x position of the start of the string (in Pango
- * units in user space coordinates)
- * @y: the y position of the baseline (in Pango units
- * in user space coordinates)
+ * @bitmap: the FreeType2 bitmap onto which to draw the string
+ * @font: the font in which to draw the string
+ * @matrix: (nullable): a `PangoMatrix`
+ * @glyphs: the glyph string to draw
+ * @x: the x position of the start of the string (in Pango
+ * units in user space coordinates)
+ * @y: the y position of the baseline (in Pango units
+ * in user space coordinates)
*
- * Renders a #PangoGlyphString onto a FreeType2 bitmap, possibly
+ * Renders a `PangoGlyphString` onto a FreeType2 bitmap, possibly
* transforming the layed-out coordinates through a transformation
- * matrix. Note that the transformation matrix for @font is not
+ * matrix.
+ *
+ * Note that the transformation matrix for @font is not
* changed, so to produce correct rendering results, the @font
- * must have been loaded using a #PangoContext with an identical
+ * must have been loaded using a `PangoContext` with an identical
* transformation matrix to that passed in to this function.
*
* Since: 1.6
- **/
+ */
void
pango_ft2_render_transformed (FT_Bitmap *bitmap,
const PangoMatrix *matrix,
@@ -734,14 +739,14 @@ pango_ft2_render_transformed (FT_Bitmap *bitmap,
/**
* pango_ft2_render:
- * @bitmap: the FreeType2 bitmap onto which to draw the string
- * @font: the font in which to draw the string
- * @glyphs: the glyph string to draw
- * @x: the x position of the start of the string (in pixels)
- * @y: the y position of the baseline (in pixels)
+ * @bitmap: the FreeType2 bitmap onto which to draw the string
+ * @font: the font in which to draw the string
+ * @glyphs: the glyph string to draw
+ * @x: the x position of the start of the string (in pixels)
+ * @y: the y position of the baseline (in pixels)
*
- * Renders a #PangoGlyphString onto a FreeType2 bitmap.
- **/
+ * Renders a `PangoGlyphString` onto a FreeType2 bitmap.
+ */
void
pango_ft2_render (FT_Bitmap *bitmap,
PangoFont *font,
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index efaf853d..f330ef7c 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -152,18 +152,21 @@ set_transform (PangoFT2Font *ft2font)
/**
* pango_ft2_font_get_face: (skip)
- * @font: a #PangoFont
+ * @font: a `PangoFont`
*
- * Returns the native FreeType2 `FT_Face` structure used for this #PangoFont.
- * This may be useful if you want to use FreeType2 functions directly.
+ * Returns the native FreeType2 `FT_Face` structure
+ * used for this `PangoFont`.
*
- * Use pango_fc_font_lock_face() instead; when you are done with a
- * face from pango_fc_font_lock_face() you must call
- * pango_fc_font_unlock_face().
+ * This may be useful if you want to use FreeType2
+ * functions directly.
*
- * Return value: (nullable): a pointer to a `FT_Face` structure, with the
- * size set correctly, or %NULL if @font is %NULL.
- **/
+ * Use [method@PangoFc.Font.lock_face] instead; when you are
+ * done with a face from [method@PangoFc.Font.lock_face], you
+ * must call [method@PangoFc.Font.unlock_face].
+ *
+ * Return value: (nullable): a pointer to a `FT_Face` structure,
+ * with the size set correctly
+ */
FT_Face
pango_ft2_font_get_face (PangoFont *font)
{
@@ -378,17 +381,17 @@ pango_ft2_font_get_glyph_extents (PangoFont *font,
/**
* pango_ft2_font_get_kerning:
- * @font: a #PangoFont
- * @left: the left #PangoGlyph
- * @right: the right #PangoGlyph
+ * @font: a `PangoFont`
+ * @left: the left `PangoGlyph`
+ * @right: the right `PangoGlyph`
*
* Retrieves kerning information for a combination of two glyphs.
*
* Use pango_fc_font_kern_glyphs() instead.
*
- * Return value: The amount of kerning (in Pango units) to apply for
- * the given combination of glyphs.
- **/
+ * Return value: The amount of kerning (in Pango units) to
+ * apply for the given combination of glyphs.
+ */
int
pango_ft2_font_get_kerning (PangoFont *font,
PangoGlyph left,
@@ -470,11 +473,12 @@ pango_ft2_font_finalize (GObject *object)
* @font: a Pango FT2 font
* @language: a language tag.
*
- * Gets the #PangoCoverage for a `PangoFT2Font`. Use
- * pango_font_get_coverage() instead.
+ * Gets the `PangoCoverage` for a `PangoFT2Font`.
*
- * Return value: (transfer full): a #PangoCoverage.
- **/
+ * Use [method@Pango.Font.get_coverage] instead.
+ *
+ * Return value: (transfer full): a `PangoCoverage`
+ */
PangoCoverage *
pango_ft2_font_get_coverage (PangoFont *font,
PangoLanguage *language)
@@ -486,17 +490,18 @@ pango_ft2_font_get_coverage (PangoFont *font,
/**
* pango_ft2_get_unknown_glyph:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
*
- * Return the index of a glyph suitable for drawing unknown characters with
- * @font, or %PANGO_GLYPH_EMPTY if no suitable glyph found.
+ * Return the index of a glyph suitable for drawing unknown
+ * characters with @font, or %PANGO_GLYPH_EMPTY if no suitable
+ * glyph found.
*
- * If you want to draw an unknown-box for a character that is not covered
- * by the font,
- * use PANGO_GET_UNKNOWN_GLYPH() instead.
+ * If you want to draw an unknown-box for a character that
+ * is not covered by the font, use PANGO_GET_UNKNOWN_GLYPH()
+ * instead.
*
* Return value: a glyph index into @font, or %PANGO_GLYPH_EMPTY
- **/
+ */
PangoGlyph
pango_ft2_get_unknown_glyph (PangoFont *font)
{
diff --git a/pango/pangowin32-fontcache.c b/pango/pangowin32-fontcache.c
index 1a1a1cef..bca80270 100644
--- a/pango/pangowin32-fontcache.c
+++ b/pango/pangowin32-fontcache.c
@@ -38,7 +38,7 @@ typedef struct _CacheEntry CacheEntry;
/**
* PangoWin32FontCache:
*
- * A #PangoWin32FontCache caches HFONTs by their LOGFONT descriptions.
+ * A `PangoWin32FontCache` caches HFONTs by their LOGFONT descriptions.
*/
struct _PangoWin32FontCache
{
@@ -72,11 +72,13 @@ free_cache_entry (LOGFONTW *logfont,
/**
* pango_win32_font_cache_free:
- * @cache: a #PangoWin32FontCache
+ * @cache: a `PangoWin32FontCache`
*
- * Frees a #PangoWin32FontCache and all associated memory. All fonts loaded
- * through this font cache will be freed along with the cache.
- **/
+ * Frees a `PangoWin32FontCache` and all associated memory.
+ *
+ * All fonts loaded through this font cache will be freed
+ * along with the cache.
+ */
void
pango_win32_font_cache_free (PangoWin32FontCache *cache)
{
@@ -178,7 +180,7 @@ cache_entry_unref (PangoWin32FontCache *cache,
/**
* pango_win32_font_cache_load:
- * @cache: a #PangoWin32FontCache
+ * @cache: a `PangoWin32FontCache`
* @logfont: a pointer to a LOGFONTA structure describing the font to load.
*
* Creates a HFONT from a LOGFONTA. The
@@ -186,9 +188,9 @@ cache_entry_unref (PangoWin32FontCache *cache,
* stored
*
* Return value: (nullable): The font structure, or %NULL if the font
- * could not be loaded. In order to free this structure, you must call
- * pango_win32_font_cache_unload().
- **/
+ * could not be loaded. In order to free this structure, you must call
+ * [method@Pango.Win32FontCache.unload].
+ */
HFONT
pango_win32_font_cache_load (PangoWin32FontCache *cache,
const LOGFONTA *lfp)
@@ -208,7 +210,7 @@ pango_win32_font_cache_load (PangoWin32FontCache *cache,
/**
* pango_win32_font_cache_loadw:
- * @cache: a #PangoWin32FontCache
+ * @cache: a `PangoWin32FontCache`
* @logfont: a pointer to a LOGFONTW structure describing the font to load.
*
* Creates a HFONT from a LOGFONTW. The
@@ -216,11 +218,11 @@ pango_win32_font_cache_load (PangoWin32FontCache *cache,
* stored
*
* Return value: (nullable): The font structure, or %NULL if the font
- * could not be loaded. In order to free this structure, you must call
- * pango_win32_font_cache_unload().
+ * could not be loaded. In order to free this structure, you must call
+ * [method@Pango.Win32FontCache.unload].
*
* Since: 1.16
- **/
+ */
HFONT
pango_win32_font_cache_loadw (PangoWin32FontCache *cache,
const LOGFONTW *lfp)
@@ -412,11 +414,12 @@ pango_win32_font_cache_loadw (PangoWin32FontCache *cache,
/**
* pango_win32_font_cache_unload:
- * @cache: a #PangoWin32FontCache
+ * @cache: a `PangoWin32FontCache`
* @hfont: the HFONT to unload
*
- * Frees a font structure previously loaded with pango_win32_font_cache_load().
- **/
+ * Frees a font structure previously loaded with
+ * [method@Pango.Win32FontCache.load].
+ */
void
pango_win32_font_cache_unload (PangoWin32FontCache *cache,
HFONT hfont)
diff --git a/pango/pangowin32-fontmap.c b/pango/pangowin32-fontmap.c
index 18d4544e..4cf2df3a 100644
--- a/pango/pangowin32-fontmap.c
+++ b/pango/pangowin32-fontmap.c
@@ -816,11 +816,13 @@ _pango_win32_font_map_class_init (PangoWin32FontMapClass *class)
/**
* pango_win32_font_map_for_display:
*
- * Returns a PangoWin32FontMap. Font maps are cached and should
- * not be freed. If the font map is no longer needed, it can
- * be released with pango_win32_shutdown_display().
+ * Returns a `PangoWin32FontMap`.
*
- * Return value: a #PangoFontMap.
+ * Font maps are cached and should not be freed. If
+ * the font map is no longer needed, it can be released
+ * with [func@Pango.win32_shutdown_display].
+ *
+ * Return value: a `PangoFontMap`
**/
PangoFontMap *
pango_win32_font_map_for_display (void)
@@ -1296,18 +1298,18 @@ get_family_nameA (const LOGFONTA *lfp)
* pango_win32_font_description_from_logfont:
* @lfp: a LOGFONTA
*
- * Creates a #PangoFontDescription that matches the specified LOGFONTA.
+ * Creates a `PangoFontDescription` that matches the specified LOGFONTA.
*
* The face name, italicness and weight fields in the LOGFONTA are used
- * to set up the resulting #PangoFontDescription. If the face name in
+ * to set up the resulting `PangoFontDescription`. If the face name in
* the LOGFONTA contains non-ASCII characters the font is temporarily
* loaded (using CreateFontIndirect()) and an ASCII (usually English)
* name for it is looked up from the font name tables in the font
* data. If that doesn't work, the face name is converted from the
* system codepage to UTF-8 and that is used.
*
- * Return value: the newly allocated #PangoFontDescription, which
- * should be freed using pango_font_description_free()
+ * Return value: the newly allocated `PangoFontDescription`, which
+ * should be freed using [method@Pango.FontDescription.free]
*
* Since: 1.12
*/
@@ -1481,18 +1483,18 @@ get_family_nameW (const LOGFONTW *lfp)
* pango_win32_font_description_from_logfontw:
* @lfp: a LOGFONTW
*
- * Creates a #PangoFontDescription that matches the specified LOGFONTW.
+ * Creates a `PangoFontDescription` that matches the specified LOGFONTW.
*
* The face name, italicness and weight fields in the LOGFONTW are used
- * to set up the resulting #PangoFontDescription. If the face name in
+ * to set up the resulting `PangoFontDescription`. If the face name in
* the LOGFONTW contains non-ASCII characters the font is temporarily
* loaded (using CreateFontIndirect()) and an ASCII (usually English)
* name for it is looked up from the font name tables in the font
* data. If that doesn't work, the face name is converted from UTF-16
* to UTF-8 and that is used.
*
- * Return value: the newly allocated #PangoFontDescription, which
- * should be freed using pango_font_description_free()
+ * Return value: the newly allocated `PangoFontDescription`, which
+ * should be freed using [method@Pango.FontDescription.free]
*
* Since: 1.16
*/
@@ -1801,12 +1803,12 @@ pango_win32_face_list_sizes (PangoFontFace *face,
/**
* pango_win32_font_map_get_font_cache:
- * @font_map: a PangoWin32FontMap
+ * @font_map: a `PangoWin32FontMap`
*
* Obtains the font cache associated with the given font map.
*
- * Return value: the #PangoWin32FontCache of @font_map.
- **/
+ * Return value: the `PangoWin32FontCache` of @font_map.
+ */
PangoWin32FontCache *
pango_win32_font_map_get_font_cache (PangoFontMap *font_map)
{
diff --git a/pango/pangowin32.c b/pango/pangowin32.c
index 12b4a36e..c8a5b46c 100644
--- a/pango/pangowin32.c
+++ b/pango/pangowin32.c
@@ -100,13 +100,13 @@ _pango_win32_font_get_hfont (PangoFont *font)
/**
* pango_win32_get_context:
*
- * Retrieves a #PangoContext appropriate for rendering with Windows fonts.
+ * Retrieves a `PangoContext` appropriate for rendering with Windows fonts.
*
- * Return value: the new #PangoContext
+ * Return value: the new `PangoContext`
*
- * Deprecated: 1.22: Use pango_win32_font_map_for_display() followed by
- * pango_font_map_create_context() instead.
- **/
+ * Deprecated: 1.22: Use [func@Pango.Win32FontMap.for_display] followed by
+ * [method@Pango.FontMap.create_context] instead.
+ */
PangoContext *
pango_win32_get_context (void)
{
@@ -214,7 +214,7 @@ _pango_win32_font_class_init (PangoWin32FontClass *class)
* @x: the x position of start of string (in pixels)
* @y: the y position of baseline (in pixels)
*
- * Render a #PangoGlyphString onto a Windows DC
+ * Render a `PangoGlyphString` onto a Windows DC
*/
void
pango_win32_render (HDC hdc,
@@ -370,23 +370,24 @@ pango_win32_render (HDC hdc,
/**
* pango_win32_render_transformed:
- * @hdc: a windows device context
- * @matrix: (nullable): a #PangoMatrix, or %NULL to use an identity
- * transformation
- * @font: the font in which to draw the string
- * @glyphs: the glyph string to draw
- * @x: the x position of the start of the string (in Pango
- * units in user space coordinates)
- * @y: the y position of the baseline (in Pango units
- * in user space coordinates)
+ * @hdc: a windows device context
+ * @matrix: (nullable): a `PangoMatrix`
+ * @font: the font in which to draw the string
+ * @glyphs: the glyph string to draw
+ * @x: the x position of the start of the string (in Pango
+ * units in user space coordinates)
+ * @y: the y position of the baseline (in Pango units
+ * in user space coordinates)
*
- * Renders a #PangoGlyphString onto a windows DC, possibly
+ * Renders a `PangoGlyphString` onto a windows DC, possibly
* transforming the layed-out coordinates through a transformation
- * matrix. Note that the transformation matrix for @font is not
+ * matrix.
+ *
+ * Note that the transformation matrix for @font is not
* changed, so to produce correct rendering results, the @font
- * must have been loaded using a #PangoContext with an identical
+ * must have been loaded using a `PangoContext` with an identical
* transformation matrix to that passed in to this function.
- **/
+ */
void
pango_win32_render_transformed (HDC hdc,
const PangoMatrix *matrix,
@@ -648,7 +649,7 @@ pango_win32_font_real_get_metrics_factor (PangoFont *font)
/**
* pango_win32_font_logfont:
- * @font: a #PangoFont which must be from the Win32 backend
+ * @font: a `PangoFont` which must be from the Win32 backend
*
* Determine the LOGFONTA struct for the specified font. Note that
* Pango internally uses LOGFONTW structs, so if converting the UTF-16
@@ -659,8 +660,8 @@ pango_win32_font_real_get_metrics_factor (PangoFont *font)
* to come across fonts with odd names.
*
* Return value: A newly allocated LOGFONTA struct. It must be
- * freed with g_free().
- **/
+ * freed with g_free().
+ */
LOGFONTA *
pango_win32_font_logfont (PangoFont *font)
{
@@ -684,12 +685,12 @@ pango_win32_font_logfont (PangoFont *font)
/**
* pango_win32_font_logfontw:
- * @font: a #PangoFont which must be from the Win32 backend
- *
+ * @font: a `PangoFont` which must be from the Win32 backend
+ *
* Determine the LOGFONTW struct for the specified font.
- *
+ *
* Return value: A newly allocated LOGFONTW struct. It must be
- * freed with g_free().
+ * freed with g_free().
*
* Since: 1.16
**/
@@ -710,21 +711,22 @@ pango_win32_font_logfontw (PangoFont *font)
/**
* pango_win32_font_select_font:
- * @font: a #PangoFont from the Win32 backend
+ * @font: a `PangoFont` from the Win32 backend
* @hdc: a windows device context
*
* Selects the font into the specified DC and changes the mapping mode
* and world transformation of the DC appropriately for the font.
+ *
* You may want to surround the use of this function with calls
- * to SaveDC() and RestoreDC(). Call pango_win32_font_done_font() when
+ * to SaveDC() and RestoreDC(). Call [method@Pango.Win32Font.done_font[ when
* you are done using the DC to release allocated resources.
*
- * See pango_win32_font_get_metrics_factor() for information about
+ * See [method@Pango.Win32Font.get_metrics_factor] for information about
* converting from the coordinate space used by this function
* into Pango units.
*
* Return value: %TRUE if the operation succeeded.
- **/
+ */
gboolean
pango_win32_font_select_font (PangoFont *font,
HDC hdc)
@@ -736,10 +738,10 @@ pango_win32_font_select_font (PangoFont *font,
/**
* pango_win32_font_done_font:
- * @font: a #PangoFont from the win32 backend
+ * @font: a `PangoFont` from the win32 backend
*
- * Releases any resources allocated by pango_win32_font_done_font()
- **/
+ * Releases any resources allocated by [method@Pango.Win32Font.select_font].
+ */
void
pango_win32_font_done_font (PangoFont *font)
{
@@ -750,15 +752,15 @@ pango_win32_font_done_font (PangoFont *font)
/**
* pango_win32_font_get_metrics_factor:
- * @font: a #PangoFont from the win32 backend
+ * @font: a `PangoFont` from the win32 backend
*
* Returns the scale factor from logical units in the coordinate
- * space used by pango_win32_font_select_font() to Pango units
- * in user space.
+ * space used by [method@Pango.Win32Font.select_font] to Pango
+ * units in user space.
*
* Return value: factor to multiply logical units by to get Pango
- * units.
- **/
+ * units.
+ */
double
pango_win32_font_get_metrics_factor (PangoFont *font)
{
@@ -893,8 +895,8 @@ pango_win32_font_get_coverage (PangoFont *font,
/**
* pango_win32_get_unknown_glyph:
- * @font: a #PangoFont
- * @wc: the Unicode character for which a glyph is needed.
+ * @font: a `PangoFont`
+ * @wc: the Unicode character for which a glyph is needed
*
* Returns the index of a glyph suitable for drawing @wc as an
* unknown character.
@@ -902,7 +904,7 @@ pango_win32_font_get_coverage (PangoFont *font,
* Use PANGO_GET_UNKNOWN_GLYPH() instead.
*
* Return value: a glyph index into @font
- **/
+ */
PangoGlyph
pango_win32_get_unknown_glyph (PangoFont *font,
gunichar wc)
@@ -912,14 +914,15 @@ pango_win32_get_unknown_glyph (PangoFont *font,
/**
* pango_win32_render_layout_line:
- * @hdc: DC to use for drawing
- * @line: a #PangoLayoutLine
- * @x: the x position of start of string (in pixels)
- * @y: the y position of baseline (in pixels)
+ * @hdc: DC to use for drawing
+ * @line: a `PangoLayoutLine`
+ * @x: the x position of start of string (in pixels)
+ * @y: the y position of baseline (in pixels)
*
- * Render a #PangoLayoutLine onto a device context. For underlining to
- * work property the text alignment of the DC should have TA_BASELINE
- * and TA_LEFT.
+ * Render a `PangoLayoutLine` onto a device context.
+ *
+ * For underlining to work property the text alignment
+ * of the DC should have TA_BASELINE and TA_LEFT.
*/
void
pango_win32_render_layout_line (HDC hdc,
@@ -1068,12 +1071,12 @@ pango_win32_render_layout_line (HDC hdc,
/**
* pango_win32_render_layout:
- * @hdc: HDC to use for drawing
- * @layout: a #PangoLayout
- * @x: the X position of the left of the layout (in pixels)
- * @y: the Y position of the top of the layout (in pixels)
+ * @hdc: HDC to use for drawing
+ * @layout: a `PangoLayout`
+ * @x: the X position of the left of the layout (in pixels)
+ * @y: the Y position of the top of the layout (in pixels)
*
- * Render a #PangoLayoutLine onto an X drawable
+ * Render a `PangoLayoutLine` onto an HDC.
*/
void
pango_win32_render_layout (HDC hdc,
@@ -1174,14 +1177,14 @@ pango_win32_get_item_properties (PangoItem *item,
/**
* pango_win32_font_get_glyph_index:
- * @font: a #PangoFont.
- * @wc: a Unicode character.
+ * @font: a `PangoFont`
+ * @wc: a Unicode character
*
* Obtains the index of the glyph for @wc in @font, or 0, if not
* covered.
*
* Return value: the glyph index for @wc.
- **/
+ */
gint
pango_win32_font_get_glyph_index (PangoFont *font,
gunichar wc)
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index ac4e6f39..1e1fff6f 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -108,15 +108,15 @@ _pango_xft_font_new (PangoXftFontMap *xftfontmap,
/**
* _pango_xft_font_get_mini_font:
- * @xfont: a #PangoXftFont
+ * @xfont: a `PangoXftFont`
*
* Gets the font used for drawing the digits in the
* missing-character hex squares
*
- * Return value: the #PangoFont used for the digits; this
+ * Return value: the `PangoFont` used for the digits; this
* value is associated with the main font and will be freed
* along with the main font.
- **/
+ */
PangoFont *
_pango_xft_font_get_mini_font (PangoXftFont *xfont)
{
@@ -470,13 +470,13 @@ pango_xft_font_real_shutdown (PangoFcFont *fcfont)
/**
* pango_xft_font_get_font: (skip)
- * @font: (nullable): a #PangoFont.
+ * @font: (nullable): a `PangoFont`
*
* Returns the `XftFont` of a font.
*
* Return value: (nullable): the `XftFont` associated to @font,
* or %NULL if @font is %NULL.
- **/
+ */
XftFont *
pango_xft_font_get_font (PangoFont *font)
{
@@ -488,7 +488,7 @@ pango_xft_font_get_font (PangoFont *font)
/**
* pango_xft_font_get_display: (skip)
- * @font: (type PangoXftFont): a #PangoFont.
+ * @font: (type PangoXftFont): a `PangoFont`
*
* Returns the X display of the `XftFont` of a font.
*
@@ -510,7 +510,7 @@ pango_xft_font_get_display (PangoFont *font)
/**
* pango_xft_font_get_unknown_glyph:
- * @font: (type PangoXftFont): a #PangoFont.
+ * @font: (type PangoXftFont): a `PangoFont`
* @wc: the Unicode character for which a glyph is needed.
*
* Returns the index of a glyph suitable for drawing @wc as an
@@ -531,7 +531,7 @@ pango_xft_font_get_unknown_glyph (PangoFont *font,
/**
* pango_xft_font_lock_face: (skip)
- * @font: (type PangoXftFont): a #PangoFont.
+ * @font: (type PangoXftFont): a `PangoFont`
*
* Gets the FreeType `FT_Face` associated with a font.
*
@@ -553,7 +553,7 @@ pango_xft_font_lock_face (PangoFont *font)
/**
* pango_xft_font_unlock_face: (skip)
- * @font: (type PangoXftFont): a #PangoFont.
+ * @font: (type PangoXftFont): a `PangoFont`
*
* Releases a font previously obtained with
* pango_xft_font_lock_face().
@@ -572,12 +572,14 @@ pango_xft_font_unlock_face (PangoFont *font)
/**
* pango_xft_font_get_glyph:
- * @font: (type PangoXftFont): a #PangoFont for the Xft backend
+ * @font: (type PangoXftFont): a `PangoFont` for the Xft backend
* @wc: Unicode codepoint 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_xft_font_has_char().
+ * for @font.
+ *
+ * If you only want to determine whether the font has
+ * the glyph, use pango_xft_font_has_char().
*
* Use pango_fc_font_get_glyph() instead.
*
@@ -597,7 +599,7 @@ pango_xft_font_get_glyph (PangoFont *font,
/**
* pango_xft_font_has_char:
- * @font: (type PangoXftFont): a #PangoFont for the Xft backend
+ * @font: (type PangoXftFont): a `PangoFont` for the Xft backend
* @wc: Unicode codepoint to look up
*
* Determines whether @font has a glyph for the codepoint @wc.
diff --git a/pango/pangoxft-fontmap.c b/pango/pangoxft-fontmap.c
index 82955165..1b5f5b5a 100644
--- a/pango/pangoxft-fontmap.c
+++ b/pango/pangoxft-fontmap.c
@@ -203,11 +203,11 @@ register_display (Display *display)
* @display: an X display
* @screen: the screen number of a screen within @display
*
- * Returns the #PangoXftFontMap for the given display and screen.
+ * Returns the `PangoXftFontMap` for the given display and screen.
* The fontmap is owned by Pango and will be valid until
* the display is closed.
*
- * Return value: (transfer none): a #PangoFontMap object, owned by Pango.
+ * Return value: (transfer none): a `PangoFontMap` object, owned by Pango.
*
* Since: 1.2
**/
@@ -348,10 +348,10 @@ _pango_xft_font_map_get_info (PangoFontMap *fontmap,
* @display: an X display.
* @screen: an X screen.
*
- * Retrieves a #PangoContext appropriate for rendering with
+ * Retrieves a `PangoContext` appropriate for rendering with
* Xft fonts on the given screen of the given display.
*
- * Return value: the new #PangoContext.
+ * Return value: the new `PangoContext`.
*
* Deprecated: 1.22: Use pango_xft_get_font_map() followed by
* pango_font_map_create_context() instead.
@@ -367,9 +367,9 @@ pango_xft_get_context (Display *display,
/**
* _pango_xft_font_map_get_renderer:
- * @fontmap: a #PangoXftFontMap
+ * @fontmap: a `PangoXftFontMap`
*
- * Gets the singleton #PangoXFTRenderer for this fontmap.
+ * Gets the singleton `PangoXFTRenderer` for this fontmap.
*
* Return value: the renderer.
**/
diff --git a/pango/pangoxft-render.c b/pango/pangoxft-render.c
index a2584f3c..9228a5c5 100644
--- a/pango/pangoxft-render.c
+++ b/pango/pangoxft-render.c
@@ -705,14 +705,14 @@ release_renderer (PangoRenderer *renderer)
/**
* pango_xft_render_layout:
- * @draw: an #XftDraw
- * @color: the foreground color in which to draw the layout
- * (may be overridden by color attributes)
- * @layout: a #PangoLayout
- * @x: the X position of the left of the layout (in Pango units)
- * @y: the Y position of the top of the layout (in Pango units)
+ * @draw: an XftDraw
+ * @color: the foreground color in which to draw the layout
+ * (may be overridden by color attributes)
+ * @layout: a `PangoLayout`
+ * @x: the X position of the left of the layout (in Pango units)
+ * @y: the Y position of the top of the layout (in Pango units)
*
- * Render a #PangoLayout onto a #XftDraw
+ * Render a `PangoLayout` onto a XftDraw
*
* Since: 1.8
*/
@@ -742,14 +742,14 @@ pango_xft_render_layout (XftDraw *draw,
/**
* pango_xft_render_layout_line:
- * @draw: an #XftDraw
- * @color: the foreground color in which to draw the layout line
- * (may be overridden by color attributes)
- * @line: a #PangoLayoutLine
- * @x: the x position of start of string (in Pango units)
- * @y: the y position of baseline (in Pango units)
+ * @draw: an XftDraw
+ * @color: the foreground color in which to draw the layout line
+ * (may be overridden by color attributes)
+ * @line: a `PangoLayoutLine`
+ * @x: the x position of start of string (in Pango units)
+ * @y: the y position of baseline (in Pango units)
*
- * Render a #PangoLayoutLine onto a #XftDraw
+ * Render a `PangoLayoutLine` onto a XftDraw
*
* Since: 1.8
*/
@@ -779,22 +779,23 @@ pango_xft_render_layout_line (XftDraw *draw,
/**
* pango_xft_render_transformed:
- * @draw: an #XftDraw
- * @color: the color in which to draw the glyphs
- * @font: the font in which to draw the string
- * @matrix: (nullable): a #PangoMatrix, or %NULL to use an identity
- * transformation
- * @glyphs: the glyph string to draw
- * @x: the x position of the start of the string (in Pango
- * units in user space coordinates)
- * @y: the y position of the baseline (in Pango units
- * in user space coordinates)
+ * @draw: an XftDraw
+ * @color: the color in which to draw the glyphs
+ * @font: the font in which to draw the string
+ * @matrix: (nullable): a `PangoMatrix`
+ * @glyphs: the glyph string to draw
+ * @x: the x position of the start of the string (in Pango
+ * units in user space coordinates)
+ * @y: the y position of the baseline (in Pango units
+ * in user space coordinates)
*
- * Renders a #PangoGlyphString onto a #XftDraw, possibly
+ * Renders a `PangoGlyphString` onto a XftDraw, possibly
* transforming the layed-out coordinates through a transformation
- * matrix. Note that the transformation matrix for @font is not
+ * matrix.
+ *
+ * Note that the transformation matrix for @font is not
* changed, so to produce correct rendering results, the @font
- * must have been loaded using a #PangoContext with an identical
+ * must have been loaded using a `PangoContext` with an identical
* transformation matrix to that passed in to this function.
*
* Since: 1.8
@@ -828,14 +829,14 @@ pango_xft_render_transformed (XftDraw *draw,
/**
* pango_xft_render:
- * @draw: the XftDraw object.
- * @color: the color in which to draw the string
- * @font: the font in which to draw the string
- * @glyphs: the glyph string to draw
- * @x: the x position of start of string (in pixels)
- * @y: the y position of baseline (in pixels)
+ * @draw: the XftDraw object.
+ * @color: the color in which to draw the string
+ * @font: the font in which to draw the string
+ * @glyphs: the glyph string to draw
+ * @x: the x position of start of string (in pixels)
+ * @y: the y position of baseline (in pixels)
*
- * Renders a #PangoGlyphString onto an XftDraw object wrapping an X drawable.
+ * Renders a `PangoGlyphString` onto an XftDraw object wrapping an X drawable.
*/
void
pango_xft_render (XftDraw *draw,
@@ -856,15 +857,15 @@ pango_xft_render (XftDraw *draw,
/**
* pango_xft_picture_render:
- * @display: an X display
- * @src_picture: the source picture to draw the string with
+ * @display: an X display
+ * @src_picture: the source picture to draw the string with
* @dest_picture: the destination picture to draw the string onto
- * @font: the font in which to draw the string
- * @glyphs: the glyph string to draw
- * @x: the x position of start of string (in pixels)
- * @y: the y position of baseline (in pixels)
+ * @font: the font in which to draw the string
+ * @glyphs: the glyph string to draw
+ * @x: the x position of start of string (in pixels)
+ * @y: the y position of baseline (in pixels)
*
- * Renders a #PangoGlyphString onto an Xrender Picture object.
+ * Renders a `PangoGlyphString` onto an Xrender Picture object.
*/
void
pango_xft_picture_render (Display *display,
@@ -900,17 +901,18 @@ pango_xft_picture_render (Display *display,
/**
* pango_xft_renderer_new:
* @display: an X display
- * @screen: the index of the screen for @display to which rendering will be done
+ * @screen: the index of the screen for @display to which rendering will be done
+ *
+ * Create a new `PangoXftRenderer` to allow rendering Pango objects
+ * with the Xft library.
*
- * Create a new #PangoXftRenderer to allow rendering Pango objects
- * with the Xft library. You must call pango_xft_renderer_set_draw() before
+ * You must call pango_xft_renderer_set_draw() before
* using the renderer.
*
- * Return value: the newly created #PangoXftRenderer, which should
- * be freed with g_object_unref().
+ * Return value: the newly created `PangoXftRenderer`
*
* Since: 1.8
- **/
+ */
PangoRenderer *
pango_xft_renderer_new (Display *display,
int screen)
@@ -927,14 +929,14 @@ pango_xft_renderer_new (Display *display,
/**
* pango_xft_renderer_set_draw:
- * @xftrenderer: a #PangoXftRenderer
- * @draw: a #XftDraw
+ * @xftrenderer: a `PangoXftRenderer`
+ * @draw: a XftDraw
*
- * Sets the #XftDraw object that the renderer is drawing to.
+ * Sets the XftDraw object that the renderer is drawing to.
* The renderer must not be currently active.
*
* Since: 1.8
- **/
+ */
void
pango_xft_renderer_set_draw (PangoXftRenderer *xftrenderer,
XftDraw *draw)
@@ -946,13 +948,13 @@ pango_xft_renderer_set_draw (PangoXftRenderer *xftrenderer,
/**
* pango_xft_renderer_set_default_color:
- * @xftrenderer: a #XftRenderer
+ * @xftrenderer: a XftRenderer
* @default_color: the default foreground color
*
- * Sets the default foreground color for a #XftRenderer.
+ * Sets the default foreground color for a XftRenderer.
*
* Since: 1.8
- **/
+ */
void
pango_xft_renderer_set_default_color (PangoXftRenderer *xftrenderer,
PangoColor *default_color)
diff --git a/pango/pangoxft-render.h b/pango/pangoxft-render.h
index 77684728..bf4b33e9 100644
--- a/pango/pangoxft-render.h
+++ b/pango/pangoxft-render.h
@@ -57,7 +57,7 @@ typedef struct _PangoXftRendererPrivate PangoXftRendererPrivate;
/**
* PangoXftRenderer:
*
- * #PangoXftRenderer is a subclass of #PangoRenderer used for rendering
+ * `PangoXftRenderer` is a subclass of `PangoRenderer` used for rendering
* with Pango's Xft backend. It can be used directly, or it can be
* further subclassed to modify exactly how drawing of individual
* elements occurs.
@@ -84,7 +84,7 @@ struct _PangoXftRenderer
* the current foreground color and other foreground
* attributes
*
- * The class structure for #PangoXftRenderer
+ * The class structure for `PangoXftRenderer`
*
* Since: 1.8
*/
diff --git a/pango/pangoxft.h b/pango/pangoxft.h
index 0852c202..105de5c2 100644
--- a/pango/pangoxft.h
+++ b/pango/pangoxft.h
@@ -49,9 +49,9 @@ G_BEGIN_DECLS
/**
* PangoXftFontMap:
*
- * #PangoXftFontMap is an implementation of #PangoFcFontMap suitable for
+ * `PangoXftFontMap` is an implementation of `PangoFcFontMap` suitable for
* the Xft library as the renderer. It is used in to create fonts of
- * type #PangoXftFont.
+ * type `PangoXftFont`.
*/
/* This is a hack needed because PangoXft hijacks the Pango namespace
@@ -73,8 +73,8 @@ typedef struct _PangoXftFontMap PangoXftFontMap;
/**
* PangoXftFont:
*
- * #PangoXftFont is an implementation of #PangoFcFont using the Xft
- * library for rendering. It is used in conjunction with #PangoXftFontMap.
+ * `PangoXftFont` is an implementation of `PangoFcFont` using the Xft
+ * library for rendering. It is used in conjunction with `PangoXftFontMap`.
*/
typedef struct _PangoXftFont PangoXftFont;
diff --git a/pango/reorder-items.c b/pango/reorder-items.c
index d00fee4c..e5ceeb6f 100644
--- a/pango/reorder-items.c
+++ b/pango/reorder-items.c
@@ -39,12 +39,12 @@ static GList *reorder_items_recurse (GList *items, int n_items);
* The visual order is determined from the associated directional
* levels of the items. The original list is unmodified.
*
- * Returns: (transfer full) (element-type Pango.Item): a #GList
- * of #PangoItem structures in visual order.
- *
* (Please open a bug if you use this function.
* It is not a particularly convenient interface, and the code
* is duplicated elsewhere in Pango for that reason.)
+ *
+ * Returns: (transfer full) (element-type Pango.Item): a `GList`
+ * of `PangoItem` structures in visual order.
*/
GList *
pango_reorder_items (GList *logical_items)
diff --git a/pango/shape.c b/pango/shape.c
index 1b2986c4..04407732 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -63,7 +63,7 @@ pango_shape (const gchar *text,
* pango_shape_full:
* @item_text: valid UTF-8 text to shape.
* @item_length: the length (in bytes) of @item_text. -1 means nul-terminated text.
- * @paragraph_text: (allow-none): text of the paragraph (see details). May be %NULL.
+ * @paragraph_text: (nullable): text of the paragraph (see details). May be %NULL.
* @paragraph_length: the length (in bytes) of @paragraph_text. -1 means nul-terminated text.
* @analysis: `PangoAnalysis` structure from [func@itemize].
* @glyphs: glyph string in which to store results.
@@ -156,7 +156,7 @@ fallback_shape (const char *text,
* @item_text: valid UTF-8 text to shape
* @item_length: the length (in bytes) of @item_text.
* -1 means nul-terminated text.
- * @paragraph_text: (allow-none): text of the paragraph (see details).
+ * @paragraph_text: (nullable): text of the paragraph (see details).
* May be %NULL.
* @paragraph_length: the length (in bytes) of @paragraph_text.
* -1 means nul-terminated text.