diff options
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. |