From 08e67e152d82007bd8e96beec0559e984f9a01fb Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 15 Feb 2021 01:16:48 -0500 Subject: docs: Port PangoItem to the new doc format Replace gtk-doc'isms and use gi-docgen links instead. --- pango/pango-item.c | 78 ++++++++++++++++++++++++++++-------------------------- pango/pango-item.h | 11 +++++--- 2 files changed, 48 insertions(+), 41 deletions(-) diff --git a/pango/pango-item.c b/pango/pango-item.c index dae65645..d1caa771 100644 --- a/pango/pango-item.c +++ b/pango/pango-item.c @@ -10,7 +10,7 @@ * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public @@ -27,11 +27,11 @@ /** * pango_item_new: * - * Creates a new #PangoItem structure initialized to default values. + * Creates a new `PangoItem` structure initialized to default values. * - * Return value: the newly allocated #PangoItem, which should - * be freed with pango_item_free(). - **/ + * Return value: the newly allocated `PangoItem`, which should + * be freed with [method@Pango.Item.free]. + */ PangoItem * pango_item_new (void) { @@ -42,14 +42,14 @@ pango_item_new (void) /** * pango_item_copy: - * @item: (nullable): a #PangoItem, may be %NULL + * @item: (nullable): a `PangoItem`, may be %NULL * - * Copy an existing #PangoItem structure. + * Copy an existing `PangoItem` structure. * - * Return value: (nullable): the newly allocated #PangoItem, which - * should be freed with pango_item_free(), or %NULL if - * @item was %NULL. - **/ + * Return value: (nullable): the newly allocated `PangoItem`, which + * should be freed with [method@Pango.Item.free], or %NULL if + * @item was %NULL. + */ PangoItem * pango_item_copy (PangoItem *item) { @@ -58,7 +58,7 @@ pango_item_copy (PangoItem *item) if (item == NULL) return NULL; - + result = g_slice_new (PangoItem); result->offset = item->offset; @@ -84,9 +84,9 @@ pango_item_copy (PangoItem *item) /** * pango_item_free: - * @item: (nullable): a #PangoItem, may be %NULL + * @item: (nullable): a `PangoItem`, may be %NULL * - * Free a #PangoItem and all associated memory. + * Free a `PangoItem` and all associated memory. **/ void pango_item_free (PangoItem *item) @@ -112,28 +112,31 @@ G_DEFINE_BOXED_TYPE (PangoItem, pango_item, /** * pango_item_split: - * @orig: a #PangoItem - * @split_index: byte index of position to split item, relative to the start of the item + * @orig: a `PangoItem` + * @split_index: byte index of position to split item, relative to the + * start of the item * @split_offset: number of chars between start of @orig and @split_index * * Modifies @orig to cover only the text after @split_index, and * returns a new item that covers the text before @split_index that - * used to be in @orig. You can think of @split_index as the length of - * the returned item. @split_index may not be 0, and it may not be - * greater than or equal to the length of @orig (that is, there must - * be at least one byte assigned to each item, you can't create a - * zero-length item). @split_offset is the length of the first item in - * chars, and must be provided because the text used to generate the - * item isn't available, so pango_item_split() can't count the char - * length of the split items itself. + * used to be in @orig. + * + * You can think of @split_index as the length of the returned item. + * @split_index may not be 0, and it may not be greater than or equal + * to the length of @orig (that is, there must be at least one byte + * assigned to each item, you can't create a zero-length item). + * @split_offset is the length of the first item in chars, and must be + * provided because the text used to generate the item isn't available, + * so `pango_item_split()` can't count the char length of the split items + * itself. * * Return value: new item representing text before @split_index, which - * should be freed with pango_item_free(). - **/ + * should be freed with [method@Pango.Item.free]. + */ PangoItem* -pango_item_split (PangoItem *orig, - int split_index, - int split_offset) +pango_item_split (PangoItem *orig, + int split_index, + int split_offset) { PangoItem *new_item; @@ -169,14 +172,15 @@ compare_attr (gconstpointer p1, gconstpointer p2) /** * pango_item_apply_attrs: - * @item: a #PangoItem - * @iter: a #PangoAttrIterator - * - * Add attributes to a PangoItem. The idea is that you have - * attributes that don't affect itemization, such as font features, - * so you filter them out using pango_attr_list_filter(), itemize - * your text, then reapply the attributes to the resulting items - * using this function. + * @item: a `PangoItem` + * @iter: a `PangoAttrIterator` + * + * Add attributes to a `PangoItem`. + * + * The idea is that you have attributes that don't affect itemization, + * such as font features, so you filter them out using + * [method@Pango.AttrList.filter], itemize your text, then reapply the + * attributes to the resulting items using this function. * * The @iter should be positioned before the range of the item, * and will be advanced past it. This function is meant to be called diff --git a/pango/pango-item.h b/pango/pango-item.h index d4162f90..9c02a45a 100644 --- a/pango/pango-item.h +++ b/pango/pango-item.h @@ -66,13 +66,13 @@ typedef struct _PangoItem PangoItem; * @lang_engine: unused * @font: the font for this segment. * @level: the bidirectional level for this segment. - * @gravity: the glyph orientation for this segment (A #PangoGravity). + * @gravity: the glyph orientation for this segment (A `PangoGravity`). * @flags: boolean flags for this segment (Since: 1.16). - * @script: the detected script for this segment (A #PangoScript) (Since: 1.18). + * @script: the detected script for this segment (A `PangoScript`) (Since: 1.18). * @language: the detected language for this segment. * @extra_attrs: extra attributes for this segment. * - * The #PangoAnalysis structure stores information about + * The `PangoAnalysis` structure stores information about * the properties of a segment of text. */ struct _PangoAnalysis @@ -98,7 +98,10 @@ struct _PangoAnalysis * @num_chars: number of Unicode characters in the item. * @analysis: analysis results for the item. * - * The #PangoItem structure stores information about a segment of text. + * The `PangoItem` structure stores information about a segment of text. + * + * You typically obtain `PangoItems` by itemizing a piece of text + * with [func@itemize]. */ struct _PangoItem { -- cgit v1.2.1