[pango/pango2: 20/68] Get the docs in shape
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pango/pango2: 20/68] Get the docs in shape
- Date: Tue, 14 Jun 2022 11:26:18 +0000 (UTC)
commit 2179352c0734b4bbe0b51dd526b1ea1450fbc681
Author: Matthias Clasen <mclasen redhat com>
Date: Sun Jun 12 08:34:17 2022 -0400
Get the docs in shape
CODING_STYLE.md | 12 ++--
docs/meson.build | 137 +----------------------------------------
docs/pango.toml.in | 36 ++++-------
docs/pango_bidi.md | 32 +++++-----
docs/pango_cairo.md | 21 ++++---
docs/pango_fonts.md | 24 ++++----
docs/pango_markup.md | 27 ++++----
docs/pango_rendering.md | 12 ++--
docs/pango_xft.md | 26 --------
docs/pangocairo.toml.in | 42 -------------
docs/pangofc.toml.in | 39 ------------
docs/pangoft2.toml.in | 39 ------------
docs/pangoot.toml.in | 33 ----------
docs/pangoxft.toml.in | 41 ------------
pango/meson.build | 1 +
pango/pango-attr-iterator.c | 2 +-
pango/pango-attr-list.c | 5 +-
pango/pango-attr.c | 6 +-
pango/pango-attributes.c | 10 +++
pango/pango-attributes.h | 4 ++
pango/pango-break.h | 4 +-
pango/pango-color.c | 2 +-
pango/pango-context.c | 11 ++--
pango/pango-direction.h | 15 +++--
pango/pango-font-description.c | 12 ++--
pango/pango-font-face.c | 27 +++++++-
pango/pango-font-family.c | 12 ++++
pango/pango-font.c | 6 ++
pango/pango-fontmap.c | 20 +++---
pango/pango-fontset.c | 14 ++++-
pango/pango-fontset.h | 11 ----
pango/pango-glyph-item.c | 11 ++--
pango/pango-glyph-item.h | 2 +-
pango/pango-glyph-iter.h | 8 +--
pango/pango-glyph.h | 2 +-
pango/pango-item.c | 17 +++++
pango/pango-language.c | 4 +-
pango/pango-layout.c | 7 ++-
pango/pango-line.c | 6 +-
pango/pango-lines.c | 2 +-
pango/pango-run.c | 2 +-
pango/pango-types.h | 2 -
pango/pangocairo-context.c | 19 +++---
pango/pangocairo-render.c | 2 +-
pango/pangofc-fontmap.c | 6 +-
pango/shape.c | 18 ++----
46 files changed, 242 insertions(+), 549 deletions(-)
---
diff --git a/CODING_STYLE.md b/CODING_STYLE.md
index d9456439a..a32f3e52a 100644
--- a/CODING_STYLE.md
+++ b/CODING_STYLE.md
@@ -58,19 +58,19 @@ in the gtk-doc / gnome-doc style. For instance:
* @layout: a `PangoLayout`
* @line: the index of a line, which must be between 0 and
* `pango_layout_get_line_count(layout) - 1`, inclusive.
- *
+ *
* Retrieves a particular line from a `PangoLayout` (or @layout.)
- *
- * Return value: the requested `PangoLayoutLine`, or %NULL
+ *
+ * Return value: the requested `PangoLine`, 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 *
+PangoLine *
pango_layout_get_line (PangoLayout *layout,
- int line)
+ int line)
[...]
```
@@ -96,7 +96,7 @@ Choosing Function Names
int pango_layout_get_line_count (PangoLayout *layout);
```
- Not:
+ Not:
```c
pango_layout_line_count ();
diff --git a/docs/meson.build b/docs/meson.build
index d61d552bd..1b6b50b89 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,4 +1,4 @@
-gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
+gidocgen = find_program('gi-docgen', required: get_option('docs'))
pango_content_files = [
'pango_rendering.md',
@@ -50,6 +50,7 @@ pango_content_files = [
'line-height2-dark.png',
'line-height3-light.png',
'line-height3-dark.png',
+ 'rotated-text.png',
]
doc_conf = configuration_data()
@@ -80,137 +81,3 @@ custom_target('pango-doc',
install: true,
install_dir: docs_dir,
)
-
-if build_pangoft2
- pangoft2_toml = configure_file(input: 'pangoft2.toml.in',
- output: 'pangoft2.toml',
- configuration: doc_conf)
-
- custom_target('pangoft-doc',
- input: pangoft2_gir[0],
- output: 'PangoFT2',
- command: [
- gidocgen,
- 'generate',
- '--quiet',
- '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
- '--config', pangoft2_toml,
- '--output-dir=@OUTPUT@',
- '--no-namespace-dir',
- '--content-dir=@0@'.format(meson.current_source_dir()),
- '@INPUT@',
- ],
- depend_files: [ pangoft2_toml, 'pango-name.png' ],
- build_by_default: true,
- install: true,
- install_dir: docs_dir,
- )
-endif
-
-if xft_dep.found() and fontconfig_dep.found()
- pangoxft_toml = configure_file(input: 'pangoxft.toml.in',
- output: 'pangoxft.toml',
- configuration: doc_conf)
-
- custom_target('pangoxft-doc',
- input: pangoxft_gir[0],
- output: 'PangoXft',
- command: [
- gidocgen,
- 'generate',
- '--quiet',
- '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
- '--config', pangoxft_toml,
- '--output-dir=@OUTPUT@',
- '--no-namespace-dir',
- '--content-dir=@0@'.format(meson.current_source_dir()),
- '@INPUT@',
- ],
- depend_files: [ pangoxft_toml, 'pango-name.png' ],
- build_by_default: true,
- install: true,
- install_dir: docs_dir,
- )
-endif
-
-if cairo_dep.found()
- pangocairo_content_files = [
- 'pango_cairo.md',
- 'pango-name.png',
- 'rotated-text.png',
- ]
-
- pangocairo_toml = configure_file(input: 'pangocairo.toml.in',
- output: 'pangocairo.toml',
- configuration: doc_conf)
-
- custom_target('pangocairo-doc',
- input: pangocairo_gir[0],
- output: 'PangoCairo',
- command: [
- gidocgen,
- 'generate',
- '--quiet',
- '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
- '--config', pangocairo_toml,
- '--output-dir=@OUTPUT@',
- '--no-namespace-dir',
- '--content-dir=@0@'.format(meson.current_source_dir()),
- '@INPUT@',
- ],
- depend_files: [ pangocairo_toml, pangocairo_content_files ],
- build_by_default: true,
- install: true,
- install_dir: docs_dir,
- )
-endif
-
-if fontconfig_dep.found()
- pangoot_toml = configure_file(input: 'pangoot.toml.in',
- output: 'pangoot.toml',
- configuration: doc_conf)
-
- custom_target('pangoot-doc',
- input: pangoot_gir[0],
- output: 'PangoOT',
- command: [
- gidocgen,
- 'generate',
- '--quiet',
- '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
- '--config', pangoot_toml,
- '--output-dir=@OUTPUT@',
- '--no-namespace-dir',
- '--content-dir=@0@'.format(meson.current_source_dir()),
- '@INPUT@',
- ],
- depend_files: [ pangoot_toml, 'pango-name.png' ],
- build_by_default: true,
- install: true,
- install_dir: docs_dir,
- )
-
- pangofc_toml = configure_file(input: 'pangofc.toml.in',
- output: 'pangofc.toml',
- configuration: doc_conf)
-
- custom_target('pangofc-doc',
- input: pangofc_gir[0],
- output: 'PangoFc',
- command: [
- gidocgen,
- 'generate',
- '--quiet',
- '--add-include-path=@0@'.format(meson.current_build_dir() / '../pango'),
- '--config', pangofc_toml,
- '--output-dir=@OUTPUT@',
- '--no-namespace-dir',
- '--content-dir=@0@'.format(meson.current_source_dir()),
- '@INPUT@',
- ],
- depend_files: [ pangofc_toml, 'pango-name.png' ],
- build_by_default: true,
- install: true,
- install_dir: docs_dir,
- )
-endif
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index 9babafbad..b68aecdef 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -4,7 +4,7 @@ version = "@PANGO_VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/pango/";
repository_url = "https://gitlab.gnome.org/GNOME/pango.git";
website_url = "https://www.pango.org";
-authors = "Owen Taylor, Behdad Esfahbod"
+authors = "Owen Taylor, Behdad Esfahbod, Matthias Clasen"
logo_url = "pango-name.png"
license = "LGPL-2.1-or-later"
description = "Internationalized text layout and rendering"
@@ -24,34 +24,20 @@ search_index = true
description = "A text shaping library"
docs_url = "https://harfbuzz.github.io/";
- [dependencies."PangoCairo-1.0"]
- name = "PangoCairo"
- description = "Cairo support for Pango"
- docs_url = "../PangoCairo/"
+ [dependencies."Fribidi-0.0"]
+ name = "FriBidi"
+ description = "The Unicode bidirectional algorithm"
+ docs_url = "https://github.com/fribidi/fribidi";
- [dependencies."PangoFc-1.0"]
- name = "PangoFc"
- description = "Fontconfig support for Pango"
- docs_url = "../PangoFc/"
-
- [dependencies."PangoFT2-1.0"]
- name = "PangoFT2"
- description = "Freetype support for Pango"
- docs_url = "../PangoFT2/"
-
- [dependencies."PangoOT-1.0"]
- name = "PangoOT"
- description = "OpenType support for Pango"
- docs_url = "../PangoOT/"
-
- [dependencies."PangoXft-1.0"]
- name = "PangoXft"
- description = "Xft support for Pango"
- docs_url = "../PangoXft/"
+ [dependencies."Cairo-0.0"]
+ name = "cairo"
+ description = "A 2D graphics library"
+ docs_url = "https://www.cairographics.org/documentation/";
[theme]
name = "basic"
show_index_summary = true
+show_class_hierarchy = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/main/";
@@ -62,6 +48,7 @@ content_files = [
"pango_markup.md",
"pango_fonts.md",
"pango_bidi.md",
+ "pango_cairo.md",
]
content_images = [
@@ -109,6 +96,7 @@ content_images = [
"line-height2-dark.png",
"line-height3-light.png",
"line-height3-dark.png",
+ "rotated-text.png",
]
urlmap_file = "urlmap.js"
diff --git a/docs/pango_bidi.md b/docs/pango_bidi.md
index 996e97810..1f2f05474 100644
--- a/docs/pango_bidi.md
+++ b/docs/pango_bidi.md
@@ -9,10 +9,10 @@ Some applications however, need some help to correctly handle bidirectional text
The [enum@Pango.Direction] type can be used with [method@Pango.Context.set_base_dir]
to instruct Pango about direction of text, though in most cases Pango detects
-that correctly and automatically. For application that need more direct
-control over bidirectional setting of text, Pango provides APIs such as
-[func@unichar_direction], [func@find_base_dir], [func@get_mirror_char]
-or [func@Pango.BidiType.for_unichar].
+text direction correctly and automatically.
+
+Applications that need more direct control of text direction should use
+[fribidi](http://fribidi.org/) directly.
Here is an example for mixed-direction text (shown in logical order):
@@ -38,15 +38,17 @@ vertical text parameters.
<source srcset="vertical-dark.png" media="(prefers-color-scheme: dark)">
<img alt="gravity west, rotated 90 degrees" align="right" valign="top" src="vertical-light.png">
</picture>
-The way this is implemented is through the concept of *gravity*. Gravity tells glyphs which way is down, so
the gravity of normal Latin text is south. A gravity value of east means that glyphs will be rotated ninety
degrees
-counterclockwise. So, to render vertical text one needs
-to set the gravity and rotate the layout using the matrix machinery already
-in place. This has the huge advantage that most algorithms working on a
-[class@Pango.Layout] do not need any change as the assumption that lines run
-in the X direction and stack in the Y direction holds even for vertical text
-layouts.
-
-Here is an example for some English text rendered with gravity west, rotated 90 degrees:
+The way this is implemented is through the concept of *gravity*. Gravity
+tells glyphs which way is down, so the gravity of normal Latin text is south.
+A gravity value of east means that glyphs will be rotated ninety degrees
+counterclockwise. So, to render vertical text one needs to set the gravity
+and rotate the layout using the matrix machinery already in place. This has
+the huge advantage that most algorithms working on a [class@Pango.Layout] do
+not need any change as the assumption that lines run in the X direction and
+stack in the Y direction holds even for vertical text layouts.
+
+Here is an example for some English text rendered with gravity west,
+rotated 90 degrees:
Applications should only need to set base gravity on [class@Pango.Context] in use,
and let Pango decide the gravity assigned to each run of text. This automatically
@@ -58,8 +60,8 @@ other scripts are rotated normally.
The correct way to set gravity on a layout is to set it on the context associated
with it using [method@Pango.Context.set_base_gravity]. The context of a layout can
be accessed using [method@Pango.Layout.get_context]. The currently set base gravity
-of the context can be accessed using [method@Pango.Context.get_base_gravity] and the
-*resolved* gravity of it using [method@Pango.Context.get_gravity]. The resolved
+of the context can be accessed using [method@Pango.Context.get_base_gravity] and
+the *resolved* gravity of it using [method@Pango.Context.get_gravity]. The resolved
gravity is the same as the base gravity for the most part, except that if the base
gravity is set to `PANGO_GRAVITY_AUTO`, the resolved gravity will depend on the
current matrix set on context, and is derived using [func@Pango.Gravity.get_for_matrix].
diff --git a/docs/pango_cairo.md b/docs/pango_cairo.md
index 2edd8ba86..e13709181 100644
--- a/docs/pango_cairo.md
+++ b/docs/pango_cairo.md
@@ -11,15 +11,14 @@ files, and to the screen on X and on other windowing systems. The functions in
this section allow using Pango to render to Cairo surfaces.
Using Pango with Cairo is straightforward. A `PangoContext` created with
-pango_cairo_font_map_create_context() can be used on any Cairo context (`cairo_t`),
+[func@Pango.cairo_create_context] can be used on any Cairo context (`cairo_t`),
but needs to be updated to match the current transformation matrix and target
-surface of the Cairo context using pango_cairo_update_context(). The convenience
-functions pango_cairo_create_layout() and pango_cairo_update_layout() handle
-the common case where the program doesn't need to manipulate the properties of
-the `PangoContext`.
+surface of the Cairo context using [func@Pango.cairo_update_context]. The
+convenience function [func@Pango.cairo_update_layout] handles the common case
+where the program doesn't need to manipulate the properties of the `PangoContext`.
When you get the metrics of a layout or of a piece of a layout using functions
-such as pango_layout_get_extents(), the reported metrics are in user-space
+such as [method@Pango.Lines.get_extents], the reported metrics are in user-space
coordinates. If a piece of text is 10 units long, and you call
`cairo_scale (cr, 2.0)`, it still is more-or-less 10 units long. However, the
results will be affected by hinting (that is, the process of adjusting the text
@@ -42,6 +41,7 @@ static void
draw_text (cairo_t *cr)
{
PangoLayout *layout;
+ PangoLines *lines;
PangoFontDescription *desc;
int i;
@@ -59,6 +59,7 @@ draw_text (cairo_t *cr)
/* Draw the layout N_WORDS times in a circle */
for (i = 0; i < N_WORDS; i++)
{
+ PangoRectangle ext;
int width, height;
double angle = (360. * i) / N_WORDS;
double red;
@@ -74,9 +75,11 @@ draw_text (cairo_t *cr)
/* Inform Pango to re-layout the text with the new transformation */
pango_cairo_update_layout (cr, layout);
- pango_layout_get_size (layout, &width, &height);
- cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS);
- pango_cairo_show_layout (cr, layout);
+ lines = pango_layout_get_lines (layout);
+
+ pango_lines_get_extents (lines, NULL, &ext);
+ cairo_move_to (cr, - ((double)ext.width / PANGO_SCALE) / 2, - RADIUS);
+ pango_cairo_show_lines (cr, layout);
cairo_restore (cr);
}
diff --git a/docs/pango_fonts.md b/docs/pango_fonts.md
index 072c020fe..21dd98c01 100644
--- a/docs/pango_fonts.md
+++ b/docs/pango_fonts.md
@@ -4,10 +4,10 @@ Title: Fonts and Glyphs
# Fonts
-Pango supports a flexible architecture where a particular rendering architecture
-can supply an implementation of fonts. The `PangoFont` structure represents an
-abstract rendering-system-independent font. Pango provides routines to list
-available fonts, and to load a font matching a given description.
+Pango supports a flexible architecture where platform-specific code can supply
+an implementation of font enumeration. The `PangoFont` structure represents a
+rendering-system-independent font. Pango provides routines to list available
+fonts, and to load a font matching a given description.
Conceptually, Pango groups fonts into faces and families which are identified
by a name. A *font face* provides the different sizes of a single font style.
@@ -22,14 +22,14 @@ The central object for dealing with the available fonts on a system and caching
loaded fonts is a [class@Pango.FontMap]. An application typically uses a single
font map.
-Since the font map depends on the rendering architecture in use, you'll need to
-use the backend function pango_cairo_font_map_get_default() to obtain the default
-fontmap. Depending on the platform, it will return a `PangoCairoFcFontMap`, a
-`PangoCairoWin32FontMap` or a `PangoCairoCoreTextFontMap`.
+Since the font map depends on the platform in use, you'll need to use the backend
+function [func@Pango.FontMap.get_default] to obtain the default fontmap. Depending
+on the platform, it will return a `PangoFcFontMap`, a `PangoDirectWriterFontMap`
+or a `PangoCoreTextFontMap`.
-Once you have a fontmap, you can enumerate the available font families with
-[method@Pango.FontMap.list_families]. To enumerate the faces of a font family,
-use [method@Pango.FontFamily.list_faces].
+Once you have a fontmap, you can enumerate the available font families using
+the [iface@Gio.ListModel] implementation of the fontmap. To enumerate the faces
+of a font family, use the [iface@Gio.ListModel] implementation of the font family.
# Font Descriptions
@@ -55,7 +55,7 @@ and clustering information (i.e. which glyphs correspond to which characters).
A glyph is identified by a [alias@Pango.Glyph], which is a numeric ID. Note that
-glyph IDs are font-specific: the same character can be represented by diffferent
+glyph IDs are font-specific: the same character can be represented by different
glyph IDs in different fonts.
The mapping between characters and glyphs is in general neither 1-1 nor a map:
diff --git a/docs/pango_markup.md b/docs/pango_markup.md
index 80ed16562..909c1a39c 100644
--- a/docs/pango_markup.md
+++ b/docs/pango_markup.md
@@ -12,8 +12,7 @@ font or size attributes will influence the font selection that is happening duri
itemization, font features and letterspacing attributes will influence shaping, and
color or underline attributes will be used for rendering.
-Pango uses a simple structs for individual attributes, such as
-[struct@Pango.AttrColor] or [struct@Pango.AttrFontDesc]. Each attribute has a type,
+Pango uses a simple structs for individual attributes. Each attribute has a type,
and a start and end index that determine the range of characters that the attribute
applies to. See the [enum@Pango.AttrType] enumeration for all the possible
attribute types.
@@ -99,8 +98,7 @@ weight
font_variant
variant
: One of 'normal', 'small-caps', 'all-small-caps', 'petite-caps', 'all-petite-caps',
- 'unicase', 'title-caps'. Values other than 'normal' and 'small-caps' are available
- since 1.50.
+ 'unicase', 'title-caps'.
font_stretch
stretch
@@ -157,12 +155,12 @@ rise
baseline_shift
: Vertical displacement. In contrast to rise, baseline_shift attributes are cumulative.
The value can be a length in Pango units or in points (e.g. '5pt'), or 'superscript'
- or 'subscript'. Available since 1.50.
+ or 'subscript'.
font_scale:
: Font size change. The possible values are 'superscript', 'subscript' or 'small-caps'.
This is similar to the font_size values 'smaller' or 'larger', but uses font metrics
- to find the new size. Available since 1.50.
+ to find the new size.
strikethrough
: 'true' or 'false' whether to strike through the text.
@@ -196,28 +194,25 @@ show
insert_hyphens
: 'true' or 'false' to indicate whether hyphens should be inserted when breaking
- lines in the middle of words. Available since Pango 1.44.
+ lines in the middle of words.
allow_breaks
-: 'true' or 'false' to indicate whether breaking lines is allowed. Available
- since Pango 1.44.
+: 'true' or 'false' to indicate whether breaking lines is allowed.
line_height
: Overrides the line height. The value can be either a factor (< 1024) that is
used to scale up the logical extents of runs or an absolute value (in 1024th
of a point).
- Available since Pango 1.50.
text_transform
: Specifies how characters are transformed during shaping. The values can be
- 'none', 'lowercase', 'uppercase' or 'capitalize'. Support for text transformation
- was added in Pango 1.50.
+ 'none', 'lowercase', 'uppercase' or 'capitalize'.
segment
-: Overrides word or sentence boundaries. The value can be 'word' or 'sentence',
- to indicate that the span should be treated as a single word or sentence.
- Overlapping segments will be split to allow this, and line breaks will be
- adjusted accordingly. Available since Pango 1.50.
+: Overrides word or sentence boundaries. The value can be 'word', 'sentence',
+ or 'paragraph', to indicate that the span should be treated as a single word,
+ sentence or paragraph. Overlapping segments will be split to allow this, and
+ line breaks will be adjusted accordingly.
## Convenience Tags
diff --git a/docs/pango_rendering.md b/docs/pango_rendering.md
index fe80ef3f0..029a81b7f 100644
--- a/docs/pango_rendering.md
+++ b/docs/pango_rendering.md
@@ -19,21 +19,21 @@ Itemization
character. Use [func@Pango.itemize] to itemize text.
Shaping
-: converts characters into glyphs. Use [func@Pango.shape],
- [func@Pango.shape_full] or [func@Pango.shape_item] to shape text.
+: converts characters into glyphs. Use [func@Pango.shape] or
+ [func@Pango.shape_item] to shape text.
Line Breaking
: determines where line breaks should be inserted into a sequence of glyphs.
The functions [func@Pango.default_break], [func@Pango.tailor_break] and
[func@Pango.attr_break] determine possible line breaks. The actual line
- breaking is done by [class@Pango.Layout].
+ breaking is done by [class@Pango.LineBreaker].
Justification
: adjusts inter-word spacing to form lines of even length. This is done by
- [class@Pango.Layout].
+ [struct Pango Line].
Rendering
: takes a string of positioned glyphs, and renders them onto a surface.
This is accomplished by a [class@Pango.Renderer] object. The functions
- pango_cairo_show_glyph_string() and pango_cairo_show_layout() use a
- [class@Pango.Renderer] to draw text onto a cairo surface.
+ [func@Pango.cairo_show_glyph_string] and [func@Pango.cairo_show_layout]
+ use a [class@Pango.Renderer] to draw text onto a cairo surface.
diff --git a/pango/meson.build b/pango/meson.build
index 279c9a0e8..09512fe41 100644
--- a/pango/meson.build
+++ b/pango/meson.build
@@ -97,6 +97,7 @@ pango_headers = [
pango_gir_includes = [
'HarfBuzz-0.0',
'GObject-2.0',
+ 'Gio-2.0'
]
if cairo_dep.found()
diff --git a/pango/pango-attr-iterator.c b/pango/pango-attr-iterator.c
index a3685655f..76205b8da 100644
--- a/pango/pango-attr-iterator.c
+++ b/pango/pango-attr-iterator.c
@@ -466,7 +466,7 @@ pango_attr_iterator_get_font (PangoAttrIterator *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.
+ * value and [func GLib SList free] on the list.
*/
GSList *
pango_attr_iterator_get_attrs (PangoAttrIterator *iterator)
diff --git a/pango/pango-attr-list.c b/pango/pango-attr-list.c
index cb6b423bd..96b90ce6c 100644
--- a/pango/pango-attr-list.c
+++ b/pango/pango-attr-list.c
@@ -178,8 +178,7 @@ pango_attr_list_unref (PangoAttrList *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.
+ * which should be freed with [method@Pango.AttrList.unref]
*/
PangoAttrList *
pango_attr_list_copy (PangoAttrList *list)
@@ -591,7 +590,7 @@ pango_attr_list_splice (PangoAttrList *list,
* Return value: (element-type Pango.Attribute) (transfer full):
* a list of all attributes in @list. To free this value,
* call [method@Pango.Attribute.destroy] on each value and
- * g_slist_free() on the list.
+ * [func GLib SList free] on the list
*/
GSList *
pango_attr_list_get_attributes (PangoAttrList *list)
diff --git a/pango/pango-attr.c b/pango/pango-attr.c
index 185ebcaa3..bde919564 100644
--- a/pango/pango-attr.c
+++ b/pango/pango-attr.c
@@ -154,7 +154,7 @@ is_valid_attr_type (guint type)
* If @name and @serialize are provided, they will be used
* to serialize attributes of this type.
*
- * To create attributes with the new type, use [func@Pango.attr_custom_new].
+ * To create attributes with the new type, use [ctor PangoAttribute new].
*
* Return value: the attribute type ID
*/
@@ -205,7 +205,7 @@ pango_attr_type_register (const char *name,
* [func@Pango.AttrType.register].
*
* The returned value is an interned string (see
- * g_intern_string() for what that means) that should
+ * [func@GLib.intern_string] for what that means) that should
* not be modified or freed.
*
* Return value: (nullable): the type ID name (which
@@ -449,7 +449,7 @@ pango_attribute_equal (const PangoAttribute *attr1,
* Creates a new attribute for the given type.
*
* The type must be one of the `PangoAttrType` values, or
- * have been registered with [func@Pango.register_attr_type].
+ * have been registered with [func@Pango.AttrType.register].
*
* Pango will initialize @start_index and @end_index to an
* all-inclusive range of `[0,G_MAXUINT]`. The caller is
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 64b46aa07..53bc01d10 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -356,6 +356,16 @@ pango_attr_underline_color_new (PangoColor *color)
return pango_attr_color_new (PANGO_ATTR_UNDERLINE_COLOR, color);
}
+/**
+ * pango_attr_underline_position_new:
+ * @position: the underline position
+ *
+ * Create a new underline position attribute.
+ *
+ * Return value: (transfer full): the newly allocated
+ * `PangoAttribute`, which should be freed with
+ * [method@Pango.Attribute.destroy]
+ */
PangoAttribute *
pango_attr_underline_position_new (PangoUnderlinePosition position)
{
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index 36d46533c..7e8310e30 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -25,8 +25,12 @@
G_BEGIN_DECLS
+#ifndef __GI_SCANNER__
#define PANGO_ATTR_TYPE(value, affects, merge) (PANGO_ATTR_VALUE_##value | (PANGO_ATTR_AFFECTS_##affects <<
8) | (PANGO_ATTR_MERGE_##merge << 12) | (__COUNTER__ << 16))
+
+#endif
+
/**
* PangoAttrType:
* @PANGO_ATTR_INVALID: does not happen
diff --git a/pango/pango-break.h b/pango/pango-break.h
index 3ada8a124..05f13ebeb 100644
--- a/pango/pango-break.h
+++ b/pango/pango-break.h
@@ -59,8 +59,8 @@ G_BEGIN_DECLS
* on grapheme boundaries (where @is_cursor_position is set). In some languages,
* the full grapheme (e.g. letter + diacritics) is considered a unit, while in
* others, each decomposed character in the grapheme is a unit. In the default
- * implementation of [func@break], this bit is set on all grapheme boundaries
- * except those following Latin, Cyrillic or Greek base characters.
+ * implementation of [func@default_break], this bit is set on all grapheme
+ * boundaries except those following Latin, Cyrillic or Greek base characters.
* @is_expandable_space: is a whitespace character that can possibly be
* expanded for justification purposes.
* @is_word_boundary: is a word boundary, as defined by UAX#29.
diff --git a/pango/pango-color.c b/pango/pango-color.c
index 8d67f62cb..03929a1b2 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -87,7 +87,7 @@ pango_color_free (PangoColor *color)
* red, green, and blue components respectively.
*
* Return value: a newly-allocated text string that must
- * be freed with g_free().
+ * be freed with [GLib.free]
*/
gchar *
pango_color_to_string (const PangoColor *color)
diff --git a/pango/pango-context.c b/pango/pango-context.c
index 6376d1ffc..c61a03da3 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -45,7 +45,8 @@
* to look up fonts, and default values such as the default language,
* default gravity, or default font.
*
- * To obtain a `PangoContext`, use [method@Pango.FontMap.create_context].
+ * To obtain a `PangoContext`, use [method@Pango.FontMap.create_context]
+ * or [func@Pango.cairo_create_context].
*/
struct _PangoContextClass
@@ -142,11 +143,11 @@ pango_context_finalize (GObject *object)
*
* If you are using Pango as part of a higher-level system,
* that system may have it's own way of create a `PangoContext`.
- * For instance, the GTK toolkit has, among others,
- * `gtk_widget_get_pango_context()`. Use those instead.
+ * Pango's own cairo support for instance, has [func@Pango.cairo_create_context],
+ * and the GTK toolkit has, among others, gtk_widget_get_pango_context().
+ * Use those instead.
*
- * Return value: the newly allocated `PangoContext`, which should
- * be freed with g_object_unref().
+ * Return value: the newly allocated `PangoContext`
*/
PangoContext *
pango_context_new (void)
diff --git a/pango/pango-direction.h b/pango/pango-direction.h
index 8857179d6..48e40276c 100644
--- a/pango/pango-direction.h
+++ b/pango/pango-direction.h
@@ -35,17 +35,16 @@ G_BEGIN_DECLS
* algorithm.
*
* Not every value in this enumeration makes sense for every usage of
- * `PangoDirection`; for example, the return value of [func@unichar_direction]
- * and [func@find_base_dir] cannot be `PANGO_DIRECTION_WEAK_LTR` or
- * `PANGO_DIRECTION_WEAK_RTL`, since every character is either neutral
- * or has a strong direction; on the other hand `PANGO_DIRECTION_NEUTRAL`
- * doesn't make sense to pass to [func@itemize].
+ * `PangoDirection`; for example, the direction of characters cannot be
+ * `PANGO_DIRECTION_WEAK_LTR` or `PANGO_DIRECTION_WEAK_RTL`, since every
+ * character is either neutral or has a strong direction; on the other hand
+ * `PANGO_DIRECTION_NEUTRAL` doesn't make sense to pass to [func@itemize].
*
* See `PangoGravity` for how vertical text is handled in Pango.
*
- * If you are interested in text direction, you should really use fribidi
- * directly. `PangoDirection` is only retained because it is used in some
- * public apis.
+ * If you are interested in text direction, you should really use
+ * [fribidi](http://fribidi.org/) directly. `PangoDirection` is only
+ * retained because it is used in some public apis.
*/
typedef enum {
PANGO_DIRECTION_LTR,
diff --git a/pango/pango-font-description.c b/pango/pango-font-description.c
index 485a641a1..38241f807 100644
--- a/pango/pango-font-description.c
+++ b/pango/pango-font-description.c
@@ -74,7 +74,7 @@ static const PangoFontDescription pfd_defaults = {
* Creates a new font description structure with all fields unset.
*
* Return value: the newly allocated `PangoFontDescription`, which
- * should be freed using [method Pango FontDescription free].
+ * should be freed using [method Pango FontDescription free]
*/
PangoFontDescription *
pango_font_description_new (void)
@@ -812,8 +812,7 @@ pango_font_description_better_match (const PangoFontDescription *desc,
* Make a copy of a `PangoFontDescription`.
*
* Return value: (nullable): the newly allocated `PangoFontDescription`,
- * which should be freed with [method Pango FontDescription free],
- * or %NULL if @desc was %NULL.
+ * which should be freed with [method Pango FontDescription free]
*/
PangoFontDescription *
pango_font_description_copy (const PangoFontDescription *desc)
@@ -855,8 +854,7 @@ pango_font_description_copy (const PangoFontDescription *desc)
* to be used when the copy is only needed temporarily.
*
* Return value: (nullable): the newly allocated `PangoFontDescription`,
- * which should be freed with [method Pango FontDescription free],
- * or %NULL if @desc was %NULL.
+ * which should be freed with [method Pango FontDescription free]
*/
PangoFontDescription *
pango_font_description_copy_static (const PangoFontDescription *desc)
@@ -941,7 +939,7 @@ case_insensitive_hash (const char *key)
* Computes a hash of a `PangoFontDescription` structure.
*
* This is suitable to be used, for example, as an argument
- * to g_hash_table_new(). The hash value is independent of @desc->mask.
+ * to [GLib.HashTable.new]. The hash value is independent of @desc->mask.
*
* Return value: the hash value.
*/
@@ -1454,7 +1452,7 @@ append_field (GString *str, const char *what, const FieldMap *map, int n_element
* the string description will only have a terminating comma if
* the last word of the list is a valid style option.
*
- * Return value: a new string that must be freed with g_free().
+ * Return value: a newly allocated string
*/
char *
pango_font_description_to_string (const PangoFontDescription *desc)
diff --git a/pango/pango-font-face.c b/pango/pango-font-face.c
index cbe0d3e49..f7d307e6f 100644
--- a/pango/pango-font-face.c
+++ b/pango/pango-font-face.c
@@ -23,6 +23,18 @@
#include "pango-font-face-private.h"
#include "pango-font-family.h"
+/**
+ * PangoFontFace:
+ *
+ * A `PangoFontFace` is used to represent a group of fonts with
+ * the same family, slant, weight, and width, but varying sizes.
+ *
+ * `PangoFontFace` provides APIs to determine coverage information,
+ * such as [method@Pango.FontFace.has_char] and
+ * [method@Pango.FontFace.supports_language], as well as general
+ * information about the font face like [method@Pango.FontFace.is_monospace]
+ * or [method@Pango.FontFace.is_variable].
+ */
G_DEFINE_ABSTRACT_TYPE (PangoFontFace, pango_font_face, G_TYPE_OBJECT)
@@ -179,7 +191,17 @@ pango_font_face_get_family (PangoFontFace *face)
* A monospace font is a font designed for text display where the the
* characters form a regular grid.
*
- * See [method@Pango.FontFamily.is_monospace] for more details.
+ * For Western languages this would mean that the advance width of all
+ * characters are the same, but this categorization also includes Asian
+ * fonts which include double-width characters: characters that occupy
+ * two grid cells. [func@GLib.unichar_iswide] returns a result that
+ * indicates whether a character is typically double-width in a monospace
+ * font.
+ *
+ * The best way to find out the grid-cell size is to call
+ * [method@Pango.FontMetrics.get_approximate_digit_width], since the
+ * results of [method@Pango.FontMetrics.get_approximate_char_width] may
+ * be affected by double-width characters.
*
* Returns: `TRUE` if @face is monospace
*/
@@ -198,7 +220,8 @@ pango_font_face_is_monospace (PangoFontFace *face)
* A variable font is a font which has axes that can be modified
* to produce variations.
*
- * See [method@Pango.FontFamily.is_variable] for more details.
+ * Such axes are also known as _variations_; see
+ * [method@Pango.FontDescription.set_variations] for more information.
*
* Returns: `TRUE` if @face is variable
*/
diff --git a/pango/pango-font-family.c b/pango/pango-font-family.c
index 8168ed8c9..91caba589 100644
--- a/pango/pango-font-family.c
+++ b/pango/pango-font-family.c
@@ -24,6 +24,18 @@
#include "pango-font-face.h"
#include "pango-font.h"
+/**
+ * PangoFontFamily:
+ *
+ * A `PangoFontFamily` is used to represent a family of related
+ * font faces.
+ *
+ * The font faces in a family share a common design, but differ in
+ * slant, weight, width or other aspects.
+ *
+ * `PangoFontFamily` implements the [iface@Gio.ListModel] interface,
+ * to provide a list of font faces.
+ */
static GType
pango_font_family_get_item_type (GListModel *list)
diff --git a/pango/pango-font.c b/pango/pango-font.c
index fbf1ddf57..9e2e17ad4 100644
--- a/pango/pango-font.c
+++ b/pango/pango-font.c
@@ -32,6 +32,12 @@
#include "pango-fontmap-private.h"
#include "pango-impl-utils.h"
+/**
+ * PangoFont:
+ *
+ * A `PangoFont` is used to represent a font in a
+ * rendering-system-independent manner.
+ */
G_DEFINE_ABSTRACT_TYPE (PangoFont, pango_font, G_TYPE_OBJECT)
diff --git a/pango/pango-fontmap.c b/pango/pango-fontmap.c
index 8eebcce39..1f74f77cf 100644
--- a/pango/pango-fontmap.c
+++ b/pango/pango-fontmap.c
@@ -59,9 +59,8 @@
/**
* PangoFontMap:
*
- * `PangoFontMap` is a `PangoFontMap` subclass for use with
- * `PangoHbFace` and `PangoHbFont`. It handles caching and
- * lookup of faces and fonts.
+ * `PangoFontMap` is the base class for font enumeration.
+ * It also handles caching and lookup of faces and fonts.
*
* Subclasses populate the fontmap using backend-specific APIs
* to enumerate the available fonts on the sytem, but it is
@@ -73,6 +72,9 @@
* generic families for monospace and sans-serif. These can
* be added using [method@Pango.FontMap.add_family] and
* [ctor Pango GenericFamily new].
+ *
+ * `PangoFontMap` implements the [iface@Gio.ListModel] interface,
+ * to provide a list of font families.
*/
@@ -770,7 +772,7 @@ pango_font_map_new (void)
* Adds @face to the `PangoFontMap`.
*
* This is most useful for creating transformed faces or aliases.
- * See [ctor@Pango.HbFace.new_synthetic] and [ctor@Pango.HbFace.new_instance].
+ * See [method@Pango.HbFace.new_synthetic] and [method@Pango.HbFace.new_instance].
*/
void
pango_font_map_add_face (PangoFontMap *self,
@@ -918,7 +920,7 @@ pango_font_map_add_family (PangoFontMap *self,
* @self: a `PangoFontMap`
* @family: a `PangoFontFamily` that belongs to @self
*
- * Removes a `PangoHbFamily` from a `PangoFontMap`
+ * Removes @family from a `PangoFontMap`
*/
void
pango_font_map_remove_family (PangoFontMap *self,
@@ -984,7 +986,7 @@ static GPrivate default_font_map = G_PRIVATE_INIT (g_object_unref); /* MT-safe *
*
* A fontmap is used to cache information about available fonts,
* and holds certain global parameters such as the resolution.
- * In most cases, you can use `func@Pango.font_map_get_default]
+ * In most cases, you can use [func@Pango.FontMap.get_default]
* instead.
*
* Note that the type of the returned object will depend
@@ -1057,7 +1059,7 @@ pango_font_map_new_default (void)
* platform that Pango is used on.
*
* The default fontmap can be changed by using
- * [method@Pango.FontMap.set_default]. This can be used to
+ * [method@Pango.FontMap.set_default].
*
* Note that the default fontmap is per-thread. Each thread gets
* its own default fontmap. In this way, Pango can be used safely
@@ -1093,11 +1095,11 @@ pango_font_map_get_default (void)
* This function only changes the default fontmap for
* the current thread. Default fontmaps of existing threads
* are not changed. Default fontmaps of any new threads will
- * still be created using [func@Pango.FontMap.new_default].
+ * still be created using [ctor@Pango.FontMap.new_default].
*
* A value of %NULL for @fontmap will cause the current default
* font map to be released and a new default font map to be created
- * on demand, using [func@Pango.FontMap.new_default].
+ * on demand, using [ctor@Pango.FontMap.new_default].
*/
void
pango_font_map_set_default (PangoFontMap *fontmap)
diff --git a/pango/pango-fontset.c b/pango/pango-fontset.c
index d8a3087e8..fb3bc22c9 100644
--- a/pango/pango-fontset.c
+++ b/pango/pango-fontset.c
@@ -21,8 +21,18 @@
#include "config.h"
-/*
- * PangoFontset
+/**
+ * PangoFontset:
+ *
+ * A `PangoFontset` represents a set of `PangoFont` to use when rendering text.
+ *
+ * A `PangoFontset` is the result of resolving a `PangoFontDescription`
+ * against a particular `PangoContext`. It has operations for finding the
+ * component font for a particular Unicode character, and for finding a
+ * composite set of metrics for the entire fontset.
+ *
+ * To obtain a `PangoFontset`, use [method@Pango.Context.load_fontset] or
+ * [method@Pango.FontMap.load_fontset].
*/
#include "pango-fontset-private.h"
diff --git a/pango/pango-fontset.h b/pango/pango-fontset.h
index cb1145dc5..9e5840a31 100644
--- a/pango/pango-fontset.h
+++ b/pango/pango-fontset.h
@@ -56,17 +56,6 @@ typedef gboolean (*PangoFontsetForeachFunc) (PangoFontset *fontset,
PangoFont *font,
gpointer user_data);
-/**
- * PangoFontset:
- *
- * A `PangoFontset` represents a set of `PangoFont` to use when rendering text.
- *
- * A `PangoFontset` is the result of resolving a `PangoFontDescription`
- * against a particular `PangoContext`. It has operations for finding the
- * component font for a particular Unicode character, and for finding a
- * composite set of metrics for the entire fontset.
- */
-
PANGO_AVAILABLE_IN_ALL
PangoFont * pango_fontset_get_font (PangoFontset *fontset,
guint wc);
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index e7455caea..fec4a8c5f 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -47,12 +47,11 @@
* 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.)
+ * This function is similar in function to [method@PangoItem.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 [method Pango GlyphItem free]
*/
PangoGlyphItem *
pango_glyph_item_split (PangoGlyphItem *orig,
@@ -216,7 +215,7 @@ pango_glyph_item_iter_copy (PangoGlyphItemIter *orig)
* pango_glyph_item_iter_free:
* @iter: (nullable): a `PangoGlyphItemIter`
*
- * Frees a `PangoGlyphItem`Iter.
+ * Frees a `PangoGlyphItemIter`.
*/
void
pango_glyph_item_iter_free (PangoGlyphItemIter *iter)
@@ -570,7 +569,7 @@ split_before_cluster_start (ApplyAttrsState *state)
* Return value: (transfer full) (element-type Pango.GlyphItem): a
* list of glyph items resulting from splitting @glyph_item. Free
* the elements using [method Pango GlyphItem free], the list using
- * g_slist_free().
+ * [func GLib SList free]
*/
GSList *
pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item,
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index 2907e0e4b..85902e3a7 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -41,7 +41,7 @@ G_BEGIN_DECLS
* resulting from shaping the items text.
*
* As an example of the usage of `PangoGlyphItem`, the results
- * of shaping text with `PangoLayout` is a list of `PangoLayoutLine`,
+ * of shaping text with `PangoLayout` is a list of `PangoLine`,
* each of which contains a list of `PangoGlyphItem`.
*/
typedef struct _PangoGlyphItem PangoGlyphItem;
diff --git a/pango/pango-glyph-iter.h b/pango/pango-glyph-iter.h
index 987c15aa2..870422679 100644
--- a/pango/pango-glyph-iter.h
+++ b/pango/pango-glyph-iter.h
@@ -36,11 +36,11 @@ G_BEGIN_DECLS
* in right-to-left cases, @start_glyph is greater than @end_glyph.
*
* An iterator should be initialized using either
- * pango_glyph_item_iter_init_start() or
- * pango_glyph_item_iter_init_end(), for forward and backward iteration
+ * [method@Pango.GlyphItemIter.init_start] or
+ * [method@Pango.GlyphItemIter.init_end], for forward and backward iteration
* respectively, and walked over using any desired mixture of
- * pango_glyph_item_iter_next_cluster() and
- * pango_glyph_item_iter_prev_cluster().
+ * [method@Pango.GlyphItemIter.next_cluster] and
+ * [method@Pango.GlyphItemIter.prev_cluster].
*
* A common idiom for doing a forward iteration over the clusters is:
*
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 5511b37a0..0b73742e9 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -220,7 +220,7 @@ void pango_glyph_string_index_to_x_full (PangoGlyphStrin
*
* Flags influencing the shaping process.
*
- * `PangoShapeFlags` can be passed to [func@Pango.shape_with_flags].
+ * `PangoShapeFlags` can be passed to [func@Pango.shape].
*/
typedef enum {
PANGO_SHAPE_NONE = 0,
diff --git a/pango/pango-item.c b/pango/pango-item.c
index 315dd9fa4..64ddbb76c 100644
--- a/pango/pango-item.c
+++ b/pango/pango-item.c
@@ -24,6 +24,23 @@
#include "pango-item-private.h"
#include "pango-impl-utils.h"
+/**
+ * PangoAnalysis:
+ *
+ * The `PangoAnalysis` structure stores information about
+ * the properties of a segment of text.
+ */
+
+/**
+ * PangoItem:
+ *
+ * The `PangoItem` structure stores information about
+ * a segment of text.
+ *
+ * You typically obtain `PangoItems` by itemizing a piece
+ * of text with [func@Pango.itemize].
+ */
+
/**
* pango_item_new:
*
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 737bcdb89..d7551edff 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -168,7 +168,7 @@ G_DEFINE_BOXED_TYPE (PangoLanguage, pango_language,
* variables, and does return a Unix-style locale string based on
* either said environment variables or the thread's current locale.
*
- * Return value: a dynamically allocated string, free with g_free().
+ * Return value: a dynamically allocated string, free with [GLib.free]
*/
static gchar *
_pango_get_lc_ctype (void)
@@ -281,7 +281,7 @@ _pango_get_lc_ctype (void)
*
* Also note that this function will not do the right thing if you
* use per-thread locales with uselocale(). In that case, you should
- * just call pango_language_from_string() yourself.
+ * just call [func@Pango.Language.from_string] yourself.
*
* Return value: (transfer none): the default language as a `PangoLanguage`
**/
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 17bea8acc..65548b16f 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -437,9 +437,10 @@ pango_layout_class_init (PangoLayoutClass *class)
* PangoLayout:single-paragraph: (attributes org.gtk.Property.get=pango_layout_get_single_paragraph
org.gtk.Property.set=pango_layout_set_single_paragraph)
*
* Whether to treat newlines and similar characters as paragraph
- * separators or not. If this property is `TRUE`, all text is kept
- * in a single paragraph, and paragraph separator characters are
- * displayed with a glyph.
+ * separators or not.
+ *
+ * If this property is `TRUE`, all text is kept in a single paragraph,
+ * and paragraph separator characters are displayed with a glyph.
*
* This is useful to allow editing of newlines on a single text line.
*
diff --git a/pango/pango-line.c b/pango/pango-line.c
index a12aebdec..f9382ea51 100644
--- a/pango/pango-line.c
+++ b/pango/pango-line.c
@@ -821,7 +821,7 @@ pango_line_is_hyphenated (PangoLine *line)
*
* Gets whether the line is justified.
*
- * See [method@Pango.LayoutLine.justify].
+ * See [method Pango Line.justify].
*
* Returns: `TRUE` if @line has been justified
*/
@@ -948,7 +948,7 @@ pango_line_justify (PangoLine *line,
* Gets the extents of the line.
*
* The logical extents returned by this function always include leading.
- * If you need extents with trimmed leading, use [method@Pango.LayoutLine.get_trimmed_extents].
+ * If you need extents with trimmed leading, use [method Pango Line.get_trimmed_extents].
*
* Note that the origin is at the left end of the baseline.
*
@@ -1520,7 +1520,7 @@ done:
*
* Note that @idx is allowed to be @line->start_index + @line->length.
*
- * This is a variant of [method@Pango.LayoutLine.get_cursor_pos] that applies
+ * This is a variant of [method Pango Line.get_cursor_pos] that applies
* font metric information about caret slope and offset to the positions
* it returns.
*
diff --git a/pango/pango-lines.c b/pango/pango-lines.c
index 253979ab0..01eea2bf1 100644
--- a/pango/pango-lines.c
+++ b/pango/pango-lines.c
@@ -553,7 +553,7 @@ pango_lines_get_baseline (PangoLines *lines)
* store a pointer to an array of ranges. The array will be of length
* `2*n_ranges`, with each range starting at `(*ranges)[2*n]` and of
* 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
+ * with [GLib.free]. The coordinates are relative to the layout and are in
* Pango units.
* @n_ranges: The number of ranges stored in @ranges
*
diff --git a/pango/pango-run.c b/pango/pango-run.c
index 88c1a6de2..5f04be8a3 100644
--- a/pango/pango-run.c
+++ b/pango/pango-run.c
@@ -10,7 +10,7 @@
/**
* PangoRun:
*
- * A `PangoRun` represents a single run within a `PangoLayoutLine`.
+ * A `PangoRun` represents a single run within a `PangoLine`.
*
* A run is a range of text with uniform script, font and attributes that
* is shaped as a unit.
diff --git a/pango/pango-types.h b/pango/pango-types.h
index d595587f5..97344d380 100644
--- a/pango/pango-types.h
+++ b/pango/pango-types.h
@@ -320,7 +320,6 @@ typedef enum
*/
#define PANGO_LEADING_TRIM_BOTH (PANGO_LEADING_TRIM_START|PANGO_LEADING_TRIM_END)
-
/*
* PANGO_DECLARE_INTERNAL_TYPE:
* @ModuleObjName: The name of the new type, in camel case (like GtkWidget)
@@ -360,5 +359,4 @@ typedef enum
return G_TYPE_INSTANCE_GET_CLASS (ptr, module_obj_name##_get_type (), ModuleObjName##Class); } \
G_GNUC_END_IGNORE_DEPRECATIONS
-
G_END_DECLS
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index 98eef290f..9a9686431 100644
--- a/pango/pangocairo-context.c
+++ b/pango/pangocairo-context.c
@@ -115,7 +115,7 @@ pango_cairo_update_context (cairo_t *cr,
*
* Sets the font options used when rendering text with this context.
*
- * These options override any options that [func@update_context]
+ * These options override any options that [func@Pango.cairo_update_context]
* derives from the target surface.
*/
void
@@ -160,10 +160,10 @@ pango_cairo_context_set_font_options (PangoContext *context,
* @context: a `PangoContext`, from a pangocairo font map
*
* Retrieves any font rendering options previously set with
- * [func@PangoCairo.context_set_font_options].
+ * [func@Pango.cairo_context_set_font_options].
*
* This function does not report options that are derived from
- * the target surface by [func@update_context].
+ * the target surface by [func@Pango.cairo_update_context].
*
* Return value: (nullable): the font options previously set on the
* context, or %NULL if no options have been set. This value is
@@ -203,10 +203,8 @@ pango_cairo_context_get_merged_font_options (PangoContext *context)
* This context can then be
* used to create a layout using [ctor Pango Layout new].
*
- * This function is a convenience function that creates a context using
- * the default font map, then updates it to @cr. If you just need to
- * create a layout for use with @cr and do not need to access `PangoContext`
- * directly, you can use [func@create_layout] instead.
+ * This function is a convenience function that creates a context
+ * using the default font map, then updates it to @cr.
*
* Return value: (transfer full): the newly created `PangoContext`
*/
@@ -228,11 +226,10 @@ pango_cairo_create_context (cairo_t *cr)
/**
* pango_cairo_update_layout:
* @cr: a Cairo context
- * @layout: a `PangoLayout`, from [func@create_layout]
+ * @layout: a `PangoLayout`
*
- * Updates the private `PangoContext` of a `PangoLayout` created with
- * [func@create_layout] to match the current transformation and target
- * surface of a Cairo context.
+ * Updates the private `PangoContext` of a `PangoLayout` to match
+ * the current transformation and target surface of a Cairo context.
*/
void
pango_cairo_update_layout (cairo_t *cr,
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 590ca4aa9..80a6cc19f 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -1056,7 +1056,7 @@ pango_cairo_show_glyph_string (cairo_t *cr,
*
* embedding the text associated with the glyphs in the output if the
* output format supports it (PDF for example), otherwise it acts
- * similar to [func@show_glyph_string].
+ * similar to [func@Pango.cairo_show_glyph_string].
*
* The origin of the glyphs (the left edge of the baseline) will
* be drawn at the current point of the cairo context.
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index 2d79be86b..99a78d343 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -551,10 +551,8 @@ pango_fc_font_map_class_init (PangoFcFontMapClass *class)
/**
* pango_fc_font_map_new:
*
- * Creates a new `PangoFcFontMap` object.
- *
- * Unless overridden by [method@PangoFc.FontMap.set_config],
- * this font map uses the default fontconfig configuration.
+ * Creates a new `PangoFcFontMap` using the default
+ * fontconfig configuration.
*
* Returns: a new `PangoFcFontMap`
*/
diff --git a/pango/shape.c b/pango/shape.c
index 6ce17b1d2..68edda99e 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -805,14 +805,10 @@ pango_shape_internal (const char *item_text,
* returned from [func@Pango.itemize], convert the characters into glyphs.
* You may also pass in only a substring of the item from [func@Pango.itemize].
*
- * This is similar to [func@Pango.shape_full], except it also takes flags
- * that can influence the shaping process.
- *
* Note that the extra attributes in the @analyis that is returned from
* [func@Pango.itemize] have indices that are relative to the entire paragraph,
* so you do not pass the full paragraph text as @paragraph_text, you need
- * to subtract the item offset from their indices before calling
- * [func@Pango.shape_with_flags].
+ * to subtract the item offset from their indices first.
*/
void
pango_shape (const char *item_text,
@@ -841,16 +837,14 @@ pango_shape (const char *item_text,
*
* Convert the characters in @item into glyphs.
*
- * This is similar to [func@Pango.shape_with_flags], except it takes a
- * `PangoItem` instead of separate @item_text and @analysis arguments.
- * It also takes @log_attrs, which may be used in implementing text
- * transforms.
+ * This is similar to [func@Pango.shape], except it takes a `PangoItem`
+ * instead of separate @item_text and @analysis arguments. It also takes
+ * @log_attrs, which may be used in implementing text transforms.
*
* Note that the extra attributes in the @analyis that is returned from
* [func@Pango.itemize] have indices that are relative to the entire paragraph,
- * so you do not pass the full paragraph text as @paragraph_text, you need
- * to subtract the item offset from their indices before calling
- * [func@Pango.shape_with_flags].
+ * so you do not pass the full paragraph text as @paragraph_text, you need to
+ * subtract the item offset from their indices before calling [func@Pango.shape].
*/
void
pango_shape_item (PangoItem *item,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
