[pango/utf8-docs] Clarify docs around text input

[Matthias Clasen <matthiasc src gnome org>]

commit 8d39b9ac1d6462a224d37a4cbc0d81b052c0e313
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Dec 12 15:43:50 2018 -0500

    Clarify docs around text input
    
    Make it clear that all text input must be valid UTF-8,
    except in the case pango_layout_set_text, which we now
    officially document as accepting and handling invalid
    input.

 pango/break.c         |  6 +++---
 pango/pango-context.c |  2 +-
 pango/pango-layout.c  | 20 +++++++++++---------
 pango/pango-utils.c   |  2 +-
 4 files changed, 16 insertions(+), 14 deletions(-)
---
diff --git a/pango/break.c b/pango/break.c
index cdac9c27..355518eb 100644
--- a/pango/break.c
+++ b/pango/break.c
@@ -139,7 +139,7 @@ typedef enum
 
 /**
  * pango_default_break:
- * @text: text to break
+ * @text: text to break. Must be valid UTF-8
  * @length: length of text in bytes (may be -1 if @text is nul-terminated)
  * @analysis: (nullable): a #PangoAnalysis for the @text
  * @attrs: logical attributes to fill in
@@ -1650,7 +1650,7 @@ tailor_break (const gchar   *text,
 
 /**
  * pango_break:
- * @text:      the text to process
+ * @text:      the text to process. Must be valid UTF-8
  * @length:    length of @text in bytes (may be -1 if @text is nul-terminated)
  * @analysis:  #PangoAnalysis structure from pango_itemize()
  * @attrs:     (array length=attrs_len): an array to store character
@@ -1810,7 +1810,7 @@ tailor_segment (const char      *range_start,
 
 /**
  * pango_get_log_attrs:
- * @text: text to process
+ * @text: text to process. Must be valid UTF-8
  * @length: length in bytes of @text
  * @level: embedding level, or -1 if unknown
  * @language: language tag
diff --git a/pango/pango-context.c b/pango/pango-context.c
index b48b0eaa..626f46e3 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -1616,7 +1616,7 @@ itemize_with_font (PangoContext               *context,
  * pango_itemize:
  * @context:   a structure holding information that affects
               the itemization process.
- * @text:      the text to itemize.
+ * @text:      the text to itemize. Must be valid UTF-8
  * @start_index: first byte in @text to process
  * @length:    the number of bytes (not characters) to process
  *             after @start_index.
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 397c9499..a3850843 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -1006,7 +1006,7 @@ pango_layout_is_ellipsized (PangoLayout *layout)
 /**
  * pango_layout_set_text:
  * @layout: a #PangoLayout
- * @text: a valid UTF-8 string
+ * @text: the text
  * @length: maximum length of @text, in bytes. -1 indicates that
  *          the string is nul-terminated and the length should be
  *          calculated.  The text will also be truncated on
@@ -1014,12 +1014,15 @@ pango_layout_is_ellipsized (PangoLayout *layout)
  *          positive.
  *
  * Sets the text of the layout.
- *
- * Note that if you have used
- * pango_layout_set_markup() or pango_layout_set_markup_with_accel() on
- * @layout before, you may want to call pango_layout_set_attributes() to clear
- * the attributes set on the layout from the markup as this function does not
- * clear attributes.
+ * 
+ * This function validates @text and renders invalid UTF-8
+ * with a placeholder glyph.
+ *
+ * Note that if you have used pango_layout_set_markup() or
+ * pango_layout_set_markup_with_accel() on @layout before, you may
+ * want to call pango_layout_set_attributes() to clear the attributes
+ * set on the layout from the markup as this function does not clear
+ * attributes.
  **/
 void
 pango_layout_set_text (PangoLayout *layout,
@@ -1044,8 +1047,7 @@ pango_layout_set_text (PangoLayout *layout,
 
   layout->length = strlen (layout->text);
 
-  /* validate it, and replace invalid bytes with '?'
-   */
+  /* validate it, and replace invalid bytes with -1 */
   start = layout->text;
   for (;;) {
     gboolean valid;
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index 04bbd7cf..088a60d6 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -798,7 +798,7 @@ pango_lookup_aliases (const char   *fontname,
 
 /**
  * pango_find_base_dir:
- * @text:   the text to process
+ * @text:   the text to process. Must be valid UTF-8
  * @length: length of @text in bytes (may be -1 if @text is nul-terminated)
  *
  * Searches a string the first character that has a strong