Merge branch 'matthiasc/for-master' into 'master'

docs: Add some details

See merge request GNOME/pango!316

2 files changed, 16 insertions, 1 deletions

diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index e20b6413..db8d8262 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -214,7 +214,10 @@ typedef enum
  *     single characters, such as for keyboard accelerators.
  *     %PANGO_UNDERLINE_SINGLE should be used for extended
  *     portions of text.
- * @PANGO_UNDERLINE_ERROR: a wavy underline should be drawn below.
+ * @PANGO_UNDERLINE_ERROR: an underline indicating an error should
+ *     be drawn below. The exact style of rendering is up to the
+ *     `PangoRenderer` in use, but typical styles include wavy
+ *     or dotted lines.
  *     This underline is typically used to indicate an error such
  *     as a possible mispelling; in some cases a contrasting color
  *     may automatically be used. This type of underlining is
diff --git a/pango/pango-renderer.c b/pango/pango-renderer.c
index 2d676782..8f3c9846 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -157,6 +157,9 @@ pango_renderer_finalize (GObject *gobject)
  *
  * Draws @layout with the specified `PangoRenderer`.
  *
+ * This is equivalent to drawing the lines of the layout, at their
+ * respective positions relative to @x, @y.
+ *
  * Since: 1.8
  */
 void
@@ -558,6 +561,10 @@ draw_shaped_glyphs (PangoRenderer    *renderer,
  *
  * Draws @line with the specified `PangoRenderer`.
  *
+ * This draws the glyph items that make up the line, as well as
+ * shapes, backgrounds and lines that are specified by the attributes
+ * of those items.
+ *
  * Since: 1.8
  */
 void
@@ -807,6 +814,11 @@ pango_renderer_default_draw_glyphs (PangoRenderer    *renderer,
  *
  * This is useful for rendering text in PDF.
  *
+ * Note that this method does not handle attributes in @glyph_item.
+ * If you want colors, shapes and lines handled automatically according
+ * to those attributes, you need to use pango_renderer_draw_layout_line()
+ * or pango_renderer_draw_layout().
+ *
  * Note that @text is the start of the text for layout, which is then
  * indexed by `glyph_item->item->offset`.
  *