Merge branch 'shape-docs' into 'master'

Shape docs

See merge request GNOME/pango!259

2 files changed, 21 insertions, 6 deletions

diff --git a/pango/shape.c b/pango/shape.c
index efdb3177..04624b00 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -45,14 +45,18 @@
  * @analysis:  #PangoAnalysis structure from pango_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().
+ * 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().
  *
  * It is recommended that you use pango_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,
+ * so you need to subtract the item offset from their indices before
+ * calling pango_shape().
  */
 void
 pango_shape (const gchar         *text,
@@ -83,6 +87,11 @@ pango_shape (const gchar         *text,
  * 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.
  *
+ * Note that the extra attributes in the @analyis that is returned from
+ * 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 pango_shape_full().
+ *
  * Since: 1.32
  */
 void
@@ -170,6 +179,12 @@ fallback_shape (const char          *text,
  * This is similar to 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
+ * 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
+ * pango_shape_with_flags().
+ *
  * Since: 1.44
  */
 void
diff --git a/tests/test-shape.c b/tests/test-shape.c
index 53d6d40a..043f3d31 100644
--- a/tests/test-shape.c
+++ b/tests/test-shape.c
@@ -185,8 +185,6 @@ test_file (const gchar *filename, GString *string)
   pango_attr_list_unref (itemize_attrs);
   pango_attr_list_unref (shape_attrs);
 
-  pango_attr_list_unref (attrs);
-
   for (l = items; l; l = l->next)
     {
       PangoItem *item = l->data;
@@ -281,6 +279,8 @@ test_file (const gchar *filename, GString *string)
   g_list_free_full (items, (GDestroyNotify)pango_item_free);
   g_free (contents);
   g_free (text);
+
+  pango_attr_list_unref (attrs);
 }
 
 static gchar *