summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--pango/pango-glyph-item.c90
-rw-r--r--pango/pango-glyph-item.h53
-rw-r--r--pango/pango-glyph.h44
-rw-r--r--pango/pango-item.h9
4 files changed, 104 insertions, 92 deletions
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index 326ae37f..8cca8627 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -30,13 +30,15 @@
/**
* pango_glyph_item_split:
- * @orig: a #PangoItem
+ * @orig: a `PangoItem`
* @text: text to which positions in @orig apply
* @split_index: byte index of position to split item, relative to the start of the item
*
* Modifies @orig to cover only the text after @split_index, and
* returns a new item that covers the text before @split_index that
- * used to be in @orig. You can think of @split_index as the length of
+ * used to be in @orig.
+ *
+ * You can think of @split_index as the length of
* the returned item. @split_index may not be 0, and it may not be
* greater than or equal to the length of @orig (that is, there must
* be at least one byte assigned to each item, you can't create a
@@ -132,11 +134,11 @@ pango_glyph_item_split (PangoGlyphItem *orig,
/**
* pango_glyph_item_copy:
- * @orig: (nullable): a #PangoGlyphItem, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`, may be %NULL
*
- * Make a deep copy of an existing #PangoGlyphItem structure.
+ * Make a deep copy of an existing `PangoGlyphItem` structure.
*
- * Return value: (nullable): the newly allocated #PangoGlyphItem, which should
+ * Return value: (nullable): the newly allocated `PangoGlyphItem`, which should
* be freed with pango_glyph_item_free(), or %NULL
* if @orig was %NULL.
*
@@ -160,9 +162,9 @@ pango_glyph_item_copy (PangoGlyphItem *orig)
/**
* pango_glyph_item_free:
- * @glyph_item: (nullable): a #PangoGlyphItem, may be %NULL
+ * @glyph_item: (nullable): a `PangoGlyphItem`, may be %NULL
*
- * Frees a #PangoGlyphItem and resources to which it points.
+ * Frees a `PangoGlyphItem` and resources to which it points.
*
* Since: 1.6
**/
@@ -187,13 +189,13 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item,
/**
* pango_glyph_item_iter_copy:
- * @orig: (nullable): a #PangoGlyphItemIter, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`Iter, may be %NULL
*
- * Make a shallow copy of an existing #PangoGlyphItemIter structure.
+ * Make a shallow copy of an existing `PangoGlyphItemIter` structure.
*
- * Return value: (nullable): the newly allocated #PangoGlyphItemIter, which should
- * be freed with pango_glyph_item_iter_free(), or %NULL
- * if @orig was %NULL.
+ * Return value: (nullable): the newly allocated `PangoGlyphItemIter`,
+ * which should be freed with pango_glyph_item_iter_free(), or %NULL
+ * if @orig was %NULL.
*
* Since: 1.22
**/
@@ -214,9 +216,9 @@ pango_glyph_item_iter_copy (PangoGlyphItemIter *orig)
/**
* pango_glyph_item_iter_free:
- * @iter: (nullable): a #PangoGlyphItemIter, may be %NULL
+ * @iter: (nullable): a `PangoGlyphItemIter`, may be %NULL
*
- * Frees a #PangoGlyphItemIter created by pango_glyph_item_iter_copy().
+ * Frees a `PangoGlyphItem`Iter.
*
* Since: 1.22
**/
@@ -235,13 +237,14 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItemIter, pango_glyph_item_iter,
/**
* pango_glyph_item_iter_next_cluster:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
*
* Advances the iterator to the next cluster in the glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
*
- * Return value: %TRUE if the iterator was advanced, %FALSE if we were already on the
- * last cluster.
+ * See `PangoGlyphItemIter` for details of cluster orders.
+ *
+ * Return value: %TRUE if the iterator was advanced,
+ * %FALSE if we were already on the last cluster.
*
* Since: 1.22
**/
@@ -325,13 +328,13 @@ pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter)
/**
* pango_glyph_item_iter_prev_cluster:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
*
* Moves the iterator to the preceding cluster in the glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
+ * See `PangoGlyphItemIter` for details of cluster orders.
*
- * Return value: %TRUE if the iterator was moved, %FALSE if we were already on the
- * first cluster.
+ * Return value: %TRUE if the iterator was moved,
+ * %FALSE if we were already on the first cluster.
*
* Since: 1.22
**/
@@ -418,13 +421,14 @@ pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter)
/**
* pango_glyph_item_iter_init_start:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
* @glyph_item: the glyph item to iterate over
* @text: text corresponding to the glyph item
*
- * Initializes a #PangoGlyphItemIter structure to point to the
+ * Initializes a `PangoGlyphItemIter` structure to point to the
* first cluster in a glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
+ *
+ * See `PangoGlyphItemIter` for details of cluster orders.
*
* Return value: %FALSE if there are no clusters in the glyph item
*
@@ -456,13 +460,14 @@ pango_glyph_item_iter_init_start (PangoGlyphItemIter *iter,
/**
* pango_glyph_item_iter_init_end:
- * @iter: a #PangoGlyphItemIter
+ * @iter: a `PangoGlyphItemIter`
* @glyph_item: the glyph item to iterate over
* @text: text corresponding to the glyph item
*
- * Initializes a #PangoGlyphItemIter structure to point to the
+ * Initializes a `PangoGlyphItemIter` structure to point to the
* last cluster in a glyph item.
- * See #PangoGlyphItemIter for details of cluster orders.
+ *
+ * See `PangoGlyphItemIter` for details of cluster orders.
*
* Return value: %FALSE if there are no clusters in the glyph item
*
@@ -554,12 +559,14 @@ split_before_cluster_start (ApplyAttrsState *state)
* pango_glyph_item_apply_attrs:
* @glyph_item: a shaped item
* @text: text that @list applies to
- * @list: a #PangoAttrList
+ * @list: a `PangoAttrList`
*
- * Splits a shaped item (PangoGlyphItem) into multiple items based
- * on an attribute list. The idea is that if you have attributes
+ * Splits a shaped item (`PangoGlyphItem`) into multiple items based
+ * on an attribute list.
+ *
+ * The idea is that if you have attributes
* that don't affect shaping, such as color or underline, to avoid
- * affecting shaping, you filter them out (pango_attr_list_filter()),
+ * affecting shaping, you filter them out ([method@Pango.AttrList.filter]),
* apply the shaping process and then reapply them to the result using
* this function.
*
@@ -567,7 +574,7 @@ split_before_cluster_start (ApplyAttrsState *state)
* to that cluster; for instance, if half of a cluster is underlined
* and the other-half strikethrough, then the cluster will end
* up with both underline and strikethrough attributes. In these
- * cases, it may happen that item->extra_attrs for some of the
+ * cases, it may happen that @item->extra_attrs for some of the
* result items can have multiple attributes of the same type.
*
* This function takes ownership of @glyph_item; it will be reused
@@ -575,7 +582,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 pango_glyph_item_free(), the list using
+ * the elements using [method@Pango.GlyphItem.free], the list using
* g_slist_free().
*
* Since: 1.2
@@ -711,7 +718,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item,
/**
* pango_glyph_item_letter_space:
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a `PangoGlyphItem`
* @text: text that @glyph_item corresponds to
* (glyph_item->item->offset is an offset from the
* start of @text)
@@ -726,7 +733,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item,
* give the effect of typographic letter spacing.
*
* Since: 1.6
- **/
+ */
void
pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
const char *text,
@@ -784,7 +791,7 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
/**
* pango_glyph_item_get_logical_widths:
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a `PangoGlyphItem`
* @text: text that @glyph_item corresponds to
* (glyph_item->item->offset is an offset from the
* start of @text)
@@ -793,12 +800,13 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
* glyph_item->item->num_chars) to be filled in with
* the resulting character widths.
*
- * Given a #PangoGlyphItem and the corresponding
- * text, determine the screen width corresponding to each character. When
- * multiple characters compose a single cluster, the width of the entire
+ * Given a `PangoGlyphItem` and the corresponding text, determine the width
+ * corresponding to each character.
+ *
+ * When multiple characters compose a single cluster, the width of the entire
* cluster is divided equally among the characters.
*
- * See also pango_glyph_string_get_logical_widths().
+ * See also [method@Pango.GlyphString.get_logical_widths].
*
* Since: 1.26
**/
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index 543d74bd..8a1dbff4 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -31,14 +31,15 @@ G_BEGIN_DECLS
/**
* PangoGlyphItem:
- * @item: corresponding #PangoItem.
- * @glyphs: corresponding #PangoGlyphString.
- *
- * A #PangoGlyphItem is a pair of a #PangoItem and the glyphs
- * resulting from shaping the text corresponding to an item.
- * As an example of the usage of #PangoGlyphItem, the results
- * of shaping text with #PangoLayout is a list of #PangoLayoutLine,
- * each of which contains a list of #PangoGlyphItem.
+ * @item: corresponding `PangoItem`
+ * @glyphs: corresponding `PangoGlyphString`
+ *
+ * A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs
+ * 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`,
+ * each of which contains a list of `PangoGlyphItem`.
*/
typedef struct _PangoGlyphItem PangoGlyphItem;
@@ -84,21 +85,23 @@ void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
/**
* PangoGlyphItemIter:
*
- * A #PangoGlyphItemIter is an iterator over the clusters in a
- * #PangoGlyphItem. The *forward direction* of the
- * iterator is the logical direction of text. That is, with increasing
- * @start_index and @start_char values. If @glyph_item is right-to-left
- * (that is, if `glyph_item->item->analysis.level` is odd),
+ * A `PangoGlyphItemIter` is an iterator over the clusters in a
+ * `PangoGlyphItem`.
+ *
+ * The *forward direction* of the iterator is the logical direction of text.
+ * That is, with increasing @start_index and @start_char values. If @glyph_item
+ * is right-to-left (that is, if `glyph_item->item->analysis.level` is odd),
* then @start_glyph decreases as the iterator moves forward. Moreover,
* in right-to-left cases, @start_glyph is greater than @end_glyph.
*
- * An iterator should be initialized using either of
- * pango_glyph_item_iter_init_start() and
+ * 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
* respectively, and walked over using any desired mixture of
* pango_glyph_item_iter_next_cluster() and
- * pango_glyph_item_iter_prev_cluster(). A common idiom for doing a
- * forward iteration over the clusters is:
+ * pango_glyph_item_iter_prev_cluster().
+ *
+ * A common idiom for doing a forward iteration over the clusters is:
*
* ```
* PangoGlyphItemIter cluster_iter;
@@ -114,14 +117,14 @@ void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
* ```
*
* Note that @text is the start of the text for layout, which is then
- * indexed by `glyph_item->item->offset` to get to the
- * text of @glyph_item. The @start_index and @end_index values can directly
- * index into @text. The @start_glyph, @end_glyph, @start_char, and @end_char
- * values however are zero-based for the @glyph_item. For each cluster, the
- * item pointed at by the start variables is included in the cluster while
- * the one pointed at by end variables is not.
- *
- * None of the members of a #PangoGlyphItemIter should be modified manually.
+ * indexed by `glyph_item->item->offset` to get to the text of @glyph_item.
+ * The @start_index and @end_index values can directly index into @text. The
+ * @start_glyph, @end_glyph, @start_char, and @end_char values however are
+ * zero-based for the @glyph_item. For each cluster, the item pointed at by
+ * the start variables is included in the cluster while the one pointed at by
+ * end variables is not.
+ *
+ * None of the members of a `PangoGlyphItemIter` should be modified manually.
*
* Since: 1.22
*/
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 628eac96..7c1bf7b5 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -36,8 +36,10 @@ typedef struct _PangoGlyphString PangoGlyphString;
/**
* PangoGlyphUnit:
*
- * The #PangoGlyphUnit type is used to store dimensions within
- * Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit.
+ * The `PangoGlyphUnit` type is used to store dimensions within
+ * Pango.
+ *
+ * Dimensions are stored in 1/%PANGO_SCALE of a device unit.
* (A device unit might be a pixel for screen display, or
* a point on a printer.) %PANGO_SCALE is currently 1024, and
* may change in the future (unlikely though), but you should not
@@ -54,7 +56,7 @@ typedef gint32 PangoGlyphUnit;
* @x_offset: horizontal offset from nominal character position.
* @y_offset: vertical offset from nominal character position.
*
- * The #PangoGlyphGeometry structure contains width and positioning
+ * The `PangoGlyphGeometry` structure contains width and positioning
* information for a single glyph.
*/
struct _PangoGlyphGeometry
@@ -68,15 +70,17 @@ struct _PangoGlyphGeometry
*/
/**
* PangoGlyphVisAttr:
- * @is_cluster_start: set for the first logical glyph in each cluster. (Clusters
- * are stored in visual order, within the cluster, glyphs
- * are always ordered in logical order, since visual
- * order is meaningless; that is, in Arabic text, accent glyphs
- * follow the glyphs for the base character.)
+ * @is_cluster_start: set for the first logical glyph in each cluster.
+ * (Clusters are stored in visual order, within the cluster, glyphs
+ * are always ordered in logical order, since visual order is meaningless;
+ * that is, in Arabic text, accent glyphs follow the glyphs for the
+ * base character.)
+ *
+ * A `PangoGlyphVisAttr` structure communicates information between
+ * the shaping and rendering phases.
*
- * The PangoGlyphVisAttr is used to communicate information between
- * the shaping phase and the rendering phase. More attributes may be
- * added in the future.
+ * Currently, it contains only cluster start information. yMore attributes
+ * may be added in the future.
*/
struct _PangoGlyphVisAttr
{
@@ -91,9 +95,8 @@ struct _PangoGlyphVisAttr
* @geometry: the positional information about the glyph.
* @attr: the visual attributes of the glyph.
*
- * The #PangoGlyphInfo structure represents a single glyph together with
+ * A `PangoGlyphInfo` structure represents a single glyph with
* positioning information and visual attributes.
- * It contains the following fields.
*/
struct _PangoGlyphInfo
{
@@ -102,9 +105,6 @@ struct _PangoGlyphInfo
PangoGlyphVisAttr attr;
};
-/* A string of glyphs with positional information and visual attributes -
- * ready for drawing
- */
/**
* PangoGlyphString:
* @num_glyphs: number of the glyphs in this glyph string.
@@ -113,10 +113,11 @@ struct _PangoGlyphInfo
* @log_clusters: logical cluster info, indexed by the byte index
* within the text corresponding to the glyph string.
*
- * The #PangoGlyphString structure is used to store strings
- * of glyphs with geometry and visual attribute information.
- * The storage for the glyph information is owned
- * by the structure which simplifies memory management.
+ * A `PangoGlyphString` is used to store strings of glyphs with geometry
+ * and visual attribute information.
+ *
+ * The storage for the glyph information is owned by the structure
+ * which simplifies memory management.
*/
struct _PangoGlyphString {
gint num_glyphs;
@@ -211,7 +212,8 @@ void pango_shape_full (const char *item_text,
* positioning of glyphs.
*
* Flags influencing the shaping process.
- * These can be passed to pango_shape_with_flags().
+ *
+ * `PangoShapeFlags` can be passed to pango_shape_with_flags().
*/
typedef enum {
PANGO_SHAPE_NONE = 0,
diff --git a/pango/pango-item.h b/pango/pango-item.h
index 638f970a..a1e95086 100644
--- a/pango/pango-item.h
+++ b/pango/pango-item.h
@@ -34,7 +34,8 @@ typedef struct _PangoItem PangoItem;
* PANGO_ANALYSIS_FLAG_CENTERED_BASELINE:
*
* Whether the segment should be shifted to center around the baseline.
- * Used in vertical writing directions mostly.
+ *
+ * This is mainly used in vertical writing directions.
*
* Since: 1.16
*/
@@ -43,8 +44,7 @@ typedef struct _PangoItem PangoItem;
/**
* PANGO_ANALYSIS_FLAG_IS_ELLIPSIS:
*
- * This flag is used to mark runs that hold ellipsized text,
- * in an ellipsized layout.
+ * Whether this run holds ellipsized text.
*
* Since: 1.36.7
*/
@@ -53,8 +53,7 @@ typedef struct _PangoItem PangoItem;
/**
* PANGO_ANALYSIS_FLAG_NEED_HYPHEN:
*
- * This flag tells Pango to add a hyphen at the end of the
- * run during shaping.
+ * Whether to add a hyphen at the end of the run during shaping.
*
* Since: 1.44
*/