Add more deprecation notes around PangoScript

Make it clear that PangoScript is deprecated, and will
not be updated. And that all APIs are in fact returning
GUnicodeScript, and callers have to handle that.

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,