2 files changed, 16 insertions, 7 deletions
diff --git a/pango/pango-script.c b/pango/pango-script.c
index 43be3fa0..4faf2b91 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -73,13 +73,15 @@
  * pango_script_for_unichar:
  * @ch: a Unicode character
  *
- * Looks up the #PangoScript for a particular character (as defined by
+ * Looks up the script for a particular character (as defined by
  * Unicode Standard Annex \#24). No check is made for @ch being a
  * valid Unicode character; if you pass in invalid character, the
  * result is undefined.
  *
- * As of Pango 1.18, this function simply returns the return value of
- * g_unichar_get_script().
+ * Note that while the return type of this function is declared
+ * as PangoScript, as of Pango 1.18, this function simply returns
+ * the return value of g_unichar_get_script(). Callers must be
+ * prepared to handle unknown values.
  *
  * Return value: the #PangoScript for the character.
  *
@@ -170,6 +172,11 @@ pango_script_iter_free (PangoScriptIter *iter)
  * The range is the set of locations p where *start <= p < *end.
  * (That is, it doesn't include the character stored at *end)
  *
+ * Note that while the type of the @script argument is declared
+ * as PangoScript, as of Pango 1.18, this function simply returns
+ * GUnicodeScript values. Callers must be prepared to handle unknown
+ * values.
+ *
  * Since: 1.4
  **/
 void
diff --git a/pango/pango-script.h b/pango/pango-script.h
index 62876025..cce4e4d1 100644
--- a/pango/pango-script.h
+++ b/pango/pango-script.h
@@ -158,12 +158,14 @@ typedef struct _PangoScriptIter PangoScriptIter;
  *
  * The #PangoScript enumeration identifies different writing
  * systems. The values correspond to the names as defined in the
- * Unicode standard.
- * Note that new types may be added in the future. Applications should be ready
- * to handle unknown values.  This enumeration is interchangeable with
- * #GUnicodeScript.  See <ulink
+ * Unicode standard. See <ulink
  * url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex
  * #24: Script names</ulink>.
+ *
+ * Note that this enumeration is deprecated and will not be updated
+ * to include values in newer versions of the Unicode standard.
+ * Applications should use the GUnicodeScript enumeration instead,
+ * whose values are interchangeable with PangoScript.
  */
 typedef enum {                         /* ISO 15924 code */
       PANGO_SCRIPT_INVALID_CODE = -1,