From 8061664ad1a5933098adc3bc1dca0b5be48586ef Mon Sep 17 00:00:00 2001
From: Behdad Esfahbod <behdad@behdad.org>
Date: Thu, 11 Oct 2018 14:16:55 -0400
Subject: [PATCH] Add doc stubs for recently added API

Thanks to David Corbett who revamped our script and language processing
and implemented full BCP 47 support.

https://github.com/harfbuzz/harfbuzz/pull/730

New API:
+hb_ot_layout_table_select_script()
+hb_ot_layout_script_select_language()
+HB_OT_MAX_TAGS_PER_SCRIPT
+HB_OT_MAX_TAGS_PER_LANGUAGE
+hb_ot_tags_from_script_and_language()
+hb_ot_tags_to_script_and_language()

Deprecated API:
-hb_ot_layout_table_choose_script()
-hb_ot_layout_script_find_language()
-hb_ot_tags_from_script()
-hb_ot_tag_from_language()
---
 src/hb-ot-layout.cc | 10 ++++++++++
 src/hb-ot-tag.cc    | 21 ++++++++++++++++-----
 src/hb-ot-tag.h     | 10 ++++++++++
 src/hb-unicode.h    |  2 +-
 4 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc
index 8c9184251..aa36954d0 100644
--- a/src/hb-ot-layout.cc
+++ b/src/hb-ot-layout.cc
@@ -373,6 +373,11 @@ hb_ot_layout_table_choose_script (hb_face_t      *face,
   return hb_ot_layout_table_select_script (face, table_tag, t - script_tags, script_tags, script_index, chosen_script);
 }
 
+/**
+ * hb_ot_layout_table_select_script:
+ *
+ * Since: REPLACEME
+ **/
 hb_bool_t
 hb_ot_layout_table_select_script (hb_face_t      *face,
 				  hb_tag_t        table_tag,
@@ -481,6 +486,11 @@ hb_ot_layout_script_find_language (hb_face_t    *face,
   return hb_ot_layout_script_select_language (face, table_tag, script_index, 1, &language_tag, language_index);
 }
 
+/**
+ * hb_ot_layout_script_select_language:
+ *
+ * Since: REPLACEME
+ **/
 hb_bool_t
 hb_ot_layout_script_select_language (hb_face_t      *face,
 				     hb_tag_t        table_tag,
diff --git a/src/hb-ot-tag.cc b/src/hb-ot-tag.cc
index 0987fe131..13b1e0fa5 100644
--- a/src/hb-ot-tag.cc
+++ b/src/hb-ot-tag.cc
@@ -332,6 +332,7 @@ parse_private_use_subtag (const char     *private_use_subtag,
  *
  * Converts an #hb_script_t and an #hb_language_t to script and language tags.
  *
+ * Since: REPLACEME
  **/
 void
 hb_ot_tags_from_script_and_language (hb_script_t   script,
@@ -441,6 +442,7 @@ hb_ot_tag_to_language (hb_tag_t tag)
  * Converts a script tag and a language tag to an #hb_script_t and an
  * #hb_language_t.
  *
+ * Since: REPLACEME
  **/
 void
 hb_ot_tags_to_script_and_language (hb_tag_t       script_tag,
@@ -451,19 +453,28 @@ hb_ot_tags_to_script_and_language (hb_tag_t       script_tag,
   hb_script_t script_out = hb_ot_tag_to_script (script_tag);
   if (script)
     *script = script_out;
-  if (language) {
+  if (language)
+  {
     unsigned int script_count = 1;
     hb_tag_t primary_script_tag[1];
-    hb_ot_tags_from_script_and_language (script_out, HB_LANGUAGE_INVALID, &script_count, primary_script_tag, nullptr, nullptr);
+    hb_ot_tags_from_script_and_language (script_out,
+					 HB_LANGUAGE_INVALID,
+					 &script_count,
+					 primary_script_tag,
+					 nullptr, nullptr);
     *language = hb_ot_tag_to_language (language_tag);
-    if (script_count == 0 || primary_script_tag[0] != script_tag) {
+    if (script_count == 0 || primary_script_tag[0] != script_tag)
+    {
       unsigned char *buf;
       const char *lang_str = hb_language_to_string (*language);
       size_t len = strlen (lang_str);
       buf = (unsigned char *) malloc (len + 11);
-      if (unlikely (!buf)) {
+      if (unlikely (!buf))
+      {
 	*language = nullptr;
-      } else {
+      }
+      else
+      {
 	memcpy (buf, lang_str, len);
 	if (lang_str[0] != 'x' || lang_str[1] != '-') {
 	  buf[len++] = '-';
diff --git a/src/hb-ot-tag.h b/src/hb-ot-tag.h
index a4e8a49c2..f7a061c70 100644
--- a/src/hb-ot-tag.h
+++ b/src/hb-ot-tag.h
@@ -39,7 +39,17 @@ HB_BEGIN_DECLS
 #define HB_OT_TAG_DEFAULT_SCRIPT	HB_TAG ('D', 'F', 'L', 'T')
 #define HB_OT_TAG_DEFAULT_LANGUAGE	HB_TAG ('d', 'f', 'l', 't')
 
+/**
+ * HB_OT_MAX_TAGS_PER_SCRIPT:
+ *
+ * Since: REPLACEME
+ **/
 #define HB_OT_MAX_TAGS_PER_SCRIPT	3u
+/**
+ * HB_OT_MAX_TAGS_PER_LANGUAGE:
+ *
+ * Since: REPLACEME
+ **/
 #define HB_OT_MAX_TAGS_PER_LANGUAGE	3u
 
 HB_EXTERN void
diff --git a/src/hb-unicode.h b/src/hb-unicode.h
index 62b58803a..df0b91f01 100644
--- a/src/hb-unicode.h
+++ b/src/hb-unicode.h
@@ -44,7 +44,7 @@ HB_BEGIN_DECLS
  * HB_UNICODE_MAX
  *
  * Since: 1.9.0
- */
+ **/
 #define HB_UNICODE_MAX 0x10FFFFu