summaryrefslogtreecommitdiff
path: root/pango
diff options
context:
space:
mode:
authorMatthias Clasen <mclasen@redhat.com>2021-02-15 01:16:48 -0500
committerMatthias Clasen <mclasen@redhat.com>2021-03-11 13:17:36 -0500
commit08e67e152d82007bd8e96beec0559e984f9a01fb (patch)
treee7081d013888d862a8a92a416a1081fb446e3d8f /pango
parent42f7a372cf18adea91aa28f27b061f74a6d05b32 (diff)
downloadpango-08e67e152d82007bd8e96beec0559e984f9a01fb.tar.gz
docs: Port PangoItem to the new doc format
Replace gtk-doc'isms and use gi-docgen links instead.
Diffstat (limited to 'pango')
-rw-r--r--pango/pango-item.c78
-rw-r--r--pango/pango-item.h11
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
{