From 8ab797c5b86c33eab6ee024471fd3c147325d26a Mon Sep 17 00:00:00 2001 From: Khaled Hosny Date: Tue, 29 Dec 2015 17:42:16 +0400 Subject: [PATCH] [docs] A bit more buffers documentation --- docs/harfbuzz-sections.txt | 60 ++++++++++++------------ src/hb-buffer.cc | 93 ++++++++++++++++++++++++++------------ src/hb-buffer.h | 7 ++- src/hb-common.cc | 43 +++++++++++------- src/hb-common.h | 15 +++--- 5 files changed, 135 insertions(+), 83 deletions(-) diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt index 0cb25682..3e7efed6 100644 --- a/docs/harfbuzz-sections.txt +++ b/docs/harfbuzz-sections.txt @@ -39,26 +39,26 @@ hb_buffer_add_utf32 hb_buffer_add_utf16 hb_buffer_add_utf8 hb_buffer_set_content_type +hb_buffer_get_content_type hb_buffer_set_direction -hb_buffer_set_flags +hb_buffer_get_direction +hb_buffer_set_script +hb_buffer_get_script hb_buffer_set_language +hb_buffer_get_language +hb_buffer_set_flags +hb_buffer_get_flags hb_buffer_set_length -hb_buffer_set_script +hb_buffer_get_length hb_buffer_set_segment_properties -hb_buffer_set_unicode_funcs -hb_buffer_set_user_data hb_buffer_guess_segment_properties -hb_buffer_get_content_type -hb_buffer_get_direction -hb_buffer_get_flags -hb_buffer_get_glyph_infos -hb_buffer_get_glyph_positions -hb_buffer_get_language -hb_buffer_get_length -hb_buffer_get_script hb_buffer_get_segment_properties +hb_buffer_set_unicode_funcs hb_buffer_get_unicode_funcs +hb_buffer_set_user_data hb_buffer_get_user_data +hb_buffer_get_glyph_infos +hb_buffer_get_glyph_positions hb_buffer_normalize_glyphs hb_buffer_reverse hb_buffer_reverse_clusters @@ -81,39 +81,39 @@ hb_buffer_serialize_format_t
hb-common -HB_DIRECTION_REVERSE -HB_LANGUAGE_INVALID -HB_TAG -HB_TAG_NONE -HB_TAG_MAX -HB_UNTAG -hb_bool_t -hb_codepoint_t -hb_destroy_func_t +hb_tag_from_string +hb_tag_to_string hb_direction_from_string -hb_direction_t hb_direction_to_string +hb_script_from_iso15924_tag +hb_script_from_string +hb_script_to_iso15924_tag +hb_script_get_horizontal_direction hb_language_from_string +hb_language_to_string hb_language_get_default +hb_bool_t +hb_codepoint_t +hb_destroy_func_t +hb_direction_t hb_language_t -hb_language_to_string hb_mask_t hb_position_t -hb_script_from_iso15924_tag -hb_script_from_string -hb_script_get_horizontal_direction -hb_script_t -hb_script_to_iso15924_tag -hb_tag_from_string hb_tag_t -hb_tag_to_string +hb_script_t hb_user_data_key_t hb_var_int_t +HB_TAG +HB_TAG_NONE +HB_TAG_MAX +HB_UNTAG +HB_DIRECTION_REVERSE HB_DIRECTION_IS_BACKWARD HB_DIRECTION_IS_FORWARD HB_DIRECTION_IS_HORIZONTAL HB_DIRECTION_IS_VALID HB_DIRECTION_IS_VERTICAL +HB_LANGUAGE_INVALID HB_BEGIN_DECLS HB_END_DECLS diff --git a/src/hb-buffer.cc b/src/hb-buffer.cc index ff3e655c..dc7124f9 100644 --- a/src/hb-buffer.cc +++ b/src/hb-buffer.cc @@ -787,7 +787,7 @@ hb_buffer_get_empty (void) * being destroyed until a matching call to hb_buffer_destroy() is made. * * Return value: (transfer full): - * the referenced #hb_buffer_t. + * The referenced #hb_buffer_t. * * Since: 0.9.2 **/ @@ -868,9 +868,10 @@ hb_buffer_get_user_data (hb_buffer_t *buffer, /** * hb_buffer_set_content_type: * @buffer: an #hb_buffer_t. - * @content_type: + * @content_type: the type of buffer contents to set * - * + * Sets the type of @buffer contents, buffers are either empty, contain + * characters (before shaping) or glyphs (the result of shaping). * * Since: 0.9.5 **/ @@ -885,9 +886,10 @@ hb_buffer_set_content_type (hb_buffer_t *buffer, * hb_buffer_get_content_type: * @buffer: an #hb_buffer_t. * - * + * see hb_buffer_set_content_type(). * - * Return value: + * Return value: + * The type of @buffer contents. * * Since: 0.9.5 **/ @@ -942,9 +944,15 @@ hb_buffer_get_unicode_funcs (hb_buffer_t *buffer) /** * hb_buffer_set_direction: * @buffer: an #hb_buffer_t. - * @direction: + * @direction: the #hb_direction_t of the @buffer * - * + * Set the text flow direction of the buffer. No shaping can happen without + * setting @buffer direction, and it controls the visual direction for the + * output glyphs; for RTL direction the glyphs will be reversed. Many layout + * features depend on the proper setting of the direction, for example, + * reversing RTL text before shaping, then shaping with LTR direction is not + * the same as keeping the text in logical order and shaping with RTL + * direction. * * Since: 0.9.2 **/ @@ -963,9 +971,10 @@ hb_buffer_set_direction (hb_buffer_t *buffer, * hb_buffer_get_direction: * @buffer: an #hb_buffer_t. * - * + * See hb_buffer_set_direction() * - * Return value: + * Return value: + * The direction of the @buffer. * * Since: 0.9.2 **/ @@ -978,9 +987,17 @@ hb_buffer_get_direction (hb_buffer_t *buffer) /** * hb_buffer_set_script: * @buffer: an #hb_buffer_t. - * @script: + * @script: an #hb_script_t to set. * - * + * Sets the script of @buffer to @script. + * + * Script is crucial for choosing the proper shaping behaviour for scripts that + * require it (e.g. Arabic) and the which OpenType features defined in the font + * to be applied. + * + * You can pass one of the predefined #hb_script_t values, or use + * hb_script_from_string() or hb_script_from_iso15924_tag() to get the + * corresponding script from an ISO 15924 script tag. * * Since: 0.9.2 **/ @@ -998,9 +1015,10 @@ hb_buffer_set_script (hb_buffer_t *buffer, * hb_buffer_get_script: * @buffer: an #hb_buffer_t. * - * + * See hb_buffer_set_script(). * - * Return value: + * Return value: + * The #hb_script_t of the @buffer. * * Since: 0.9.2 **/ @@ -1013,9 +1031,17 @@ hb_buffer_get_script (hb_buffer_t *buffer) /** * hb_buffer_set_language: * @buffer: an #hb_buffer_t. - * @language: + * @language: an hb_language_t to set. * - * + * Sets the language of @buffer to @language. + * + * Languages are crucial for selecting which OpenType feature to apply to the + * buffer which can result in applying language-specific behaviour. Languages + * are orthogonal to the scripts, and though they are related, they are + * different concepts and should not be confused with each other. + * + * Use hb_language_from_string() to convert from ISO 639 language codes to + * #hb_language_t. * * Since: 0.9.2 **/ @@ -1033,9 +1059,10 @@ hb_buffer_set_language (hb_buffer_t *buffer, * hb_buffer_get_language: * @buffer: an #hb_buffer_t. * - * + * See hb_buffer_set_language(). * * Return value: (transfer none): + * The #hb_language_t of the buffer. Must not be freed by the caller. * * Since: 0.9.2 **/ @@ -1192,7 +1219,8 @@ hb_buffer_get_replacement_codepoint (hb_buffer_t *buffer) * hb_buffer_reset: * @buffer: an #hb_buffer_t. * - * + * Resets the buffer to its initial status, just like new buffers returned from + * hb_buffer_create(). * * Since: 0.9.2 **/ @@ -1206,7 +1234,7 @@ hb_buffer_reset (hb_buffer_t *buffer) * hb_buffer_clear_contents: * @buffer: an #hb_buffer_t. * - * + * Clears the contents of the buffer without resetting other properties. * * Since: 0.9.11 **/ @@ -1219,11 +1247,12 @@ hb_buffer_clear_contents (hb_buffer_t *buffer) /** * hb_buffer_pre_allocate: * @buffer: an #hb_buffer_t. - * @size: + * @size: number of items to pre allocate. * - * + * Pre allocates memory for @buffer to fit at least @size number of items. * - * Return value: + * Return value: + * %true if the memory pre allocation succeeded, %false otherwise. * * Since: 0.9.2 **/ @@ -1237,9 +1266,10 @@ hb_buffer_pre_allocate (hb_buffer_t *buffer, unsigned int size) * hb_buffer_allocation_successful: * @buffer: an #hb_buffer_t. * - * + * Check if allocating memory for the buffer succeeded. * - * Return value: + * Return value: + * %true if memory allocation succeeded, %false otherwise. * * Since: 0.9.2 **/ @@ -1318,7 +1348,8 @@ hb_buffer_set_length (hb_buffer_t *buffer, * * Returns the number of items in the buffer. * - * Return value: buffer length. + * Return value: + * The @buffer length. * * Since: 0.9.2 **/ @@ -1333,10 +1364,11 @@ hb_buffer_get_length (hb_buffer_t *buffer) * @buffer: an #hb_buffer_t. * @length: (out): output array length. * - * Returns buffer glyph information array. Returned pointer - * is valid as long as buffer contents are not modified. + * Returns @buffer glyph information array. Returned pointer + * is valid as long as @buffer contents are not modified. * - * Return value: (transfer none) (array length=length): buffer glyph information array. + * Return value: (transfer none) (array length=length): + * The @buffer glyph information array. * * Since: 0.9.2 **/ @@ -1355,10 +1387,11 @@ hb_buffer_get_glyph_infos (hb_buffer_t *buffer, * @buffer: an #hb_buffer_t. * @length: (out): output length. * - * Returns buffer glyph position array. Returned pointer - * is valid as long as buffer contents are not modified. + * Returns @buffer glyph position array. Returned pointer + * is valid as long as @buffer contents are not modified. * - * Return value: (transfer none) (array length=length): buffer glyph position array. + * Return value: (transfer none) (array length=length): + * The @buffer glyph position array. * * Since: 0.9.2 **/ diff --git a/src/hb-buffer.h b/src/hb-buffer.h index a28d47fe..e24ffa44 100644 --- a/src/hb-buffer.h +++ b/src/hb-buffer.h @@ -115,7 +115,12 @@ HB_EXTERN void * hb_buffer_get_user_data (hb_buffer_t *buffer, hb_user_data_key_t *key); - +/** + * hb_buffer_content_type_t: + * @HB_BUFFER_CONTENT_TYPE_INVALID: Initial value for new buffer. + * @HB_BUFFER_CONTENT_TYPE_UNICODE: The buffer contains input characters (before shaping). + * @HB_BUFFER_CONTENT_TYPE_GLYPHS: The buffer contains output glyphs (after shaping). + */ typedef enum { HB_BUFFER_CONTENT_TYPE_INVALID = 0, HB_BUFFER_CONTENT_TYPE_UNICODE, diff --git a/src/hb-common.cc b/src/hb-common.cc index 710b36e5..e0911900 100644 --- a/src/hb-common.cc +++ b/src/hb-common.cc @@ -281,12 +281,15 @@ retry: /** * hb_language_from_string: - * @str: (array length=len) (element-type uint8_t): - * @len: + * @str: (array length=len) (element-type uint8_t): a string representing + * ISO 639 language code + * @len: length of the @str, or -1 if it is %NULL-terminated. * - * + * Converts @str representing an ISO 639 language code to the corresponding + * #hb_language_t. * * Return value: (transfer none): + * The #hb_language_t corresponding to the ISO 639 language code. * * Since: 0.9.2 **/ @@ -314,11 +317,13 @@ hb_language_from_string (const char *str, int len) /** * hb_language_to_string: - * @language: + * @language: an #hb_language_t to convert. * - * + * See hb_language_from_string(). * - * Return value: (transfer none): + * Return value: (transfer none): + * A %NULL-terminated string representing the @language. Must not be freed by + * the caller. * * Since: 0.9.2 **/ @@ -357,11 +362,12 @@ hb_language_get_default (void) /** * hb_script_from_iso15924_tag: - * @tag: + * @tag: an #hb_tag_t representing an ISO 15924 tag. * - * + * Converts an ISO 15924 script tag to a corresponding #hb_script_t. * * Return value: + * An #hb_script_t corresponding to the ISO 15924 tag. * * Since: 0.9.2 **/ @@ -401,28 +407,33 @@ hb_script_from_iso15924_tag (hb_tag_t tag) /** * hb_script_from_string: - * @s: (array length=len) (element-type uint8_t): - * @len: + * @str: (array length=len) (element-type uint8_t): a string representing an + * ISO 15924 tag. + * @len: length of the @str, or -1 if it is %NULL-terminated. * - * + * Converts a string @str representing an ISO 15924 script tag to a + * corresponding #hb_script_t. Shorthand for hb_tag_from_string() then + * hb_script_from_iso15924_tag(). * * Return value: + * An #hb_script_t corresponding to the ISO 15924 tag. * * Since: 0.9.2 **/ hb_script_t -hb_script_from_string (const char *s, int len) +hb_script_from_string (const char *str, int len) { - return hb_script_from_iso15924_tag (hb_tag_from_string (s, len)); + return hb_script_from_iso15924_tag (hb_tag_from_string (str, len)); } /** * hb_script_to_iso15924_tag: - * @script: + * @script: an #hb_script_ to convert. * - * + * See hb_script_from_iso15924_tag(). * - * Return value: + * Return value: + * An #hb_tag_t representing an ISO 15924 script tag. * * Since: 0.9.2 **/ diff --git a/src/hb-common.h b/src/hb-common.h index af17d780..5b0a0b68 100644 --- a/src/hb-common.h +++ b/src/hb-common.h @@ -106,8 +106,14 @@ HB_EXTERN void hb_tag_to_string (hb_tag_t tag, char *buf); -/* hb_direction_t */ - +/** + * hb_direction_t: + * @HB_DIRECTION_INVALID: Initial, unset direction. + * @HB_DIRECTION_LTR: Text is set horizontally from left to right. + * @HB_DIRECTION_RTL: Text is set horizontally from right to left. + * @HB_DIRECTION_TTB: Text is set vertically from top to bottom. + * @HB_DIRECTION_BTT: Text is set vertically from bottom to top. + */ typedef enum { HB_DIRECTION_INVALID = 0, HB_DIRECTION_LTR = 4, @@ -136,7 +142,6 @@ hb_direction_to_string (hb_direction_t direction); typedef const struct hb_language_impl_t *hb_language_t; -/* len=-1 means str is NUL-terminated */ HB_EXTERN hb_language_t hb_language_from_string (const char *str, int len); @@ -327,10 +332,8 @@ typedef enum HB_EXTERN hb_script_t hb_script_from_iso15924_tag (hb_tag_t tag); -/* sugar for tag_from_string() then script_from_iso15924_tag */ -/* len=-1 means s is NUL-terminated */ HB_EXTERN hb_script_t -hb_script_from_string (const char *s, int len); +hb_script_from_string (const char *str, int len); HB_EXTERN hb_tag_t hb_script_to_iso15924_tag (hb_script_t script); -- GitLab