From 4cfc401b7c4fd45d980ffd5f9e8b7bf3e4c26702 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 22 Jun 2022 20:15:00 -0400 Subject: Documentation improvements --- NEWS | 6 +++++ docs/meson.build | 2 +- docs/migrating.md | 42 ++++++++++++++++++----------------- docs/pango.toml.in | 14 +++++++----- docs/urlmap.js | 2 -- pango/pango-attr.c | 13 +++++++++++ pango/pango-attr.h | 50 +++++++++++++++++++++--------------------- pango/pango-attributes.h | 41 ++++++++++++++++++++-------------- pango/pango-context.c | 4 ++-- pango/pango-font-description.h | 24 ++++++++++---------- pango/pango-font-face.c | 17 +++++++++----- pango/pango-font-family.c | 6 ++--- pango/pango-font.c | 2 +- pango/pango-fontmap.c | 23 +++++++++---------- pango/pango-glyph.h | 4 ++-- pango/pango-layout.c | 17 +++++++------- pango/pango-line-breaker.c | 12 +++++----- pango/pango-lines.c | 14 ++++++------ pango/pango-types.h | 1 - pango/pangofc-fontmap.c | 4 ++-- 20 files changed, 166 insertions(+), 132 deletions(-) diff --git a/NEWS b/NEWS index 2e554c9f..38a512a9 100644 --- a/NEWS +++ b/NEWS @@ -110,6 +110,12 @@ Other API changes - Most structs have been made private +- Support for trimming the leading of the first and last line in + a layout + +- Face-ids have been introduced to guarantee lossless + font - description - font roundtrips + - Many smaller API cleanups and reductions diff --git a/docs/meson.build b/docs/meson.build index ee58c26a..52ab55c3 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -72,7 +72,7 @@ pango_toml = configure_file(input: 'pango.toml.in', custom_target('pango-doc', input: pango_gir[0], - output: 'Pango', + output: 'Pango2', command: [ gidocgen, 'generate', diff --git a/docs/migrating.md b/docs/migrating.md index 222adf7e..c7b897d0 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -3,16 +3,16 @@ Title: Migrating from Pango 1.x to Pango 2 --- Pango 2 is a major new version of Pango that breaks both API and ABI -compared to Pango 1.x. Thankfully, most of the changes are not hard -to adapt to. +compared to Pango 1.x. Therefore, some porting is required when switching +an application from Pango 1 to Pango 2. Thankfully, most of the changes +are not hard to adapt to. ## Preparation in Pango 1.x -The steps outlined in the following sections assume that your -application is working with a recent version of Pango 1.x, such -as Pango 1.50. If you are using an older version of Pango, you -should first get your application to build and work with -Pango 1.50. +The steps outlined in the following sections assume that your application +is working with a recent version of Pango 1.x, such as Pango 1.50. If you +are using an older version of Pango, you should first get your application +to build and work with Pango 1.50. ### Do not use deprecated symbols @@ -51,11 +51,11 @@ the `pangocairo.h` header, and use the APIs that are declared in it. There is still a `pangocairo2.pc` file, if you want to be explicit in your build configuration about requiring cairo support. If you want to handle the possible absence of cairo support at runtime, you can check the -`PANGO_CAIRO_RENDERING` macro before including `pangocairo.h`. +[const@Pango.RENDERING_CAIRO] macro before including `pangocairo.h`. ### PangoFontMap changes -The `PangoFontMap` class has seen some significant changes. It is now possible +The [class@Pango.FontMap] class has seen some significant changes. It is now possible to instantiate a `PangoFontMap`, and populate it manually with `PangoFontFamily` and `PangoFontFace` objects. If you simply want to obtain the default fontmap that is populated with the native font enumeration APIs, use @@ -70,7 +70,7 @@ APIs to obtain a suitable fontmap, or set the resolution. ### Font-related API changes -Some APIs have moved between [class@Pango.Font], [class@Pango.FontFace] +Some APIs have been moved between [class@Pango.Font], [class@Pango.FontFace] and [class@Pango.FontFamily] or renamed. | Old API | New API | @@ -101,7 +101,7 @@ and have getters. APIs for creating items have been dropped. ### PangoLayout changes Most APIs that provide information about the formatted output have been -moved from `PangoLayout` to the new objects [class@Pango.Lines] and +moved from [class@Pango.Layout] to the new objects [class@Pango.Lines] and [struct@Pango.LineIter]. To obtain these from a `PangoLayout`, use [method@Pango.Layout.get_lines] and [method@Pango.Layout.get_iter]. @@ -134,19 +134,21 @@ The `PangoGlyphItem/PangoLayoutRun` struct has been replaced by a new ### PangoAttribute changes -`PangoAttribute` is no longer defined with different structs, but is -an opaque type with getters for the different types of value. To set -the range of an attribute use [method@Pango.Attribute.set_range]. To -define your own attribute types, use [func@Pango.AttrType.register]. +[struct@Pango.Attribute] is no longer defined with different structs, +but is an opaque type with getters for the different types of value. +To set the range of an attribute use [method@Pango.Attribute.set_range]. +To define your own attribute types, use [func@Pango.AttrType.register]. Some of the existing attribute types have seen changes as well. All the -color-related attributes now take a [struct@PangoColor] argument in their -constructor. The line-related attributes have been reorganized. There is now -a [enum@Pango.LineStyle] enumeration that can be applied to underlines, -overlines and strikethroughs, and a separate [enum@Pango.UnderlinePosition] -enumeration. Alpha attributes have been removed, since [struct@Pango.Color] +color-related attributes now take a [struct@Pango.Color] argument in their +constructor. Alpha attributes have been removed, since [struct@Pango.Color] now contains an alpha field. +The line-related attributes have been reorganized. There is now a +[enum@Pango.LineStyle] enumeration that can be applied to underlines, +overlines and strikethroughs, and a separate [enum@Pango.UnderlinePosition] +enumeration. + ### Markup changes The attributes 'alpha', 'fgalpha', 'background_alpha' and 'bgalpha' have diff --git a/docs/pango.toml.in b/docs/pango.toml.in index b1cf26ea..7503e1ec 100644 --- a/docs/pango.toml.in +++ b/docs/pango.toml.in @@ -1,23 +1,22 @@ [library] namespace = "Pango" version = "@PANGO_VERSION@" -browse_url = "https://gitlab.gnome.org/GNOME/pango/" +browse_url = "https://gitlab.gnome.org/GNOME/pango2/" repository_url = "https://gitlab.gnome.org/GNOME/pango.git" website_url = "https://www.pango.org" authors = "Owen Taylor, Behdad Esfahbod, Matthias Clasen" logo_url = "pango-name.png" license = "LGPL-2.1-or-later" description = "Internationalized text layout and rendering" -dependencies = [ "GObject-2.0", "HarfBuzz-0.0", "PangoCairo-1.0", - "PangoFc-1.0", "PangoFT2-1.0", "PangoOT-1.0", - "PangoXft-1.0" ] +dependencies = [ "GObject-2.0", "HarfBuzz-0.0", "Fribidi-0.0", + "Cairo-0.0", "Gio-2.0", ] devhelp = true search_index = true [dependencies."GObject-2.0"] name = "GObject" description = "The base type system library" - docs_url = "https://developer.gnome.org/gobject/stable" + docs_url = "https://docs.gtk.org/gobject/" [dependencies."HarfBuzz-0.0"] name = "HarfBuzz" @@ -34,6 +33,11 @@ search_index = true description = "A 2D graphics library" docs_url = "https://www.cairographics.org/documentation/" + [dependencies."Gio-2.0"] + name = "GIO" + description = "Useful classes for general purpose I/O, networking, IPC, etc." + docs_url = "https://docs.gtk.org/gio/" + [theme] name = "basic" show_index_summary = true diff --git a/docs/urlmap.js b/docs/urlmap.js index 5d60b064..deae96b9 100644 --- a/docs/urlmap.js +++ b/docs/urlmap.js @@ -6,6 +6,4 @@ baseURLs = [ [ 'GLib', 'https://docs.gtk.org/glib/' ], [ 'GObject', 'https://docs.gtk.org/gobject/' ], [ 'Gio', 'https://docs.gtk.org/gio/' ], - [ 'Pango', 'https://docs.gtk.org/Pango/' ], - [ 'PangoCairo', 'https://docs.gtk.org/PangoCairo/' ], ] diff --git a/pango/pango-attr.c b/pango/pango-attr.c index 8f6f5980..4f4d8fdf 100644 --- a/pango/pango-attr.c +++ b/pango/pango-attr.c @@ -26,6 +26,19 @@ #include "pango-attributes-private.h" #include "pango-impl-utils.h" +/** + * PangoAttribute: + * + * A `PangoAttribute` structure associates a named attribute with + * a certain range of a text. + * + * Attributes can have basic types, such as int, float, boolean + * `PangoColor`, `PangoFontDescription or `PangoLanguage`. It is + * also possible to define new, custom attributes. + * + * By default, an attribute will have an all-inclusive range of + * `[0,G_MAXUINT]`. + */ /* {{{ Generic attribute code */ diff --git a/pango/pango-attr.h b/pango/pango-attr.h index abb57130..0617c4cf 100644 --- a/pango/pango-attr.h +++ b/pango/pango-attr.h @@ -30,20 +30,20 @@ typedef struct _PangoAttribute PangoAttribute; /** * PangoAttrValueType: - * @PANGO_ATTR_VALUE_STRING: a string - * @PANGO_ATTR_VALUE_INT: an integer - * @PANGO_ATTR_VALUE_BOOLEAN: a boolean - * @PANGO_ATTR_VALUE_FLOAT: a floating point number - * @PANGO_ATTR_VALUE_COLOR: a `PangoColor` - * @PANGO_ATTR_VALUE_LANGUAGE: a `PangoLanguage` - * @PANGO_ATTR_VALUE_FONT_DESC: a `PangoFontDescription` - * @PANGO_ATTR_VALUE_POINTER: a generic pointer - * - * The `PangoAttrValueType` enumeration describes the various types - * of values that a `PangoAttribute` can contain. - * - * The `PangoAttrValueType` of a `PangoAttribute` is part of its type, - * and can be obtained with `PANGO_ATTR_VALUE_TYPE()`. + * @PANGO_ATTR_VALUE_STRING: A string + * @PANGO_ATTR_VALUE_INT: An integer + * @PANGO_ATTR_VALUE_BOOLEAN: A boolean + * @PANGO_ATTR_VALUE_FLOAT: A floating point number + * @PANGO_ATTR_VALUE_COLOR: A `PangoColor` + * @PANGO_ATTR_VALUE_LANGUAGE: A `PangoLanguage` + * @PANGO_ATTR_VALUE_FONT_DESC: A `PangoFontDescription` + * @PANGO_ATTR_VALUE_POINTER: A generic pointer + * + * `PangoAttrValueType` enumerates the types of values + * that a `PangoAttribute` can contain. + * + * The `PangoAttrValueType` of a `PangoAttribute` is part + * of its type, and can be obtained with `PANGO_ATTR_VALUE_TYPE()`. */ typedef enum { @@ -59,14 +59,14 @@ typedef enum /** * PangoAttrAffects: - * @PANGO_ATTR_AFFECTS_NONE: the attribute does not affect rendering - * @PANGO_ATTR_AFFECTS_ITEMIZATION: the attribute affecs itemization - * @PANGO_ATTR_AFFECTS_BREAKING: the attribute affects `PangoLogAttr` determination - * @PANGO_ATTR_AFFECTS_SHAPING: the attribute affects shaping - * @PANGO_ATTR_AFFECTS_RENDERING: the attribute affects rendering + * @PANGO_ATTR_AFFECTS_NONE: The attribute does not affect rendering + * @PANGO_ATTR_AFFECTS_ITEMIZATION: The attribute affecs itemization + * @PANGO_ATTR_AFFECTS_BREAKING: The attribute affects `PangoLogAttr` determination + * @PANGO_ATTR_AFFECTS_SHAPING: The attribute affects shaping + * @PANGO_ATTR_AFFECTS_RENDERING: The attribute affects rendering * - * Flags to indicate what part of Pangos processing pipeline is - * affected by an attribute. + * A `PangoAttrAffects` value indicates what part of Pango's processing + * pipeline is affected by an attribute. * * Marking an attribute with `PANGO_ATTR_AFFECTS_ITEMIZATION` ensures * that the attribute values are constant across items. @@ -82,11 +82,11 @@ typedef enum /** * PangoAttrMerge: - * @PANGO_ATTR_MERGE_OVERRIDES: only the attribute with the narrowest range is used - * @PANGO_ATTR_MERGE_ACCUMULATES: all attributes with overlapping range are kept + * @PANGO_ATTR_MERGE_OVERRIDES: Only the attribute with the narrowest range is used + * @PANGO_ATTR_MERGE_ACCUMULATES: All attributes with overlapping range are kept * - * Options to indicate how overlapping attribute values should be - * reconciled to determine the effective attribute value. + * A `PangoAttrMerge` value indicates how overlapping attribute values + * should be reconciled to determine the effective attribute value. * * These options influence the @extra_attrs returned by * [method@Pango.AttrIterator.get_font]. diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h index ffb3d07f..e97db134 100644 --- a/pango/pango-attributes.h +++ b/pango/pango-attributes.h @@ -69,10 +69,11 @@ G_BEGIN_DECLS * @PANGO_ATTR_PARAGRAPH: mark the range of the attribute as a single paragraph * @PANGO_ATTR_BASELINE_SHIFT: baseline displacement * @PANGO_ATTR_FONT_SCALE: font-relative size change - * @PANGO_ATTR_LINE_SPACING: extra space to add to the leading from the - * font metrics (if not overridden by line height attribute) + * @PANGO_ATTR_LINE_SPACING: space to add to the leading from the + * font metrics (if not overridden by a line height attribute) + * @PANGO_ATTR_SHAPE: override glyph shapes (requires renderer support) * - * The `PangoAttrType` enumeration contains predefined types for attributes. + * `PangoAttrType` contains predefined attribute types. * * Along with the predefined values, it is possible to allocate additional * values for custom attributes using [func@AttrType.register]. The predefined @@ -148,15 +149,14 @@ PangoAttribute * pango_attr_font_desc_new (const PangoFont /** * PangoLineStyle: - * @PANGO_LINE_STYLE_NONE: no line should be drawn - * @PANGO_LINE_STYLE_SOLID: a single line should be drawn - * @PANGO_LINE_STYLE_DOUBLE: a double line should be drawn - * @PANGO_LINE_STYLE_DASHED: an dashed line should be drawn - * @PANGO_LINE_STYLE_DOTTED: an dotted line should be drawn - * @PANGO_LINE_STYLE_WAVY: an wavy line should be drawn + * @PANGO_LINE_STYLE_NONE: No visible line + * @PANGO_LINE_STYLE_SOLID: A single line + * @PANGO_LINE_STYLE_DOUBLE: A double line + * @PANGO_LINE_STYLE_DASHED: A dashed line + * @PANGO_LINE_STYLE_DOTTED: A dotted line + * @PANGO_LINE_STYLE_WAVY: A wavy line * - * The `PangoLineStyle` enumeration is used to specify how - * lines should be drawn. + * `PangoLineStyle specifies how lines should be drawn. */ typedef enum { PANGO_LINE_STYLE_NONE, @@ -173,6 +173,13 @@ PangoAttribute * pango_attr_underline_new (PangoLineStyle PANGO_AVAILABLE_IN_ALL PangoAttribute * pango_attr_underline_color_new (PangoColor *color); +/** + * PangoUnderlinePosition: + * @PANGO_UNDERLINE_POSITION_NORMAL: As specified by font metrics + * @PANGO_UNDERLINE_POSITION_UNDER: Below the ink extents of the run + * + * `PangoUnderlinePosition` specifies where underlines should be drawn. + */ typedef enum { PANGO_UNDERLINE_POSITION_NORMAL, PANGO_UNDERLINE_POSITION_UNDER @@ -196,7 +203,7 @@ PangoAttribute * pango_attr_rise_new (int * @PANGO_BASELINE_SHIFT_SUBSCRIPT: Shift the baseline to the subscript position, * relative to the previous run * - * An enumeration that affects baseline shifts between runs. + * `PangoBaselineShift` influences how baselines are changed between runs. */ typedef enum { PANGO_BASELINE_SHIFT_NONE, @@ -214,8 +221,7 @@ PangoAttribute * pango_attr_baseline_shift_new (int * @PANGO_FONT_SCALE_SUBSCRIPT: Change the font to a size suitable for subscripts * @PANGO_FONT_SCALE_SMALL_CAPS: Change the font to a size suitable for Small Caps * - * An enumeration that affects font sizes for superscript - * and subscript positioning and for (emulated) Small Caps. + * `PangoFontScale` influences the font size of a run. */ typedef enum { PANGO_FONT_SCALE_NONE, @@ -262,7 +268,7 @@ PangoAttribute * pango_attr_overline_color_new (PangoColor * @PANGO_SHOW_IGNORABLES: Render default-ignorable Unicode * characters visibly * - * These flags affect how Pango treats characters that are normally + * `PangoShowFlags` affect how Pango treats characters that are normally * not visible in the output. */ typedef enum { @@ -281,7 +287,7 @@ PangoAttribute * pango_attr_line_height_new_absolute (int PANGO_AVAILABLE_IN_ALL PangoAttribute * pango_attr_line_spacing_new (int spacing); -/* +/** * PangoTextTransform: * @PANGO_TEXT_TRANSFORM_NONE: Leave text unchanged * @PANGO_TEXT_TRANSFORM_LOWERCASE: Display letters and numbers as lowercase @@ -289,7 +295,8 @@ PangoAttribute * pango_attr_line_spacing_new (int * @PANGO_TEXT_TRANSFORM_CAPITALIZE: Display the first character of a word * in titlecase * - * An enumeration that affects how Pango treats characters during shaping. + * `PangoTextTransform` determines if Pango changes the case of characters + * during shaping. */ typedef enum { PANGO_TEXT_TRANSFORM_NONE, diff --git a/pango/pango-context.c b/pango/pango-context.c index 6503e857..2c926690 100644 --- a/pango/pango-context.c +++ b/pango/pango-context.c @@ -234,7 +234,7 @@ pango_context_class_init (PangoContextClass *klass) /** * PangoContext:font-description: (attributes org.gtk.Property.get=pango_context_get_font_description org.gtk.Property.set=pango_context_set_font_description) * - * The default font descriptoin for the context. + * The default font description for the context. */ properties[PROP_FONT_DESCRIPTION] = g_param_spec_boxed ("font-description", NULL, NULL, PANGO_TYPE_FONT_DESCRIPTION, @@ -303,7 +303,7 @@ pango_context_class_init (PangoContextClass *klass) * * The transformation is needed in cases where the font rendering applies * hinting that depends on knowing the position of text with respect to - * the pixel grid. If your font rendering does not + * the pixel grid. */ properties[PROP_MATRIX] = g_param_spec_boxed ("matrix", NULL, NULL, PANGO_TYPE_MATRIX, diff --git a/pango/pango-font-description.h b/pango/pango-font-description.h index 7cad766c..6643131c 100644 --- a/pango/pango-font-description.h +++ b/pango/pango-font-description.h @@ -96,7 +96,7 @@ typedef enum { * @PANGO_WEIGHT_HEAVY: the heavy weight (= 900) * @PANGO_WEIGHT_ULTRAHEAVY: the ultraheavy weight (= 1000) * - * An enumeration specifying the weight (boldness) of a font. + * A `PangoWeight` specifes the weight (boldness) of a font. * * Weight is specified as a numeric value ranging from 100 to 1000. * This enumeration simply provides some common, predefined values. @@ -118,18 +118,18 @@ typedef enum { /** * PangoStretch: - * @PANGO_STRETCH_ULTRA_CONDENSED: ultra condensed width - * @PANGO_STRETCH_EXTRA_CONDENSED: extra condensed width - * @PANGO_STRETCH_CONDENSED: condensed width - * @PANGO_STRETCH_SEMI_CONDENSED: semi condensed width - * @PANGO_STRETCH_NORMAL: the normal width - * @PANGO_STRETCH_SEMI_EXPANDED: semi expanded width - * @PANGO_STRETCH_EXPANDED: expanded width - * @PANGO_STRETCH_EXTRA_EXPANDED: extra expanded width - * @PANGO_STRETCH_ULTRA_EXPANDED: ultra expanded width + * @PANGO_STRETCH_ULTRA_CONDENSED: ultra-condensed width (= 500) + * @PANGO_STRETCH_EXTRA_CONDENSED: extra-condensed width (= 625) + * @PANGO_STRETCH_CONDENSED: condensed width (= 750) + * @PANGO_STRETCH_SEMI_CONDENSED: semi-condensed width (= 875) + * @PANGO_STRETCH_NORMAL: the normal width (= 1000) + * @PANGO_STRETCH_SEMI_EXPANDED: semi-expanded width (= 1125) + * @PANGO_STRETCH_EXPANDED: expanded width (= 1250) + * @PANGO_STRETCH_EXTRA_EXPANDED: extra-expanded width (= 1500) + * @PANGO_STRETCH_ULTRA_EXPANDED: ultra-expanded width (= 2000) * - * An enumeration specifying the width of the font relative to other designs - * within a family. + * A `PangoStretch` specifes the width of the font relative + * to other designs within a family. * * Stretch is specified as a numeric value ranging from 500 to 2000. * This enumeration simply provides some common, predefined values. diff --git a/pango/pango-font-face.c b/pango/pango-font-face.c index 73c41997..36232694 100644 --- a/pango/pango-font-face.c +++ b/pango/pango-font-face.c @@ -223,7 +223,7 @@ pango_font_face_class_init (PangoFontFaceClass *class) /** * PangoFontFace:family: (attributes org.gtk.Property.get=pango_font_face_get_family) * - * The `PangoFontFamily` that @face belongs to. + * The `PangoFontFamily` that the face belongs to. */ properties[PROP_FAMILY] = g_param_spec_object ("family", NULL, NULL, @@ -412,7 +412,7 @@ pango_font_face_get_name (PangoFontFace *face) * pango_font_face_get_family: * @face: a `PangoFontFace` * - * Gets the `PangoFontFamily` that @face belongs to. + * Gets the `PangoFontFamily` that the face belongs to. * * Returns: (transfer none): the `PangoFontFamily` */ @@ -428,6 +428,8 @@ pango_font_face_get_family (PangoFontFace *face) * pango_font_face_is_monospace: * @face: a `PangoFontFace` * + * Returns whether this font face is monospace. + * * A monospace font is a font designed for text display where the the * characters form a regular grid. * @@ -457,6 +459,8 @@ pango_font_face_is_monospace (PangoFontFace *face) * pango_font_face_is_variable: * @face: a `PangoFontFace` * + * Returns whether this font face is variable. + * * A variable font is a font which has axes that can be modified * to produce variations. * @@ -478,7 +482,8 @@ pango_font_face_is_variable (PangoFontFace *face) * @face: a `PangoFontFace` * @language: a `PangoLanguage` * - * Returns whether @face has all the glyphs necessary to write @language. + * Returns whether the face has all the glyphs necessary to + * support this language. * * Returns: `TRUE` if @face supports @language */ @@ -495,11 +500,11 @@ pango_font_face_supports_language (PangoFontFace *face, * pango_font_face_get_languages: * @face: a `PangoFontFace` * - * Returns the languages that are supported by @face. + * Returns the languages that are supported by the face. * * If the font backend does not provide this information, - * %NULL is returned. For the fontconfig backend, this - * corresponds to the FC_LANG member of the FcPattern. + * `NULL` is returned. For the fontconfig backend, this + * corresponds to the `FC_LANG` member of the `FcPattern`. * * The returned array is only valid as long as the face * and its fontmap are valid. diff --git a/pango/pango-font-family.c b/pango/pango-font-family.c index 789992d8..5c0de724 100644 --- a/pango/pango-font-family.c +++ b/pango/pango-font-family.c @@ -242,14 +242,14 @@ pango_font_family_get_name (PangoFontFamily *family) /** * pango_font_family_get_face: * @family: a `PangoFontFamily` - * @name: (nullable): the name of a face. If the name is %NULL, + * @name: (nullable): the name of a face. If the name is `NULL`, * the family's default face (fontconfig calls it "Regular") * will be returned. * - * Gets the `PangoFontFace` of @family with the given name. + * Gets the `PangoFontFace` of the 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. */ PangoFontFace * pango_font_family_get_face (PangoFontFamily *family, diff --git a/pango/pango-font.c b/pango/pango-font.c index 9552b786..d8f081ad 100644 --- a/pango/pango-font.c +++ b/pango/pango-font.c @@ -386,7 +386,7 @@ pango_font_get_metrics (PangoFont *font, * pango_font_get_face: * @font: a `PangoFont` * - * Gets the `PangoFontFace` to which @font belongs. + * Gets the `PangoFontFace` to which the font belongs. * * Returns: (transfer none): the `PangoFontFace` */ diff --git a/pango/pango-fontmap.c b/pango/pango-fontmap.c index 5f42be64..b76a0ded 100644 --- a/pango/pango-fontmap.c +++ b/pango/pango-fontmap.c @@ -799,10 +799,11 @@ pango_font_map_changed (PangoFontMap *self) * @context: the `PangoContext` the font will be used with * @desc: a `PangoFontDescription` describing the font to load * - * Load the font in the fontmap that is the closest match for @desc. + * Load the font in the fontmap that is the closest match for + * a font description. * - * Returns: (transfer full) (nullable): the `PangoFont` that was found, - * or %NULL if no font matched + * Returns: (transfer full) (nullable): the `PangoFont` that + * was found */ PangoFont * pango_font_map_load_font (PangoFontMap *self, @@ -825,10 +826,10 @@ pango_font_map_load_font (PangoFontMap *self, * or `NULL` to use the language of @context * * Load a set of fonts in the fontmap that can be used to render - * a font matching @desc. + * a font matching a font description. * * Returns: (transfer full) (nullable): the `PangoFontset` containing - * the fonts that were found, or %NULL if no font matched + * the fonts that were found */ PangoFontset * pango_font_map_load_fontset (PangoFontMap *self, @@ -847,7 +848,7 @@ pango_font_map_load_fontset (PangoFontMap *self, * pango_font_map_get_serial: * @self: a `PangoFontMap` * - * Returns the current serial number of @self. + * Returns the current serial number of the fontmap. * * The serial number is initialized to an small number larger than zero * when a new fontmap is created and is increased whenever the fontmap @@ -909,7 +910,7 @@ pango_font_map_new (void) * @self: a `PangoFontMap` * @face: (transfer full): a `PangoFontFace` * - * Adds @face to the `PangoFontMap`. + * Adds a face to the fontmap. * * This is most useful for creating transformed faces or aliases. * See [method@Pango.HbFace.new_synthetic] and [method@Pango.HbFace.new_instance]. @@ -953,7 +954,7 @@ pango_font_map_add_face (PangoFontMap *self, * @self: a `PangoFontMap` * @face: a `PangoFontFace` that belongs to @map * - * Removes @face from the `PangoFontMap`. + * Removes @face from the fontmap. * * @face must have been added with [method@Pango.FontMap.add_face]. */ @@ -1009,7 +1010,7 @@ pango_font_map_add_file (PangoFontMap *self, * @self: a `PangoFontMap` * @family: (transfer full): a `PangoFontFamily` * - * Adds @family to @self. + * Adds a family to the `PangoFontMap`. * * The fontmap must not contain a family with the * same name as @family yet. @@ -1061,7 +1062,7 @@ pango_font_map_add_family (PangoFontMap *self, * @self: a `PangoFontMap` * @family: a `PangoFontFamily` that belongs to @self * - * Removes @family from a `PangoFontMap` + * Removes a family from the fontmap. */ void pango_font_map_remove_family (PangoFontMap *self, @@ -1121,7 +1122,7 @@ pango_font_map_set_fallback (PangoFontMap *self, * pango_font_map_get_fallback: * @self: a `PangoFontMap` * - * Returns the fallback fontmap of @self + * Returns the fallback fontmap of the fontmap. * * See [method@Pango.FontMap.set_fallback]. * diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h index 94938b84..8dafd623 100644 --- a/pango/pango-glyph.h +++ b/pango/pango-glyph.h @@ -221,9 +221,9 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC(PangoGlyphString, pango_glyph_string_free) * @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 * - * Flags influencing the shaping process. + * `PangoShapeFlags` influence the shaping process. * - * `PangoShapeFlags` can be passed to [func@Pango.shape]. + * These flags can be passed to [func@Pango.shape]. */ typedef enum { PANGO_SHAPE_NONE = 0, diff --git a/pango/pango-layout.c b/pango/pango-layout.c index 42674881..5a2f50aa 100644 --- a/pango/pango-layout.c +++ b/pango/pango-layout.c @@ -453,7 +453,7 @@ pango_layout_class_init (PangoLayoutClass *class) /** * PangoLayout:wrap: (attributes org.gtk.Property.get=pango_layout_get_wrap org.gtk.Property.set=pango_layout_set_wrap) * - * The wrap mode of this `PangoLayout. + * The wrap mode of this `PangoLayout`. * * The wrap mode influences how Pango chooses line breaks * when text needs to be wrapped. @@ -468,7 +468,7 @@ pango_layout_class_init (PangoLayoutClass *class) /** * PangoLayout:indent: (attributes org.gtk.Property.get=pango_layout_get_indent org.gtk.Property.set=pango_layout_set_indent) * - * The indent of this `PangoLayout. + * The indent of this `PangoLayout`. * * The indent is specified in Pango units. * @@ -485,7 +485,7 @@ pango_layout_class_init (PangoLayoutClass *class) /** * PangoLayout:alignment: (attributes org.gtk.Property.get=pango_layout_get_alignment org.gtk.Property.set=pango_layout_set_alignment) * - * The alignment mode of this `PangoLayout. + * The alignment mode of this `PangoLayout`. * * The default value is `PANGO_ALIGN_NATURAL`. */ @@ -497,7 +497,7 @@ pango_layout_class_init (PangoLayoutClass *class) /** * PangoLayout:ellipsize: (attributes org.gtk.Property.get=pango_layout_get_ellipsize org.gtk.Property.set=pango_layout_set_ellipsize) * - * The ellipsization mode of this `PangoLayout. + * The ellipsization mode of this `PangoLayout`. * * The default value is `PANGO_ELLIPSIZE_NONE`. */ @@ -888,7 +888,7 @@ pango_layout_get_serial (PangoLayout *layout) * pango_layout_context_changed: * @layout: a `PangoLayout` * - * Forces recomputation of any state in the `PangoLayout` that + * Forces recomputation of any state in the layout that * might depend on the layout's context. * * This function should be called if you make changes to the @@ -1507,7 +1507,7 @@ pango_layout_set_ellipsize (PangoLayout *layout, * pango_layout_get_ellipsize: * @layout: a `PangoLayout` * - * Gets the type of ellipsization being performed for @layout. + * Gets the type of ellipsization being performed for the layout. * * See [method@Pango.Layout.set_ellipsize]. * @@ -1657,7 +1657,7 @@ pango_layout_get_character_count (PangoLayout *layout) * pango_layout_get_lines: * @layout: a `PangoLayout` * - * Gets the lines of the @layout. + * Gets the lines of the layout. * * The returned object will become invalid when any * property of @layout is changed. Take a reference @@ -1681,8 +1681,7 @@ pango_layout_get_lines (PangoLayout *layout) * @layout: a `PangoLayout` * @n_attrs: (out): return location for the length of the array * - * Gets the `PangoLogAttr` array for the content - * of @layout. + * Gets the `PangoLogAttr` array for the content of layout. * * The returned array becomes invalid when * any properties of @layout change. Make a diff --git a/pango/pango-line-breaker.c b/pango/pango-line-breaker.c index 76d125cc..9d906a08 100644 --- a/pango/pango-line-breaker.c +++ b/pango/pango-line-breaker.c @@ -28,7 +28,7 @@ * A `PangoLineBreaker` breaks text into lines. * * To use a `PangoLineBreaker`, you must call [method@Pango.LineBreaker.add_text] - * to provide text that you want to break into lines, plus possibly attribute + * to provide text that you want to break into lines, plus possibly attributes * to influence the formatting. * * Then you can call [method@Pango.LineBreaker.next_line] repeatedly to obtain @@ -2288,7 +2288,7 @@ pango_line_breaker_new (PangoContext *context) * pango_line_breaker_get_context: * @self: a `PangoLineBreaker` * - * Retrieves the context used for this `PangoLineBreaker`. + * Retrieves the context used for the `PangoLineBreaker`. * * Returns: (transfer none): the `PangoContext` for @self */ @@ -2344,7 +2344,7 @@ pango_line_breaker_set_tabs (PangoLineBreaker *self, * pango_line_breaker_get_tabs: * @self: a `PangoLineBreaker` * - * Gets the current `PangoTabArray` used by this `PangoLineBreaker`. + * Gets the current `PangoTabArray` used by the `PangoLineBreaker`. * * If no `PangoTabArray` has been set, then the default tabs are * in use and %NULL is returned. Default tabs are every 8 spaces. @@ -2367,7 +2367,7 @@ pango_line_breaker_get_tabs (PangoLineBreaker *self) * @self: a `PangoLineBreaker` * @direction: the direction * - * Sets the base direction for lines produced by this `PangoLineBreaker`. + * Sets the base direction for lines produced by the `PangoLineBreaker`. * * If @direction is `PANGO_DIRECTION_NEUTRAL`, the direction is determined * from the content. This is the default behavior. @@ -2390,7 +2390,7 @@ pango_line_breaker_set_base_dir (PangoLineBreaker *self, * pango_line_breaker_get_base_dir: * @self: a `PangoLineBreaker` * - * Gets the base direction for lines produced by this `PangoLineBreaker`. + * Gets the base direction for lines produced by the `PangoLineBreaker`. * * See [method@Pango.LineBreaker.set_base_dir]. */ @@ -2565,7 +2565,7 @@ pango_line_breaker_next_line (PangoLineBreaker *self, * @self: a `PangoLineBreaker` * @line: (transfer none): the most recent line produced by @self * - * Re-adds the content of @line to the unprocessed + * Re-adds the content of a line to the unprocessed * input of the `PangoLineBreaker`. * * This can be used to try this line again with diff --git a/pango/pango-lines.c b/pango/pango-lines.c index 3f0b5faf..fe6f9352 100644 --- a/pango/pango-lines.c +++ b/pango/pango-lines.c @@ -392,7 +392,7 @@ pango_lines_get_line_position (PangoLines *lines, * pango_lines_get_unknown_glyphs_count: * @lines: a `PangoLines` object * - * Counts the number of unknown glyphs in @lines. + * Counts the number of unknown glyphs in the `PangoLines` * * This function can be used to determine if there are any fonts * available to render all characters in a certain string, or when @@ -429,7 +429,7 @@ pango_lines_get_unknown_glyphs_count (PangoLines *lines) * pango_lines_is_wrapped: * @lines: a `PangoLines` object * - * Returns whether any line in @lines is wrapped. + * Returns whether any of the lines is wrapped. * * Returns: `TRUE` if @lines is wrapped */ @@ -450,7 +450,7 @@ pango_lines_is_wrapped (PangoLines *lines) * pango_lines_is_ellipsized: * @lines: a `PangoLines` object * - * Returns whether any line in @lines is ellipsized. + * Returns whether any of the lines is ellipsized. * * Returns: `TRUE` if @lines is ellipsized */ @@ -471,7 +471,7 @@ pango_lines_is_ellipsized (PangoLines *lines) * pango_lines_is_hyphenated: * @lines: a `PangoLines` object * - * Returns whether any line in @lines is hyphenated. + * Returns whether any of the lines is hyphenated. * * Returns: `TRUE` if @lines is hyphenated */ @@ -497,7 +497,7 @@ pango_lines_is_hyphenated (PangoLines *lines) * @ink_rect: (out) (optional): return location for the ink extents * @logical_rect: (out) (optional): return location for the logical extents * - * Computes the extents of @lines. + * Computes the extents of the lines. * * Logical extents are usually what you want for positioning things. Note * that the extents may have non-zero x and y. You may want to use those @@ -600,7 +600,7 @@ pango_lines_get_size (PangoLines *lines, * pango_lines_get_baseline: * @lines: a `PangoLines` object * - * Gets the Y position of baseline of the first line in @lines. + * Gets the Y position of baseline of the first line. * * Return value: baseline of first line */ @@ -774,7 +774,7 @@ pango_lines_get_x_ranges (PangoLines *lines, } /* }}} */ - /* {{{ Editing API */ + /* { {{ Editing API */ /** * pango_lines_index_to_line: diff --git a/pango/pango-types.h b/pango/pango-types.h index 97344d38..f39f35b2 100644 --- a/pango/pango-types.h +++ b/pango/pango-types.h @@ -310,7 +310,6 @@ typedef enum PANGO_LEADING_TRIM_NONE = 0, PANGO_LEADING_TRIM_START = 1 << 0, PANGO_LEADING_TRIM_END = 1 << 1, - } PangoLeadingTrim; /** diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c index 6058ff68..49733a7f 100644 --- a/pango/pangofc-fontmap.c +++ b/pango/pangofc-fontmap.c @@ -603,12 +603,12 @@ pango_fc_font_map_set_config (PangoFcFontMap *self, * pango_fc_font_map_get_config: (skip) * @self: a `PangoFcFontMap` * - * Fetches the `FcConfig` attached to a font map. + * Fetches the fontconfig configuration of the fontmap. * * See also: [method@PangoFc.FontMap.set_config]. * * Returns: (nullable): the `FcConfig` object attached to - * @self, which might be %NULL. The return value is + * @self, which might be `NULL`. The return value is * owned by Pango and should not be freed. */ FcConfig * -- cgit v1.2.1