summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthias Clasen <mclasen@redhat.com>2021-02-19 08:09:54 -0500
committerMatthias Clasen <mclasen@redhat.com>2021-03-11 13:17:36 -0500
commit4ecf4e5770459eb0749b0715f7968a832beafd43 (patch)
tree095755c6917cac5cb29520b0ca6cba79674afb68
parent5340665b4d62a539d9361d3fb19e15c52dab4ccf (diff)
downloadpango-4ecf4e5770459eb0749b0715f7968a832beafd43.tar.gz
docs: Tweak shaping docs
Add summaries, convert markup, etc.
-rw-r--r--pango/shape.c78
1 files changed, 36 insertions, 42 deletions
diff --git a/pango/shape.c b/pango/shape.c
index 04624b00..1b2986c4 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -19,16 +19,6 @@
* Boston, MA 02111-1307, USA.
*/
-/**
- * SECTION:glyphs
- * @short_description:Structures for storing information about glyphs
- * @title:Glyphs
- *
- * pango_shape() produces a string of glyphs which
- * can be measured or drawn to the screen. The following
- * structures are used to store information about
- * glyphs.
- */
#include "config.h"
#include "pango-impl-utils.h"
@@ -40,23 +30,25 @@
/**
* pango_shape:
- * @text: the text to process
- * @length: the length (in bytes) of @text
- * @analysis: #PangoAnalysis structure from pango_itemize()
- * @glyphs: glyph string in which to store results
+ * @text: the text to process
+ * @length: the length (in bytes) of @text
+ * @analysis: `PangoAnalysis` structure from [func@itemize]
+ * @glyphs: glyph string in which to store results
*
- * Given a segment of text and the corresponding #PangoAnalysis structure
- * returned from pango_itemize(), convert the characters into glyphs. You
- * may also pass in only a substring of the item from pango_itemize().
+ * Convert the characters in @text into glyphs.
*
- * It is recommended that you use pango_shape_full() instead, since
+ * Given a segment of text and the corresponding `PangoAnalysis` structure
+ * returned from [func@itemize], convert the characters into glyphs. You
+ * may also pass in only a substring of the item from [func@itemize].
+ *
+ * It is recommended that you use [func@shape_full] instead, since
* that API allows for shaping interaction happening across text item
* boundaries.
*
* Note that the extra attributes in the @analyis that is returned from
- * pango_itemize() have indices that are relative to the entire paragraph,
+ * [func@itemize] have indices that are relative to the entire paragraph,
* so you need to subtract the item offset from their indices before
- * calling pango_shape().
+ * calling [func@shape].
*/
void
pango_shape (const gchar *text,
@@ -69,28 +61,29 @@ pango_shape (const gchar *text,
/**
* pango_shape_full:
- * @item_text: valid UTF-8 text to shape.
- * @item_length: the length (in bytes) of @item_text. -1 means nul-terminated text.
+ * @item_text: valid UTF-8 text to shape.
+ * @item_length: the length (in bytes) of @item_text. -1 means nul-terminated text.
* @paragraph_text: (allow-none): text of the paragraph (see details). May be %NULL.
* @paragraph_length: the length (in bytes) of @paragraph_text. -1 means nul-terminated text.
- * @analysis: #PangoAnalysis structure from pango_itemize().
- * @glyphs: glyph string in which to store results.
+ * @analysis: `PangoAnalysis` structure from [func@itemize].
+ * @glyphs: glyph string in which to store results.
+ *
+ * Convert the characters in @text into glyphs.
*
- * Given a segment of text and the corresponding
- * #PangoAnalysis structure returned from pango_itemize(),
- * convert the characters into glyphs. You may also pass
- * in only a substring of the item from pango_itemize().
+ * Given a segment of text and the corresponding `PangoAnalysis` structure
+ * returned from [func@itemize], convert the characters into glyphs. You may
+ * also pass in only a substring of the item from [func@itemize].
*
- * This is similar to pango_shape(), except it also can optionally take
+ * This is similar to [func@shape], except it also can optionally take
* the full paragraph text as input, which will then be used to perform
- * certain cross-item shaping interactions. If you have access to the broader
+ * certain cross-item shaping interactions. If you have access to the broader
* text of which @item_text is part of, provide the broader text as
- * @paragraph_text. If @paragraph_text is %NULL, item text is used instead.
+ * @paragraph_text. If @paragraph_text is %NULL, item text is used instead.
*
* Note that the extra attributes in the @analyis that is returned from
- * pango_itemize() have indices that are relative to the entire paragraph,
+ * [func@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 pango_shape_full().
+ * to subtract the item offset from their indices before calling [func@shape_full].
*
* Since: 1.32
*/
@@ -167,23 +160,24 @@ fallback_shape (const char *text,
* May be %NULL.
* @paragraph_length: the length (in bytes) of @paragraph_text.
* -1 means nul-terminated text.
- * @analysis: #PangoAnalysis structure from pango_itemize()
+ * @analysis: `PangoAnalysis` structure from [func@itemize]
* @glyphs: glyph string in which to store results
* @flags: flags influencing the shaping process
*
- * Given a segment of text and the corresponding
- * #PangoAnalysis structure returned from pango_itemize(),
- * convert the characters into glyphs. You may also pass
- * in only a substring of the item from pango_itemize().
+ * Convert the characters in @text into glyphs.
+ *
+ * Given a segment of text and the corresponding `PangoAnalysis` structure
+ * returned from [func@itemize], convert the characters into glyphs. You may
+ * also pass in only a substring of the item from [func@itemize].
*
- * This is similar to pango_shape_full(), except it also takes
- * flags that can influence the shaping process.
+ * This is similar to [func@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
- * pango_itemize() have indices that are relative to the entire paragraph,
+ * [func@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
- * pango_shape_with_flags().
+ * [func@shape_with_flags].
*
* Since: 1.44
*/