[pango/shape-docs: 2/2] Amend the shaping api docs

[Matthias Clasen <matthiasc src gnome org>]

commit 2f45a0933160f33cc968e32d93c4baf3df067a66
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Nov 7 12:01:23 2020 -0500

    Amend the shaping api docs
    
    Discuss problems with extra_attr indices in the
    docs for pango_shape() and friends.
    
    See: #511

 pango/shape.c | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 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