From 5b43eb5a4caadd1494a7402ff0bea893102556d7 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 22 Apr 2019 19:16:48 +0100 Subject: [PATCH 1/8] [Docs] Add GTK-Dod comments to hb-unicode. --- src/hb-unicode.cc | 118 +++++++++++------- src/hb-unicode.h | 307 ++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 339 insertions(+), 86 deletions(-) diff --git a/src/hb-unicode.cc b/src/hb-unicode.cc index 36070a7f1..9621a2256 100644 --- a/src/hb-unicode.cc +++ b/src/hb-unicode.cc @@ -40,11 +40,16 @@ * @include: hb.h * * Unicode functions are used to access Unicode character properties. - * Client can pass its own Unicode functions to HarfBuzz, or access - * the built-in Unicode functions that come with HarfBuzz. + * With these functions, client programs can query various properties from + * the Unicode Character Database for any code point, such as General + * Category (gc), Script (sc), Canonical Combining Class (ccc), etc. * - * With the Unicode functions, one can query variour Unicode character - * properties, such as General Category, Script, Combining Class, etc. + * Client programs can optionally pass in their own Unicode functions + * that implement the same queries. The set of functions available is + * defined by the virtual methods in #hb_unicode_funcs_t. + * + * HarfBuzz provides built-in default functions for each method in + * #hb_unicode_funcs_t. **/ @@ -133,6 +138,11 @@ hb_unicode_decompose_compatibility_nil (hb_unicode_funcs_t *ufuncs HB_UNUSED #include "hb-icu.h" #endif +/** + * + * + * + **/ hb_unicode_funcs_t * hb_unicode_funcs_get_default () { @@ -155,11 +165,11 @@ hb_unicode_funcs_get_default () /** * hb_unicode_funcs_create: (Xconstructor) - * @parent: (nullable): + * @parent: (nullable): Parent Unicode-functions structure * + * Creates a new #hb_unicode_funcs_t structure of Unicode functions. * - * - * Return value: (transfer full): + * Return value: (transfer full): The Unicode-functions structure * * Since: 0.9.2 **/ @@ -203,9 +213,9 @@ DEFINE_NULL_INSTANCE (hb_unicode_funcs_t) = /** * hb_unicode_funcs_get_empty: * + * Fetches the singleton empty Unicode-functions structure. * - * - * Return value: (transfer full): + * Return value: (transfer full): The empty Unicode-functions structure * * Since: 0.9.2 **/ @@ -217,11 +227,11 @@ hb_unicode_funcs_get_empty () /** * hb_unicode_funcs_reference: (skip) - * @ufuncs: Unicode functions. + * @ufuncs: The Unicode-functions structure * + * Increases the reference count on a Unicode-functions structure. * - * - * Return value: (transfer full): + * Return value: (transfer full): The Unicode-functions structure * * Since: 0.9.2 **/ @@ -233,9 +243,11 @@ hb_unicode_funcs_reference (hb_unicode_funcs_t *ufuncs) /** * hb_unicode_funcs_destroy: (skip) - * @ufuncs: Unicode functions. - * + * @ufuncs: The Unicode-functions structure * + * Decreases the reference count on a Unicode-functions structure. When + * the reference count reaches zero, the Unicode-functions structure is + * destroyed, freeing all memory. * * Since: 0.9.2 **/ @@ -256,15 +268,15 @@ hb_unicode_funcs_destroy (hb_unicode_funcs_t *ufuncs) /** * hb_unicode_funcs_set_user_data: (skip) - * @ufuncs: Unicode functions. - * @key: - * @data: - * @destroy: - * @replace: + * @ufuncs: The Unicode-functions structure + * @key: The user-data key + * @data: A pointer to the user data + * @destroy: A callback to call when @data is not needed anymore + * @replace: Whether to replace an existing data with the same key * + * Attaches a user-data key/data pair to the specified Unicode-functions structure. * - * - * Return value: + * Return value: %true if success, false otherwise * * Since: 0.9.2 **/ @@ -280,12 +292,13 @@ hb_unicode_funcs_set_user_data (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_funcs_get_user_data: (skip) - * @ufuncs: Unicode functions. - * @key: + * @ufuncs: The Unicode-functions structure + * @key: The user-data key to query * + * Fetches the user-data associated with the specified key, + * attached to the specified Unicode-functions structure. * - * - * Return value: (transfer none): + * Return value: (transfer none): A pointer to the user data * * Since: 0.9.2 **/ @@ -299,9 +312,10 @@ hb_unicode_funcs_get_user_data (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_funcs_make_immutable: - * @ufuncs: Unicode functions. - * + * @ufuncs: The Unicode-functions structure * + * Makes the specified Unicode-functions structure + * immutable. * * Since: 0.9.2 **/ @@ -316,11 +330,12 @@ hb_unicode_funcs_make_immutable (hb_unicode_funcs_t *ufuncs) /** * hb_unicode_funcs_is_immutable: - * @ufuncs: Unicode functions. + * @ufuncs: The Unicode-functions structure * + * Tests whether the specified Unicode-functions structure + * is immutable. * - * - * Return value: + * Return value: %true if @ufuncs is immutable, false otherwise * * Since: 0.9.2 **/ @@ -332,11 +347,12 @@ hb_unicode_funcs_is_immutable (hb_unicode_funcs_t *ufuncs) /** * hb_unicode_funcs_get_parent: - * @ufuncs: Unicode functions. + * @ufuncs: The Unicode-functions structure * + * Fetches the parent of the Unicode-functions structure + * @ufuncs. * - * - * Return value: + * Return value: The parent Unicode-functions structure * * Since: 0.9.2 **/ @@ -389,14 +405,18 @@ HB_UNICODE_FUNCS_IMPLEMENT_CALLBACKS_SIMPLE /** * hb_unicode_compose: - * @ufuncs: Unicode functions. - * @a: - * @b: - * @ab: (out): + * @ufuncs: The Unicode-functions structure + * @a: The first Unicode code point to compose + * @b: The second Unicode code point to compose + * @ab: (out): The composition of @a, @b * + * Fetches the composition of a sequence of two Unicode + * code points. * + * Calls the composition function of the specified + * Unicode-functions structure @ufuncs. * - * Return value: + * Return value: %true if @a and @b composed, false otherwise * * Since: 0.9.2 **/ @@ -411,14 +431,17 @@ hb_unicode_compose (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_decompose: - * @ufuncs: Unicode functions. - * @ab: - * @a: (out): - * @b: (out): + * @ufuncs: The Unicode-functions structure + * @ab: Unicode code point to decompose + * @a: (out): The first code point of the decomposition of @ab + * @b: (out): The second code point of the decomposition of @ab * + * Fetches the decomposition of a Unicode code point. * + * Calls the decomposition function of the specified + * Unicode-functions structure @ufuncs. * - * Return value: + * Return value: %true if @ab was decomposed, false otherwise * * Since: 0.9.2 **/ @@ -434,11 +457,12 @@ hb_unicode_decompose (hb_unicode_funcs_t *ufuncs, #ifndef HB_DISABLE_DEPRECATED /** * hb_unicode_decompose_compatibility: - * @ufuncs: Unicode functions. - * @u: - * @decomposed: (out): - * + * @ufuncs: The Unicode-functions structure + * @u: Code point to decompose + * @decomposed: (out): Compatibility decomposition of @u * + * Fetches the compatibility decomposition of a Unicode + * code point. Deprecated. * * Return value: * diff --git a/src/hb-unicode.h b/src/hb-unicode.h index 61b1b0ba1..2353f0fbf 100644 --- a/src/hb-unicode.h +++ b/src/hb-unicode.h @@ -48,7 +48,42 @@ HB_BEGIN_DECLS #define HB_UNICODE_MAX 0x10FFFFu -/* hb_unicode_general_category_t */ +/** + * hb_unicode_general_category_t: + * @HB_UNICODE_GENERAL_CATEGORY_CONTROL: (Cc) + * @HB_UNICODE_GENERAL_CATEGORY_FORMAT: (Cf) + * @HB_UNICODE_GENERAL_CATEGORY_UNASSIGNED: (Cn) + * @HB_UNICODE_GENERAL_CATEGORY_PRIVATE_USE: (Co) + * @HB_UNICODE_GENERAL_CATEGORY_SURROGATE: (Cs) + * @HB_UNICODE_GENERAL_CATEGORY_LOWERCASE_LETTER: (Ll) + * @HB_UNICODE_GENERAL_CATEGORY_MODIFIER_LETTER: (Lm) + * @HB_UNICODE_GENERAL_CATEGORY_OTHER_LETTER: (Lo) + * @HB_UNICODE_GENERAL_CATEGORY_TITLECASE_LETTER: (Lt) + * @HB_UNICODE_GENERAL_CATEGORY_UPPERCASE_LETTER: (Lu) + * @HB_UNICODE_GENERAL_CATEGORY_SPACING_MARK: (Mc) + * @HB_UNICODE_GENERAL_CATEGORY_ENCLOSING_MARK: (Me) + * @HB_UNICODE_GENERAL_CATEGORY_NON_SPACING_MARK: (Mn) + * @HB_UNICODE_GENERAL_CATEGORY_DECIMAL_NUMBER: (Nd) + * @HB_UNICODE_GENERAL_CATEGORY_LETTER_NUMBER: (Nl) + * @HB_UNICODE_GENERAL_CATEGORY_OTHER_NUMBER: (No) + * @HB_UNICODE_GENERAL_CATEGORY_CONNECT_PUNCTUATION: (Pc) + * @HB_UNICODE_GENERAL_CATEGORY_DASH_PUNCTUATION: (Pd) + * @HB_UNICODE_GENERAL_CATEGORY_CLOSE_PUNCTUATION: (Pe) + * @HB_UNICODE_GENERAL_CATEGORY_FINAL_PUNCTUATION: (Pf) + * @HB_UNICODE_GENERAL_CATEGORY_INITIAL_PUNCTUATION: (Pi) + * @HB_UNICODE_GENERAL_CATEGORY_OTHER_PUNCTUATION: (Po) + * @HB_UNICODE_GENERAL_CATEGORY_OPEN_PUNCTUATION: (Ps) + * @HB_UNICODE_GENERAL_CATEGORY_CURRENCY_SYMBOL: (Sc) + * @HB_UNICODE_GENERAL_CATEGORY_MODIFIER_SYMBOL: (Sk) + * @HB_UNICODE_GENERAL_CATEGORY_MATH_SYMBOL: (Sm) + * @HB_UNICODE_GENERAL_CATEGORY_OTHER_SYMBOL: (So) + * @HB_UNICODE_GENERAL_CATEGORY_LINE_SEPARATOR: (Zl) + * @HB_UNICODE_GENERAL_CATEGORY_PARAGRAPH_SEPARATOR: (Zp) + * @HB_UNICODE_GENERAL_CATEGORY_SPACE_SEPARATOR: (Zs) + * + * Data type for the "General_Category" (gc) property from + * the Unicode Character Database. + **/ /* Unicode Character Database property: General_Category (gc) */ typedef enum @@ -85,13 +120,72 @@ typedef enum HB_UNICODE_GENERAL_CATEGORY_SPACE_SEPARATOR /* Zs */ } hb_unicode_general_category_t; -/* hb_unicode_combining_class_t */ - -/* Note: newer versions of Unicode may add new values. Clients should be ready to handle - * any value in the 0..254 range being returned from hb_unicode_combining_class(). - */ - -/* Unicode Character Database property: Canonical_Combining_Class (ccc) */ +/** + * hb_unicode_combining_class_t: + * @HB_UNICODE_COMBINING_CLASS_NOT_REORDERED + * @HB_UNICODE_COMBINING_CLASS_OVERLAY + * @HB_UNICODE_COMBINING_CLASS_NUKTA + * @HB_UNICODE_COMBINING_CLASS_KANA_VOICING + * @HB_UNICODE_COMBINING_CLASS_VIRAMA + * @HB_UNICODE_COMBINING_CLASS_CCC11: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC12: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC13: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC14: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC15: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC16: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC17: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC18: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC19: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC20: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC21: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC22: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC23: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC24: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC25: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC26: (Hebrew) + * @HB_UNICODE_COMBINING_CLASS_CCC28: (Arabic) + * @HB_UNICODE_COMBINING_CLASS_CCC29: (Arabic) + * @HB_UNICODE_COMBINING_CLASS_CCC30: (Arabic) + * @HB_UNICODE_COMBINING_CLASS_CCC31: (Arabic) + * @HB_UNICODE_COMBINING_CLASS_CCC32: (Arabic) + * @HB_UNICODE_COMBINING_CLASS_CCC33: (Arabic) + * @HB_UNICODE_COMBINING_CLASS_CCC34: (Arabic) + * @HB_UNICODE_COMBINING_CLASS_CCC35: (Arabic) + * @HB_UNICODE_COMBINING_CLASS_CCC36: (Syriac) + * @HB_UNICODE_COMBINING_CLASS_CCC84: (Telugu) + * @HB_UNICODE_COMBINING_CLASS_CCC91: (Telugu) + * @HB_UNICODE_COMBINING_CLASS_CCC103: (Thai) + * @HB_UNICODE_COMBINING_CLASS_CCC107: (Thai) + * @HB_UNICODE_COMBINING_CLASS_CCC118: (Lao) + * @HB_UNICODE_COMBINING_CLASS_CCC122: (Lao) + * @HB_UNICODE_COMBINING_CLASS_CCC129: (Tibetan) + * @HB_UNICODE_COMBINING_CLASS_CCC130: (Tibetan) + * @HB_UNICODE_COMBINING_CLASS_CCC133: (Tibetan) + * @HB_UNICODE_COMBINING_CLASS_ATTACHED_BELOW_LEFT + * @HB_UNICODE_COMBINING_CLASS_ATTACHED_BELOW + * @HB_UNICODE_COMBINING_CLASS_ATTACHED_ABOVE + * @HB_UNICODE_COMBINING_CLASS_ATTACHED_ABOVE_RIGHT + * @HB_UNICODE_COMBINING_CLASS_BELOW_LEFT + * @HB_UNICODE_COMBINING_CLASS_BELOW + * @HB_UNICODE_COMBINING_CLASS_BELOW_RIGHT + * @HB_UNICODE_COMBINING_CLASS_LEFT + * @HB_UNICODE_COMBINING_CLASS_RIGHT + * @HB_UNICODE_COMBINING_CLASS_ABOVE_LEFT + * @HB_UNICODE_COMBINING_CLASS_ABOVE + * @HB_UNICODE_COMBINING_CLASS_ABOVE_RIGHT + * @HB_UNICODE_COMBINING_CLASS_DOUBLE_BELOW + * @HB_UNICODE_COMBINING_CLASS_DOUBLE_ABOVE + * @HB_UNICODE_COMBINING_CLASS_IOTA_SUBSCRIPT + * @HB_UNICODE_COMBINING_CLASS_INVALID: 255 + * + * Data type for the Canonical_Combining_Class (ccc) property + * from the Unicode Character Database. + * + * Note: newer versions of Unicode may add new values. + * Client programs should be ready to handle any value in the 0..254 range + * being returned from hb_unicode_combining_class(). + * + **/ typedef enum { HB_UNICODE_COMBINING_CLASS_NOT_REORDERED = 0, @@ -176,6 +270,18 @@ typedef enum * hb_unicode_funcs_t */ +/** + * hb_unicode_funcs_t: + * + * Data type containing a set of virtual methods used for + * accessing various Unicode character properties. + * + * HarfBuzz provides a default function for each of the + * methods in #hb_unicode_funcs_t. Client programs can implement + * their own replacements for the individual Unicode functions, as + * needed, and replace the default by calling the setter for a + * method. + **/ typedef struct hb_unicode_funcs_t hb_unicode_funcs_t; @@ -227,40 +333,107 @@ hb_unicode_funcs_get_parent (hb_unicode_funcs_t *ufuncs); /* typedefs */ +/** + * hb_unicode_combining_class_func_t: + * + * A virtual method for the #hb_unicode_funcs_t structure. + * + * This method should retrieve the Canonical Combining Class (ccc) + * property for a specified Unicode code point. + * + **/ typedef hb_unicode_combining_class_t (*hb_unicode_combining_class_func_t) (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode, void *user_data); + +/** + * hb_unicode_general_category_func_t: + * + * A virtual method for the #hb_unicode_funcs_t structure. + * + * This method should retrieve the General Category property for + * a specified Unicode code point. + * + **/ typedef hb_unicode_general_category_t (*hb_unicode_general_category_func_t) (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode, void *user_data); + +/** + * hb_unicode_mirroring_func_t: + * + * A virtual method for the #hb_unicode_funcs_t structure. + * + * This method should retrieve the Bi-Directional Mirroring Glyph + * code point for a specified Unicode code point. + * + * Note: If a code point does not have a specified + * Bi-Directional Mirroring Glyph defined, the method should + * return the original code point. + * + **/ typedef hb_codepoint_t (*hb_unicode_mirroring_func_t) (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode, void *user_data); + +/** + * hb_unicode_script_func_t: + * + * A virtual method for the #hb_unicode_funcs_t structure. + * + * This method should retrieve the Script property for a + * specified Unicode code point. + * + **/ typedef hb_script_t (*hb_unicode_script_func_t) (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode, void *user_data); +/** + * hb_unicode_compose_func_t: + * + * A virtual method for the #hb_unicode_funcs_t structure. + * + * This method should compose a sequence of two input Unicode code + * points by canonical equivalence, returning the composed code + * point in a #hb_codepoint_t output parameter (if successful). + * The method must return an #hb_bool_t indicating the success + * of the composition. + * + **/ typedef hb_bool_t (*hb_unicode_compose_func_t) (hb_unicode_funcs_t *ufuncs, hb_codepoint_t a, hb_codepoint_t b, hb_codepoint_t *ab, void *user_data); + +/** + * hb_unicode_decompose_func_t: + * + * A virtual method for the #hb_unicode_funcs_t structure. + * + * This method should decompose an input Unicode code point, + * returning the two decomposed code points in #hb_codepoint_t + * output parameters (if successful). The method must return an + * #hb_bool_t indicating the success of the composition. + * + **/ typedef hb_bool_t (*hb_unicode_decompose_func_t) (hb_unicode_funcs_t *ufuncs, hb_codepoint_t ab, hb_codepoint_t *a, hb_codepoint_t *b, void *user_data); -/* setters */ +/* func setters */ /** * hb_unicode_funcs_set_combining_class_func: - * @ufuncs: a Unicode function structure - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ufuncs: A Unicode-functions structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_unicode_combining_class_func_t. * * Since: 0.9.2 **/ @@ -271,12 +444,12 @@ hb_unicode_funcs_set_combining_class_func (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_funcs_set_general_category_func: - * @ufuncs: a Unicode function structure - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ufuncs: A Unicode-functions structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_unicode_general_category_func_t. * * Since: 0.9.2 **/ @@ -287,12 +460,12 @@ hb_unicode_funcs_set_general_category_func (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_funcs_set_mirroring_func: - * @ufuncs: a Unicode function structure - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ufuncs: A Unicode-functions structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_unicode_mirroring_func_t. * * Since: 0.9.2 **/ @@ -303,12 +476,12 @@ hb_unicode_funcs_set_mirroring_func (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_funcs_set_script_func: - * @ufuncs: a Unicode function structure - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ufuncs: A Unicode-functions structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_unicode_script_func_t. * * Since: 0.9.2 **/ @@ -319,12 +492,12 @@ hb_unicode_funcs_set_script_func (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_funcs_set_compose_func: - * @ufuncs: a Unicode function structure - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ufuncs: A Unicode-functions structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_unicode_compose_func_t. * * Since: 0.9.2 **/ @@ -335,12 +508,12 @@ hb_unicode_funcs_set_compose_func (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_funcs_set_decompose_func: - * @ufuncs: a Unicode function structure - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ufuncs: A Unicode-functions structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_unicode_decompose_func_t. * * Since: 0.9.2 **/ @@ -353,6 +526,13 @@ hb_unicode_funcs_set_decompose_func (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_combining_class: + * @ufuncs: The Unicode-functions structure + * @unicode: The code point to query + * + * Retrieves the Canonical Combining Class (ccc) property + * of code point @unicode. + * + * Return value: The #hb_unicode_combining_class_t of @unicode * * Since: 0.9.2 **/ @@ -362,6 +542,13 @@ hb_unicode_combining_class (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_general_category: + * @ufuncs: The Unicode-functions structure + * @unicode: The code point to query + * + * Retrieves the General Category (gc) property + * of code point @unicode. + * + * Return value: The #hb_unicode_general_category_t of @unicode * * Since: 0.9.2 **/ @@ -371,6 +558,13 @@ hb_unicode_general_category (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_mirroring: + * @ufuncs: The Unicode-functions structure + * @unicode: The code point to query + * + * Retrieves the Bi-directional Mirroring Glyph code + * point defined for code point @unicode. + * + * Return value: The #hb_codepoint_t of the Mirroring Glyph for @unicode * * Since: 0.9.2 **/ @@ -380,6 +574,13 @@ hb_unicode_mirroring (hb_unicode_funcs_t *ufuncs, /** * hb_unicode_script: + * @ufuncs: The Unicode-functions structure + * @unicode: The code point to query + * + * Retrieves the #hb_script_t script to which code + * point @unicode belongs. + * + * Return value: The #hb_script_t of @unicode * * Since: 0.9.2 **/ @@ -387,12 +588,40 @@ HB_EXTERN hb_script_t hb_unicode_script (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode); +/** + * hb_unicode_compose: + * @ufuncs: The Unicode-functions structure + * @a: The first code point to compose + * @b: The second code point to compose + * @ab: (out): The composed code point + * + * Composes the code point sequence @a,@b by canonical equivalence into + * code point @ab. + * + * Return value: True is @a,@b composed, false otherwise + * + * Since: 0.9.2 + **/ HB_EXTERN hb_bool_t hb_unicode_compose (hb_unicode_funcs_t *ufuncs, hb_codepoint_t a, hb_codepoint_t b, hb_codepoint_t *ab); +/** + * hb_unicode_decompose: + * @ufuncs: The Unicode-functions structure + * @ab: The code point to decompose + * @a: (out): The first decomposed code point + * @b: (out): The second decomposed code point + * + * Decomposes code point @ab by canonical equivalence, into code points + * @a and @b. + * + * Return value: True if @ab decomposed, false otherwise + * + * Since: 0.9.2 + **/ HB_EXTERN hb_bool_t hb_unicode_decompose (hb_unicode_funcs_t *ufuncs, hb_codepoint_t ab, From 88cdea60e07187139419c0dc2cc76eb7a3c81a6e Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 22 Apr 2019 19:17:40 +0100 Subject: [PATCH 2/8] [Docs] Add GTK-Doc comments to hb-shape-plan. --- src/hb-shape-plan.cc | 140 +++++++++++++++++++++++++++++-------------- src/hb-shape-plan.h | 14 +++++ 2 files changed, 109 insertions(+), 45 deletions(-) diff --git a/src/hb-shape-plan.cc b/src/hb-shape-plan.cc index a5a101d0f..2e03003dd 100644 --- a/src/hb-shape-plan.cc +++ b/src/hb-shape-plan.cc @@ -37,10 +37,17 @@ * @short_description: Object representing a shaping plan * @include: hb.h * - * Shape plans are not used for shaping directly, but can be access to query - * certain information about how shaping will perform given a set of input - * parameters (script, language, direction, features, etc.) - * Most client would not need to deal with shape plans directly. + * Shape plans are an internal mechanism. Each plan contains state + * describing how HarfBuzz will shape a particular text segment, based on + * the combination of segment properties and the capabilities in the + * font face in use. + * + * Shape plans are not used for shaping directly, but can be queried to + * access certain information about how shaping will perform, given a set + * of specific input parameters (script, language, direction, features, + * etc.). + * + * Most client programs will not need to deal with shape plans directly. **/ @@ -164,15 +171,16 @@ hb_shape_plan_key_t::equal (const hb_shape_plan_key_t *other) /** * hb_shape_plan_create: (Xconstructor) - * @face: - * @props: - * @user_features: (array length=num_user_features): - * @num_user_features: - * @shaper_list: (array zero-terminated=1): + * @face: #hb_face_t to use + * @props: The #hb_segment_properties_t of the segment + * @user_features: (array length=num_user_features): The list of user-selected features + * @num_user_features: The number of user-selected features + * @shaper_list: (array zero-terminated=1): List of shapers to try * + * Constructs a shaping plan for a combination of @face, @user_features, @props, + * and @shaper_list. * - * - * Return value: (transfer full): + * Return value: (transfer full): The shaping plan * * Since: 0.9.7 **/ @@ -189,6 +197,24 @@ hb_shape_plan_create (hb_face_t *face, shaper_list); } +/** + * hb_shape_plan_create2: (Xconstructor) + * @face: #hb_face_t to use + * @props: The #hb_segment_properties_t of the segment + * @user_features: (array length=num_user_features): The list of user-selected features + * @num_user_features: The number of user-selected features + * @coords: (array length=num_coords): The list of variation-space coordinates + * @num_coords: The number of variation-space coordinates + * @shaper_list: (array zero-terminated=1): List of shapers to try + * + * The variable-font version of #hb_shape_plan_create. + * Constructs a shaping plan for a combination of @face, @user_features, @props, + * and @shaper_list, plus the variation-space coordinates @coords. + * + * Return value: (transfer full): The shaping plan + * + * Since: 1.4.0 + **/ hb_shape_plan_t * hb_shape_plan_create2 (hb_face_t *face, const hb_segment_properties_t *props, @@ -248,9 +274,9 @@ bail: /** * hb_shape_plan_get_empty: * + * Fetches the singleton empty shaping plan. * - * - * Return value: (transfer full): + * Return value: (transfer full): The empty shaping plan * * Since: 0.9.7 **/ @@ -262,11 +288,11 @@ hb_shape_plan_get_empty () /** * hb_shape_plan_reference: (skip) - * @shape_plan: a shape plan. + * @shape_plan: A shaping plan * + * Increases the reference count on the given shaping plan. * - * - * Return value: (transfer full): + * Return value: (transfer full): @shape_plan * * Since: 0.9.7 **/ @@ -278,9 +304,11 @@ hb_shape_plan_reference (hb_shape_plan_t *shape_plan) /** * hb_shape_plan_destroy: (skip) - * @shape_plan: a shape plan. - * + * @shape_plan: A shaping plan * + * Decreases the reference count on the given shaping plan. When the + * reference count reaches zero, the shaping plan is destroyed, + * freeing all memory. * * Since: 0.9.7 **/ @@ -298,13 +326,13 @@ hb_shape_plan_destroy (hb_shape_plan_t *shape_plan) /** * hb_shape_plan_set_user_data: (skip) - * @shape_plan: a shape plan. - * @key: - * @data: - * @destroy: - * @replace: - * + * @shape_plan: A shaping plan + * @key: The user-data key to set + * @data: A pointer to the user data + * @destroy: A callback to call when @data is not needed anymore + * @replace: Whether to replace an existing data with the same key * + * Attaches a user-data key/data pair to the given shaping plan. * * Return value: * @@ -322,12 +350,13 @@ hb_shape_plan_set_user_data (hb_shape_plan_t *shape_plan, /** * hb_shape_plan_get_user_data: (skip) - * @shape_plan: a shape plan. - * @key: + * @shape_plan: A shaping plan + * @key: The user-data key to query * + * Fetches the user data associated with the specified key, + * attached to the specified shaping plan. * - * - * Return value: (transfer none): + * Return value: (transfer none): A pointer to the user data * * Since: 0.9.7 **/ @@ -340,11 +369,11 @@ hb_shape_plan_get_user_data (hb_shape_plan_t *shape_plan, /** * hb_shape_plan_get_shaper: - * @shape_plan: a shape plan. + * @shape_plan: A shaping plan * + * Fetches the shaper from a given shaping plan. * - * - * Return value: (transfer none): + * Return value: (transfer none): The shaper * * Since: 0.9.7 **/ @@ -400,15 +429,16 @@ _hb_shape_plan_execute_internal (hb_shape_plan_t *shape_plan, } /** * hb_shape_plan_execute: - * @shape_plan: a shape plan. - * @font: a font. - * @buffer: a buffer. - * @features: (array length=num_features): - * @num_features: + * @shape_plan: A shaping plan + * @font: The #hb_font_t to use + * @buffer: The #hb_buffer_t to work upon + * @features: (array length=num_features): Features to enable + * @num_features: The number of features to enable * + * Executes the given shaping plan on the specified buffer, using + * the given @font and @features. * - * - * Return value: + * Return value: * * Since: 0.9.7 **/ @@ -435,15 +465,16 @@ hb_shape_plan_execute (hb_shape_plan_t *shape_plan, /** * hb_shape_plan_create_cached: - * @face: - * @props: - * @user_features: (array length=num_user_features): - * @num_user_features: - * @shaper_list: (array zero-terminated=1): + * @face: #hb_face_t to use + * @props: The #hb_segment_properties_t of the segment + * @user_features: (array length=num_user_features): The list of user-selected features + * @num_user_features: The number of user-selected features + * @shaper_list: (array zero-terminated=1): List of shapers to try * + * Creates a cached shaping plan suitable for reuse, for a combination + * of @face, @user_features, @props, and @shaper_list. * - * - * Return value: (transfer full): + * Return value: (transfer full): The shaping plan * * Since: 0.9.7 **/ @@ -460,6 +491,25 @@ hb_shape_plan_create_cached (hb_face_t *face, shaper_list); } +/** + * hb_shape_plan_create_cached2: + * @face: #hb_face_t to use + * @props: The #hb_segment_properties_t of the segment + * @user_features: (array length=num_user_features): The list of user-selected features + * @num_user_features: The number of user-selected features + * @coords: (array length=num_coords): The list of variation-space coordinates + * @num_coords: The number of variation-space coordinates + * @shaper_list: (array zero-terminated=1): List of shapers to try + * + * The variable-font version of #hb_shape_plan_create_cached. + * Creates a cached shaping plan suitable for reuse, for a combination + * of @face, @user_features, @props, and @shaper_list, plus the + * variation-space coordinates @coords. + * + * Return value: (transfer full): The shaping plan + * + * Since: 1.4.0 + **/ hb_shape_plan_t * hb_shape_plan_create_cached2 (hb_face_t *face, const hb_segment_properties_t *props, diff --git a/src/hb-shape-plan.h b/src/hb-shape-plan.h index b62ae7ca3..336524ee2 100644 --- a/src/hb-shape-plan.h +++ b/src/hb-shape-plan.h @@ -36,6 +36,20 @@ HB_BEGIN_DECLS +/** + * hb_shape_plan_t: + * + * Data type for holding a shaping plan. + * + * Shape plans contain information about how HarfBuzz will shape a + * particular text segment, based on the segment's properties and the + * capabilities in the font face in use. + * + * Shape plans can be queried about how shaping will perform, given a set + * of specific input parameters (script, language, direction, features, + * etc.). + * + **/ typedef struct hb_shape_plan_t hb_shape_plan_t; HB_EXTERN hb_shape_plan_t * From 3e72febde020649cb7c213f71675804e09fb1926 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 22 Apr 2019 19:21:27 +0100 Subject: [PATCH 3/8] [Docs] Add GTK-Doc comments for hb-face. --- src/hb-face.cc | 174 +++++++++++++++++++++++++++++-------------------- src/hb-face.h | 8 +++ 2 files changed, 110 insertions(+), 72 deletions(-) diff --git a/src/hb-face.cc b/src/hb-face.cc index 7bde50df5..bf11df203 100644 --- a/src/hb-face.cc +++ b/src/hb-face.cc @@ -41,8 +41,10 @@ * @short_description: Font face objects * @include: hb.h * - * Font face is objects represent a single face in a font family. - * More exactly, a font face represents a single face in a binary font file. + * A font face is an object that represents a single face from within a + * font family. + * + * More precisely, a font face represents a single face in a binary font file. * Font faces are typically built from a binary blob and a face index. * Font faces are used to create fonts. **/ @@ -52,7 +54,7 @@ * hb_face_count: * @blob: a blob. * - * Get number of faces in a blob. + * Fetches the number of faces in a blob. * * Return value: Number of faces in @blob * @@ -96,11 +98,16 @@ DEFINE_NULL_INSTANCE (hb_face_t) = /** * hb_face_create_for_tables: - * @reference_table_func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @reference_table_func: (closure user_data) (destroy destroy) (scope notified): Table-referencing function + * @user_data: A pointer to the user data + * @destroy: (optional): A callback to call when @data is not needed anymore * + * Variant of hb_face_create(), built for those cases where + * client programs are primarily concerned with querying the + * font tables, rather than with full shaping. + * + * Creates a new face object from the specified @user_data and @reference_table_func, + * with the @destroy callback. * * Return value: (transfer full) * @@ -182,12 +189,13 @@ _hb_face_for_data_reference_table (hb_face_t *face HB_UNUSED, hb_tag_t tag, void /** * hb_face_create: (Xconstructor) - * @blob: - * @index: + * @blob: #hb_blob_t to work upon + * @index: The index of the face within @blob * + * Constructs a new face object from the specified blob and + * a face index into that blob. * - * - * Return value: (transfer full): + * Return value: (transfer full): The new face object * * Since: 0.9.2 **/ @@ -222,9 +230,9 @@ hb_face_create (hb_blob_t *blob, /** * hb_face_get_empty: * + * Fetches the singleton empty face object. * - * - * Return value: (transfer full) + * Return value: (transfer full) The empty face object * * Since: 0.9.2 **/ @@ -237,11 +245,11 @@ hb_face_get_empty () /** * hb_face_reference: (skip) - * @face: a face. + * @face: A face object * + * Increases the reference count on a face object. * - * - * Return value: + * Return value: The @face object * * Since: 0.9.2 **/ @@ -253,9 +261,11 @@ hb_face_reference (hb_face_t *face) /** * hb_face_destroy: (skip) - * @face: a face. - * - * + * @face: A face object + * + * Decreases the reference count on a face object. When the + * reference count reaches zero, the face is destroyed, + * freeing all memory. * * Since: 0.9.2 **/ @@ -283,15 +293,15 @@ hb_face_destroy (hb_face_t *face) /** * hb_face_set_user_data: (skip) - * @face: a face. - * @key: - * @data: - * @destroy: - * @replace: + * @face: A face object + * @key: The user-data key to set + * @data: A pointer to the user data + * @destroy: (optional): A callback to call when @data is not needed anymore + * @replace: Whether to replace an existing data with the same key * + * Attaches a user-data key/data pair to the given face object. * - * - * Return value: + * Return value: %true if success, false otherwise * * Since: 0.9.2 **/ @@ -307,12 +317,13 @@ hb_face_set_user_data (hb_face_t *face, /** * hb_face_get_user_data: (skip) - * @face: a face. - * @key: + * @face: A face object + * @key: The user-data key to query * + * Fetches the user data associated with the specified key, + * attached to the specified face object. * - * - * Return value: (transfer none): + * Return value: (transfer none): A pointer to the user data * * Since: 0.9.2 **/ @@ -325,9 +336,9 @@ hb_face_get_user_data (const hb_face_t *face, /** * hb_face_make_immutable: - * @face: a face. - * + * @face: A face object * + * Makes the given face object immutable. * * Since: 0.9.2 **/ @@ -342,11 +353,11 @@ hb_face_make_immutable (hb_face_t *face) /** * hb_face_is_immutable: - * @face: a face. + * @face: A face object * + * Tests whether the given face object is immutable. * - * - * Return value: + * Return value: True is @face is immutable, false otherwise * * Since: 0.9.2 **/ @@ -359,12 +370,13 @@ hb_face_is_immutable (const hb_face_t *face) /** * hb_face_reference_table: - * @face: a face. - * @tag: + * @face: A face object + * @tag: The #hb_tag_t of the table to query * + * Fetches a reference to the specified table within + * the specified face. * - * - * Return value: (transfer full): + * Return value: (transfer full): A pointer to the @tag table within @face * * Since: 0.9.2 **/ @@ -380,11 +392,13 @@ hb_face_reference_table (const hb_face_t *face, /** * hb_face_reference_blob: - * @face: a face. + * @face: A face object * + * Fetches a pointer to the binary blob that contains the + * specified face. Can only be used on faces created with + * hb_face_builder_create(). * - * - * Return value: (transfer full): + * Return value: (transfer full): A pointer to the blob for @face * * Since: 0.9.2 **/ @@ -396,10 +410,13 @@ hb_face_reference_blob (hb_face_t *face) /** * hb_face_set_index: - * @face: a face. - * @index: + * @face: A face object + * @index: The index to assign * + * Assigns the specified face-index to @face. Fails if the + * face is immutable. * + * Note: face indices within a collection are zero-based. * * Since: 0.9.2 **/ @@ -415,11 +432,13 @@ hb_face_set_index (hb_face_t *face, /** * hb_face_get_index: - * @face: a face. + * @face: A face object * + * Fetches the face-index corresponding to the given face. * + * Note: face indices within a collection are zero-based. * - * Return value: + * Return value: The index of @face. * * Since: 0.9.2 **/ @@ -431,10 +450,10 @@ hb_face_get_index (const hb_face_t *face) /** * hb_face_set_upem: - * @face: a face. - * @upem: - * + * @face: A face object + * @upem: The units-per-em value to assign * + * Sets the units-per-em (upem) for a face object to the specified value. * * Since: 0.9.2 **/ @@ -450,11 +469,11 @@ hb_face_set_upem (hb_face_t *face, /** * hb_face_get_upem: - * @face: a face. + * @face: A face object * + * Fetches the units-per-em (upem) value of the specified face object. * - * - * Return value: + * Return value: The upem value of @face * * Since: 0.9.2 **/ @@ -466,10 +485,10 @@ hb_face_get_upem (const hb_face_t *face) /** * hb_face_set_glyph_count: - * @face: a face. - * @glyph_count: - * + * @face: A face object + * @glyph_count: The glyph-count value to assign * + * Sets the glyph count for a face object to the specified value. * * Since: 0.9.7 **/ @@ -485,11 +504,11 @@ hb_face_set_glyph_count (hb_face_t *face, /** * hb_face_get_glyph_count: - * @face: a face. + * @face: A face object * + * Fetches the glyph-count value of the specified face object. * - * - * Return value: + * Return value: The glyph-count value of @face * * Since: 0.9.7 **/ @@ -501,14 +520,16 @@ hb_face_get_glyph_count (const hb_face_t *face) /** * hb_face_get_table_tags: - * @face: a face. - * @start_offset: index of first tag to return. - * @table_count: input length of @table_tags array, output number of items written. - * @table_tags: array to write tags into. + * @face: A face object + * @start_offset: The index of first table tag to retrieve + * @table_count: (inout): Input = the maximum number of table tags to return; + * Output = the actual number of table tags returned (may be zero) + * @table_tags: (out) (array length=table_count): The array of table tags found * - * Retrieves table tags for a face, if possible. + * Fetches a list of all table tags for a face, if possible. The list returned will + * begin at the offset provided * - * Return value: total number of tables, or 0 if not possible to list. + * Return value: Total number of tables, or zero if it is not possible to list * * Since: 1.6.0 **/ @@ -542,8 +563,11 @@ hb_face_get_table_tags (const hb_face_t *face, #ifndef HB_NO_FACE_COLLECT_UNICODES /** * hb_face_collect_unicodes: - * @face: font face. - * @out: set to add Unicode characters covered by @face to. + * @face: A face object + * @out: The set to add Unicode characters to + * + * Collects all of the Unicode characters covered by @face and adds + * them to the #hb_set_t set @out. * * Since: 1.9.0 */ @@ -555,10 +579,11 @@ hb_face_collect_unicodes (hb_face_t *face, } /** * hb_face_collect_variation_selectors: - * @face: font face. - * @out: set to add Variation Selector characters covered by @face to. - * + * @face: A face object + * @out: The set to add Variation Selector characters to * + * Collects all Unicode "Variation Selector" characters covered by @face and adds + * them to the #hb_set_t set @out. * * Since: 1.9.0 */ @@ -570,10 +595,12 @@ hb_face_collect_variation_selectors (hb_face_t *face, } /** * hb_face_collect_variation_unicodes: - * @face: font face. - * @out: set to add Unicode characters for @variation_selector covered by @face to. - * + * @face: A face object + * @variation_selector: The Variation Selector to query + * @out: The set to add Unicode characters to * + * Collects all Unicode characters for @variation_selector covered by @face and adds + * them to the #hb_set_t set @out. * * Since: 1.9.0 */ @@ -708,6 +735,9 @@ hb_face_builder_create () /** * hb_face_builder_add_table: + * @face: A face object created with hb_face_builder_create() + * @tag: The #hb_tag_t of the table to add + * @blob: The blob containing the table data to add * * Add table for @tag with data provided by @blob to the face. @face must * be created using hb_face_builder_create(). diff --git a/src/hb-face.h b/src/hb-face.h index e8ff090d5..d88285a50 100644 --- a/src/hb-face.h +++ b/src/hb-face.h @@ -46,6 +46,14 @@ hb_face_count (hb_blob_t *blob); * hb_face_t */ +/** + * hb_face_t: + * @blob: A pointer to the #hb_blob_t that contains the binary blob of a font file + * @index: The index (zero-based) into the font file that points to the face + * + * Data type for holding font faces. + * + **/ typedef struct hb_face_t hb_face_t; HB_EXTERN hb_face_t * From eb10ef46aa1c62d6871f4780831e7ea326af10cf Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 22 Apr 2019 19:22:24 +0100 Subject: [PATCH 4/8] [Docs] Add GTK-Doc comments for hb-ot-font and hb-ot-shape. --- src/hb-ot-font.cc | 3 +++ src/hb-ot-shape.cc | 15 +++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/src/hb-ot-font.cc b/src/hb-ot-font.cc index a1dc88603..fae7b5b65 100644 --- a/src/hb-ot-font.cc +++ b/src/hb-ot-font.cc @@ -306,6 +306,9 @@ _hb_ot_get_font_funcs () /** * hb_ot_font_set_funcs: + * @font: #hb_font_t to work upon + * + * Sets the font functions to use when working with @font. * * Since: 0.9.28 **/ diff --git a/src/hb-ot-shape.cc b/src/hb-ot-shape.cc index fe0444987..010a6f2c8 100644 --- a/src/hb-ot-shape.cc +++ b/src/hb-ot-shape.cc @@ -1155,6 +1155,12 @@ _hb_ot_shape (hb_shape_plan_t *shape_plan, /** * hb_ot_shape_plan_collect_lookups: + * @shape_plan: #hb_shape_plan_t to query + * @table_tag: GSUB or GPOS + * @lookup_indexes: (out): The #hb_set_t set of lookups returned + * + * Computes the complete set of GSUB or GPOS lookups that are applicable + * under a given @shape_plan. * * Since: 0.9.7 **/ @@ -1189,6 +1195,15 @@ add_char (hb_font_t *font, /** * hb_ot_shape_glyphs_closure: + * @font: #hb_font_t to work upon + * @buffer: The input buffer to compute from + * @features: (array length=num_features): The features enabled on the buffer + * @num_features: The number of features enabled on the buffer + * @glyphs: (out): The #hb_set_t set of glyphs comprising the transitive closure of the query + * + * Computes the transitive closure of glyphs needed for a specified + * input buffer under the given font and feature list. The closure is + * computed as a set, not as a list. * * Since: 0.9.2 **/ From 70331ca4850427b2c5b235ab46f6b5fb6f7036f6 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 22 Apr 2019 19:25:42 +0100 Subject: [PATCH 5/8] [Docs] Minor update GTK-Doc comments in hb-ot-layout. --- src/hb-ot-layout.cc | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index 46408bb9d..7918f86dd 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -76,7 +76,7 @@ * Tests whether a face includes any kerning data in the 'kern' table. * Does NOT test for kerning lookups in the GPOS table. * - * Return value: true if data found, false otherwise + * Return value: %true if data found, false otherwise * **/ bool @@ -92,7 +92,7 @@ hb_ot_layout_has_kerning (hb_face_t *face) * Tests whether a face includes any state-machine kerning in the 'kern' table. * Does NOT examine the GPOS table. * - * Return value: true if data found, false otherwise + * Return value: %true if data found, false otherwise * **/ bool @@ -112,7 +112,7 @@ hb_ot_layout_has_machine_kerning (hb_face_t *face) * * Does NOT examine the GPOS table. * - * Return value: true is data found, false otherwise + * Return value: %true is data found, false otherwise * **/ bool @@ -268,7 +268,7 @@ _hb_ot_layout_set_glyph_props (hb_font_t *font, * * Tests whether a face has any glyph classes defined in its GDEF table. * - * Return value: true if data found, false otherwise + * Return value: %true if data found, false otherwise * **/ hb_bool_t @@ -444,7 +444,7 @@ hb_ot_layout_table_get_script_tags (hb_face_t *face, * Fetches the index if a given script tag in the specified face's GSUB table * or GPOS table. * - * Return value: true if the script is found, false otherwise + * Return value: %true if the script is found, false otherwise * **/ hb_bool_t @@ -598,7 +598,7 @@ hb_ot_layout_table_get_feature_tags (hb_face_t *face, * Fetches the index for a given feature tag in the specified face's GSUB table * or GPOS table. * - * Return value: true if the feature is found, false otherwise + * Return value: %true if the feature is found, false otherwise **/ bool hb_ot_layout_table_find_feature (hb_face_t *face, @@ -663,7 +663,7 @@ hb_ot_layout_script_get_language_tags (hb_face_t *face, * Fetches the index of a given language tag in the specified face's GSUB table * or GPOS table, underneath the specified script tag. * - * Return value: true if the language tag is found, false otherwise + * Return value: %true if the language tag is found, false otherwise * * Since: ?? * Deprecated: ?? @@ -697,7 +697,7 @@ hb_ot_layout_script_find_language (hb_face_t *face, * Fetches the index of a given language tag in the specified face's GSUB table * or GPOS table, underneath the specified script index. * - * Return value: true if the language tag is found, false otherwise + * Return value: %true if the language tag is found, false otherwise * * Since: 2.0.0 **/ @@ -739,7 +739,7 @@ hb_ot_layout_script_select_language (hb_face_t *face, * Fetches the index of a requested feature in the given face's GSUB or GPOS table, * underneath the specified script and language. * - * Return value: true if the feature is found, false otherwise + * Return value: %true if the feature is found, false otherwise * **/ hb_bool_t @@ -770,7 +770,7 @@ hb_ot_layout_language_get_required_feature_index (hb_face_t *face, * Fetches the tag of a requested feature index in the given face's GSUB or GPOS table, * underneath the specified script and language. * - * Return value: true if the feature is found, false otherwise + * Return value: %true if the feature is found, false otherwise * * Since: 0.9.30 **/ @@ -877,7 +877,7 @@ hb_ot_layout_language_get_feature_tags (hb_face_t *face, * Fetches the index of a given feature tag in the specified face's GSUB table * or GPOS table, underneath the specified script and language. * - * Return value: true if the feature is found, false otherwise + * Return value: %true if the feature is found, false otherwise * **/ hb_bool_t @@ -1196,7 +1196,7 @@ hb_ot_layout_collect_lookups (hb_face_t *face, * @glyphs_before: (out): Array of glyphs preceding the substitution range * @glyphs_input: (out): Array of input glyphs that would be substituted by the lookup * @glyphs_after: (out): Array of glyphs following the substitution range - * @glyphs_output: (out): Array of glyphs that would be the substitued output of the lookup + * @glyphs_output: (out): Array of glyphs that would be the substituted output of the lookup * * Fetches a list of all glyphs affected by the specified lookup in the * specified face's GSUB table or GPOS table. @@ -1245,7 +1245,7 @@ hb_ot_layout_lookup_collect_glyphs (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @coords: The variation coordinates to query - * @num_coords: The number of variation coorinates + * @num_coords: The number of variation coordinates * @variations_index: (out): The array of feature variations found for the query * * Fetches a list of feature variations in the specified face's GSUB table @@ -1310,7 +1310,7 @@ hb_ot_layout_feature_with_variations_get_lookups (hb_face_t *face, * * Tests whether the specified face includes any GSUB substitutions. * - * Return value: true if data found, false otherwise + * Return value: %true if data found, false otherwise * **/ hb_bool_t @@ -1331,7 +1331,7 @@ hb_ot_layout_has_substitution (hb_face_t *face) * Tests whether a specified lookup in the specified face would * trigger a substitution on the given glyph sequence. * - * Return value: true if a substitution would be triggered, false otherwise + * Return value: %true if a substitution would be triggered, false otherwise * * Since: 0.9.7 **/ @@ -1488,7 +1488,7 @@ hb_ot_layout_lookups_substitute_closure (hb_face_t *face, * hb_ot_layout_has_positioning: * @face: #hb_face_t to work upon * - * Return value: true if the face has GPOS data, false otherwise + * Return value: %true if the face has GPOS data, false otherwise * **/ hb_bool_t @@ -1561,7 +1561,7 @@ hb_ot_layout_position_finish_offsets (hb_font_t *font, hb_buffer_t *buffer) * For more information on this distinction, see the [`size` feature documentation]( * https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size). * - * Return value: true if data found, false otherwise + * Return value: %true if data found, false otherwise * * Since: 0.9.10 **/ @@ -1625,7 +1625,7 @@ hb_ot_layout_get_size_params (hb_face_t *face, * Fetches name indices from feature parameters for "Stylistic Set" ('ssXX') or * "Character Variant" ('cvXX') features. * - * Return value: true if data found, false otherwise + * Return value: %true if data found, false otherwise * * Since: 2.0.0 **/ From 726e320ece912a75918f4a3208dff973b18c4b45 Mon Sep 17 00:00:00 2001 From: n8willis Date: Sun, 26 Apr 2020 15:56:57 +0100 Subject: [PATCH 6/8] Update inline doc for hb_face_create: explain index --- src/hb-face.cc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/hb-face.cc b/src/hb-face.cc index bf11df203..89859ba17 100644 --- a/src/hb-face.cc +++ b/src/hb-face.cc @@ -193,7 +193,9 @@ _hb_face_for_data_reference_table (hb_face_t *face HB_UNUSED, hb_tag_t tag, void * @index: The index of the face within @blob * * Constructs a new face object from the specified blob and - * a face index into that blob. + * a face index into that blob. This is used for blobs of + * file formats such as Dfont and TTC that can contain more + * than one face. * * Return value: (transfer full): The new face object * From 41b46a3cb2d18417d642c3101aacc38fc6a56dc9 Mon Sep 17 00:00:00 2001 From: n8willis Date: Sun, 26 Apr 2020 16:01:31 +0100 Subject: [PATCH 7/8] Update hb-face.cc --- src/hb-face.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/hb-face.cc b/src/hb-face.cc index 89859ba17..54abac007 100644 --- a/src/hb-face.cc +++ b/src/hb-face.cc @@ -109,7 +109,7 @@ DEFINE_NULL_INSTANCE (hb_face_t) = * Creates a new face object from the specified @user_data and @reference_table_func, * with the @destroy callback. * - * Return value: (transfer full) + * Return value: (transfer full): The new face object * * Since: 0.9.2 **/ From cc7b3a1abd24aebabd812a151e0c206bf6f09635 Mon Sep 17 00:00:00 2001 From: Khaled Hosny Date: Sat, 26 Sep 2020 10:22:39 +0200 Subject: [PATCH 8/8] [Docs] Address review comments --- src/hb-face.cc | 11 ++++++----- src/hb-face.h | 2 -- src/hb-unicode.cc | 5 +++++ 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/src/hb-face.cc b/src/hb-face.cc index 54abac007..848c4ff9c 100644 --- a/src/hb-face.cc +++ b/src/hb-face.cc @@ -102,9 +102,10 @@ DEFINE_NULL_INSTANCE (hb_face_t) = * @user_data: A pointer to the user data * @destroy: (optional): A callback to call when @data is not needed anymore * - * Variant of hb_face_create(), built for those cases where - * client programs are primarily concerned with querying the - * font tables, rather than with full shaping. + * Variant of hb_face_create(), built for those cases where it is more + * convenient to provide data for individual tables instead of the whole font + * data. With the caveat that hb_face_get_table_tags() does not currently work + * with faces created this way. * * Creates a new face object from the specified @user_data and @reference_table_func, * with the @destroy callback. @@ -397,8 +398,8 @@ hb_face_reference_table (const hb_face_t *face, * @face: A face object * * Fetches a pointer to the binary blob that contains the - * specified face. Can only be used on faces created with - * hb_face_builder_create(). + * specified face. Returns an empty blob if referencing face data is not + * possible. * * Return value: (transfer full): A pointer to the blob for @face * diff --git a/src/hb-face.h b/src/hb-face.h index d88285a50..3b18f7eef 100644 --- a/src/hb-face.h +++ b/src/hb-face.h @@ -48,8 +48,6 @@ hb_face_count (hb_blob_t *blob); /** * hb_face_t: - * @blob: A pointer to the #hb_blob_t that contains the binary blob of a font file - * @index: The index (zero-based) into the font file that points to the face * * Data type for holding font faces. * diff --git a/src/hb-unicode.cc b/src/hb-unicode.cc index 9621a2256..71de71549 100644 --- a/src/hb-unicode.cc +++ b/src/hb-unicode.cc @@ -139,9 +139,14 @@ hb_unicode_decompose_compatibility_nil (hb_unicode_funcs_t *ufuncs HB_UNUSED #endif /** + * hb_unicode_funcs_get_default: * + * Fetches a pointer to the default Unicode-functions structure that is used + * when no functions are explicitly set on #hb_buffer_t. * + * Return value: (transfer none): a pointer to the #hb_unicode_funcs_t Unicode-functions structure * + * Since: 0.9.2 **/ hb_unicode_funcs_t * hb_unicode_funcs_get_default ()