[pango/pango2: 198/201] Get the docs in shape
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pango/pango2: 198/201] Get the docs in shape
- Date: Sat, 11 Jun 2022 02:22:35 +0000 (UTC)
commit 2a4372e07306635b2b8141894fd0d07d9e1401ab
Author: Matthias Clasen <mclasen redhat com>
Date: Thu Jun 9 21:24:50 2022 -0400
Get the docs in shape
CODING_STYLE.md | 12 ++--
docs/meson.build | 136 +--------------------------------------------
docs/pango.toml.in | 31 +++--------
docs/pango_bidi.md | 32 ++++++-----
docs/pango_cairo.md | 11 ++--
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/pango-attr.c | 4 +-
pango/pango-attributes.c | 10 ++++
pango/pango-attributes.h | 4 ++
pango/pango-break.h | 4 +-
pango/pango-direction.h | 15 +++--
pango/pango-font-face.c | 21 ++++++-
pango/pango-font-family.c | 12 ++++
pango/pango-font.c | 6 ++
pango/pango-fontmap.c | 20 ++++---
pango/pango-glyph-item.h | 2 +-
pango/pango-glyph.h | 2 +-
pango/pango-hbface.c | 11 ++--
pango/pango-item.c | 17 ++++++
pango/pango-line.c | 6 +-
pango/pango-run.c | 2 +-
pango/pango-types.h | 2 -
pango/pango-userface.c | 12 ++--
pango/pangocairo-context.c | 19 +++----
pango/pangocairo-render.c | 2 +-
pango/pangofc-fontmap.c | 6 +-
pango/shape.c | 18 ++----
35 files changed, 191 insertions(+), 509 deletions(-)
---
diff --git a/CODING_STYLE.md b/CODING_STYLE.md
index d9456439..a32f3e52 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 d61d552b..b048fa63 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',
@@ -80,137 +80,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 9babafba..e461a874 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -24,30 +24,15 @@ 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"
diff --git a/docs/pango_bidi.md b/docs/pango_bidi.md
index 996e9781..1f2f0547 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 2edd8ba8..7624438d 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 [func@PangoLayout.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
diff --git a/docs/pango_fonts.md b/docs/pango_fonts.md
index 072c020f..21dd98c0 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 80ed1656..909c1a39 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 fe80ef3f..029a81b7 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/pango-attr.c b/pango/pango-attr.c
index 185ebcaa..276934e1 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
*/
@@ -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 e0806e87..9f6756fd 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 36d46533..7e8310e3 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 3ada8a12..05f13ebe 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-direction.h b/pango/pango-direction.h
index 8857179d..48e40276 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-face.c b/pango/pango-font-face.c
index cbe0d3e4..6271b3d6 100644
--- a/pango/pango-font-face.c
+++ b/pango/pango-font-face.c
@@ -23,6 +23,12 @@
#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.
+ */
G_DEFINE_ABSTRACT_TYPE (PangoFontFace, pango_font_face, G_TYPE_OBJECT)
@@ -179,7 +185,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 +214,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 8168ed8c..91caba58 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 fbf1ddf5..9e2e17ad 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 c113adc5..5436d03b 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-glyph-item.h b/pango/pango-glyph-item.h
index 2907e0e4..85902e3a 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.h b/pango/pango-glyph.h
index 5511b37a..0b73742e 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-hbface.c b/pango/pango-hbface.c
index a54eafa0..c92d4028 100644
--- a/pango/pango-hbface.c
+++ b/pango/pango-hbface.c
@@ -664,7 +664,7 @@ pango_hb_face_new_from_file (const char *file,
*
* Here, 'synthetic' means that the variant is implemented by rendering
* the glyphs differently, not by using data from the original @face.
- * See [ctor@Pango.HbFace.new_instance] for that.
+ * See [method@Pango.HbFace.new_instance] for that.
*
* @transform can be used to specify a non-trivial font matrix for creating
* synthetic italics or synthetic condensed variants of an existing face.
@@ -680,11 +680,12 @@ pango_hb_face_new_from_file (const char *file,
* be used to create generic aliases such as 'sans' or 'monospace'.
*
* Note that only the following fields in @description should be set:
- * - style or stretch, to indicate a transformed style
- * - weight, to indicate a bolder weight
- * - family, to provide an alternative family name
*
- * [method Pango Face.is_synthesized] will return `TRUE` for objects
+ * + style or stretch, to indicate a transformed style
+ * + weight, to indicate a bolder weight
+ * + family, to provide an alternative family name
+ *
+ * [method@Pango.FontFace.is_synthesized] will return `TRUE` for objects
* created by this function.
*
* Returns: (transfer full): a newly created `PangoHbFace`
diff --git a/pango/pango-item.c b/pango/pango-item.c
index a7cdbae1..1e230627 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-line.c b/pango/pango-line.c
index a12aebde..f9382ea5 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-run.c b/pango/pango-run.c
index 88c1a6de..5f04be8a 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 d595587f..97344d38 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/pango-userface.c b/pango/pango-userface.c
index a9f16c09..c924e686 100644
--- a/pango/pango-userface.c
+++ b/pango/pango-userface.c
@@ -309,7 +309,7 @@ pango_user_face_class_init (PangoUserFaceClass *class)
* @extents: (out caller-allocates): return location for font extents
* user_data: user data that was pased to [ctor Pango UserFace new]
*
- * The type of the function that is called to obtain font extents for user fonts.
+ * Type of a function that is called to obtain font extents for user fonts.
*
* Returns: `TRUE` on success
*/
@@ -321,7 +321,7 @@ pango_user_face_class_init (PangoUserFaceClass *class)
* @glyph: (out caller-allocates): return location for the glyph that
* user_data: user data that was pased to [ctor Pango UserFace new]
*
- * The type of the function that is called to determine if a user
+ * Type of a function that is called to determine if a user
* font can render a character, and what glyph it will use.
*
* Returns: `TRUE` on success
@@ -339,7 +339,7 @@ pango_user_face_class_init (PangoUserFaceClass *class)
* whether @glyph has color
* user_data: user data that was pased to [ctor Pango UserFace new]
*
- * The type of the function that is called to query information about
+ * Type of a function that is called to query information about
* a glyph in a user font.
*
* Returns: `TRUE` on success
@@ -356,7 +356,7 @@ pango_user_face_class_init (PangoUserFaceClass *class)
* @flags: `PangoShapeFlags` to use
* user_data: user data that was pased to [ctor Pango UserFace new]
*
- * The type of the function that is used to shape a segment of text
+ * Type of a function that is used to shape a segment of text
* with a user font.
*
* This callback is optional when creating a user font. If it isn't
@@ -370,7 +370,7 @@ pango_user_face_class_init (PangoUserFaceClass *class)
* that turn the text-to-glyph mapping into an m-n relationship. The
* function is responsible for filling not just the glyphs and their
* positions, but also cluster information and glyph attributes in
- * [struct@Pango.VisAttr].
+ * [struct@Pango.GlyphVisAttr].
*
* Returns: `TRUE` on success
*/
@@ -384,7 +384,7 @@ pango_user_face_class_init (PangoUserFaceClass *class)
* @backend_id: a string identifying the [class@Pango.Renderer] in use
* @backend_data: backend-specific data
*
- * The type of the function that is called to render a glyph with a
+ * Type of a function that is called to render a glyph with a
* user font.
*
* This callback is optional when creating a user font. IF it isn't
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index 54ce452d..f0b9517a 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 590ca4aa..80a6cc19 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 750b3d20..1a66acc2 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 6ce17b1d..68edda99 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]
