diff --git a/.travis.yml b/.travis.yml index 89f401202..7c155a716 100644 --- a/.travis.yml +++ b/.travis.yml @@ -28,7 +28,7 @@ script: - ./configure $CONFIGURE_OPTS - make - make check - - if [ "$TRAVIS_OS_NAME" == "linux" -a "$CC" == "gcc" ]; then rm -f src/.libs/NONE.gcov; touch src/NONE; coveralls; fi + - if [ "$TRAVIS_OS_NAME" == "linux" -a "$CC" == "gcc" ]; then rm -f src/.libs/NONE.gcov; touch src/NONE; coveralls -e docs; fi after_success: - bash .ci/deploy-docs.sh notifications: diff --git a/docs/Makefile.am b/docs/Makefile.am index 5e6fd2b3c..f2048c5e3 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -28,7 +28,8 @@ SCANGOBJ_OPTIONS= # Extra options to supply to gtkdoc-scan. # e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" -SCAN_OPTIONS=--rebuild-types --deprecated-guards="HB_DISABLE_DEPRECATED" +SCAN_OPTIONS=--rebuild-types --deprecated-guards="HB_DISABLE_DEPRECATED" \ + --ignore-decorators="HB_EXTERN" # Header files or dirs to ignore when scanning. Use base file/dir names # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt index 3612dad61..3ad7be478 100644 --- a/docs/harfbuzz-sections.txt +++ b/docs/harfbuzz-sections.txt @@ -25,94 +25,97 @@ hb_memory_mode_t
hb-buffer HB_SEGMENT_PROPERTIES_DEFAULT -hb_buffer_add -hb_buffer_add_utf16 -hb_buffer_add_utf32 -hb_buffer_add_utf8 -hb_buffer_allocation_successful -hb_buffer_clear_contents -hb_buffer_content_type_t hb_buffer_create -hb_buffer_deserialize_glyphs -hb_buffer_destroy -hb_buffer_flags_t -hb_buffer_get_content_type -hb_buffer_get_direction +hb_buffer_reference hb_buffer_get_empty +hb_buffer_destroy +hb_buffer_reset +hb_buffer_clear_contents +hb_buffer_pre_allocate +hb_buffer_allocation_successful +hb_buffer_add +hb_buffer_add_codepoints +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_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_cluster_level +hb_buffer_get_cluster_level +hb_buffer_set_length +hb_buffer_get_length +hb_buffer_set_segment_properties +hb_buffer_guess_segment_properties +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_get_language -hb_buffer_get_length -hb_buffer_get_script -hb_buffer_get_segment_properties -hb_buffer_get_unicode_funcs -hb_buffer_get_user_data -hb_buffer_guess_segment_properties hb_buffer_normalize_glyphs -hb_buffer_pre_allocate -hb_buffer_reference -hb_buffer_reset hb_buffer_reverse hb_buffer_reverse_clusters -hb_buffer_serialize_flags_t -hb_buffer_serialize_format_from_string -hb_buffer_serialize_format_t -hb_buffer_serialize_format_to_string hb_buffer_serialize_glyphs +hb_buffer_deserialize_glyphs +hb_buffer_serialize_format_from_string +hb_buffer_serialize_format_to_string hb_buffer_serialize_list_formats -hb_buffer_set_content_type -hb_buffer_set_direction -hb_buffer_set_flags -hb_buffer_set_language -hb_buffer_set_length -hb_buffer_set_script -hb_buffer_set_segment_properties -hb_buffer_set_unicode_funcs -hb_buffer_set_user_data +hb_segment_properties_equal +hb_segment_properties_hash hb_buffer_t hb_glyph_info_t hb_glyph_position_t -hb_segment_properties_equal -hb_segment_properties_hash +hb_buffer_content_type_t +hb_buffer_flags_t +hb_buffer_serialize_flags_t hb_segment_properties_t +hb_buffer_serialize_format_t
hb-common -HB_DIRECTION_REVERSE -HB_LANGUAGE_INVALID +hb_tag_from_string +hb_tag_to_string +hb_direction_from_string +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_mask_t +hb_position_t +hb_tag_t +hb_script_t +hb_user_data_key_t +hb_var_int_t HB_TAG HB_TAG_NONE HB_TAG_MAX HB_UNTAG -hb_bool_t -hb_codepoint_t -hb_destroy_func_t -hb_direction_from_string -hb_direction_t -hb_direction_to_string -hb_language_from_string -hb_language_get_default -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_user_data_key_t -hb_var_int_t +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 764b8ed5a..5fd902c0a 100644 --- a/src/hb-buffer.cc +++ b/src/hb-buffer.cc @@ -35,6 +35,15 @@ #define HB_DEBUG_BUFFER (HB_DEBUG+0) #endif +/** + * SECTION: hb-buffer + * @title: Buffers + * @short_description: Input and output buffers + * @include: hb.h + * + * Buffers serve dual role in HarfBuzz; they hold the input characters that are + * passed hb_shape(), and after shaping they hold the output glyphs. + **/ /** * hb_segment_properties_equal: @@ -710,9 +719,14 @@ void hb_buffer_t::deallocate_var_all (void) /** * hb_buffer_create: (Xconstructor) * - * + * Creates a new #hb_buffer_t with all properties to defaults. * - * Return value: (transfer full) + * Return value: (transfer full): + * A newly allocated #hb_buffer_t with a reference count of 1. The initial + * reference count should be released with hb_buffe_destroy() when you are done + * using the #hb_buffer_t. This function never returns %NULL. If memory cannot + * be allocated, a special #hb_buffer_t object will be returned on which + * hb_buffer_allocation_successful() returns %false. * * Since: 0.9.2 **/ @@ -767,11 +781,13 @@ hb_buffer_get_empty (void) /** * hb_buffer_reference: (skip) - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * - * + * Increases the reference count on @buffer by one. This prevents @buffer from + * being destroyed until a matching call to hb_buffer_destroy() is made. * * Return value: (transfer full): + * The referenced #hb_buffer_t. * * Since: 0.9.2 **/ @@ -783,9 +799,11 @@ hb_buffer_reference (hb_buffer_t *buffer) /** * hb_buffer_destroy: (skip) - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * - * + * Deallocate the @buffer. + * Decreases the reference count on @buffer by one. If the result is zero, then + * @buffer and all associated resources are freed. See hb_buffer_reference(). * * Since: 0.9.2 **/ @@ -806,7 +824,7 @@ hb_buffer_destroy (hb_buffer_t *buffer) /** * hb_buffer_set_user_data: (skip) - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @key: * @data: * @destroy: @@ -830,7 +848,7 @@ hb_buffer_set_user_data (hb_buffer_t *buffer, /** * hb_buffer_get_user_data: (skip) - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @key: * * @@ -849,10 +867,11 @@ hb_buffer_get_user_data (hb_buffer_t *buffer, /** * hb_buffer_set_content_type: - * @buffer: a buffer. - * @content_type: + * @buffer: an #hb_buffer_t. + * @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 **/ @@ -865,11 +884,12 @@ hb_buffer_set_content_type (hb_buffer_t *buffer, /** * hb_buffer_get_content_type: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * - * + * see hb_buffer_set_content_type(). * - * Return value: + * Return value: + * The type of @buffer contents. * * Since: 0.9.5 **/ @@ -882,7 +902,7 @@ hb_buffer_get_content_type (hb_buffer_t *buffer) /** * hb_buffer_set_unicode_funcs: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @unicode_funcs: * * @@ -907,7 +927,7 @@ hb_buffer_set_unicode_funcs (hb_buffer_t *buffer, /** * hb_buffer_get_unicode_funcs: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * * * @@ -923,10 +943,16 @@ hb_buffer_get_unicode_funcs (hb_buffer_t *buffer) /** * hb_buffer_set_direction: - * @buffer: a buffer. - * @direction: + * @buffer: an #hb_buffer_t. + * @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 **/ @@ -943,11 +969,12 @@ hb_buffer_set_direction (hb_buffer_t *buffer, /** * hb_buffer_get_direction: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * - * + * See hb_buffer_set_direction() * - * Return value: + * Return value: + * The direction of the @buffer. * * Since: 0.9.2 **/ @@ -959,10 +986,18 @@ hb_buffer_get_direction (hb_buffer_t *buffer) /** * hb_buffer_set_script: - * @buffer: a buffer. - * @script: + * @buffer: an #hb_buffer_t. + * @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 **/ @@ -978,11 +1013,12 @@ hb_buffer_set_script (hb_buffer_t *buffer, /** * hb_buffer_get_script: - * @buffer: a buffer. + * @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 **/ @@ -994,10 +1030,18 @@ hb_buffer_get_script (hb_buffer_t *buffer) /** * hb_buffer_set_language: - * @buffer: a buffer. - * @language: + * @buffer: an #hb_buffer_t. + * @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 **/ @@ -1013,11 +1057,12 @@ hb_buffer_set_language (hb_buffer_t *buffer, /** * hb_buffer_get_language: - * @buffer: a buffer. + * @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 **/ @@ -1029,7 +1074,7 @@ hb_buffer_get_language (hb_buffer_t *buffer) /** * hb_buffer_set_segment_properties: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @props: * * @@ -1048,7 +1093,7 @@ hb_buffer_set_segment_properties (hb_buffer_t *buffer, /** * hb_buffer_get_segment_properties: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @props: (out): * * @@ -1065,10 +1110,10 @@ hb_buffer_get_segment_properties (hb_buffer_t *buffer, /** * hb_buffer_set_flags: - * @buffer: a buffer. - * @flags: + * @buffer: an #hb_buffer_t. + * @flags: the buffer flags to set. * - * + * Sets @buffer flags to @flags. See #hb_buffer_flags_t. * * Since: 0.9.7 **/ @@ -1084,11 +1129,12 @@ hb_buffer_set_flags (hb_buffer_t *buffer, /** * hb_buffer_get_flags: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * - * + * See hb_buffer_set_flags(). * * Return value: + * The @buffer flags. * * Since: 0.9.7 **/ @@ -1100,7 +1146,7 @@ hb_buffer_get_flags (hb_buffer_t *buffer) /** * hb_buffer_set_cluster_level: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @cluster_level: * * @@ -1119,7 +1165,7 @@ hb_buffer_set_cluster_level (hb_buffer_t *buffer, /** * hb_buffer_get_cluster_level: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * * * @@ -1136,7 +1182,7 @@ hb_buffer_get_cluster_level (hb_buffer_t *buffer) /** * hb_buffer_set_replacement_codepoint: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @replacement: * * @@ -1155,7 +1201,7 @@ hb_buffer_set_replacement_codepoint (hb_buffer_t *buffer, /** * hb_buffer_get_replacement_codepoint: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * * * @@ -1172,9 +1218,10 @@ hb_buffer_get_replacement_codepoint (hb_buffer_t *buffer) /** * hb_buffer_reset: - * @buffer: a buffer. + * @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 **/ @@ -1186,9 +1233,9 @@ hb_buffer_reset (hb_buffer_t *buffer) /** * hb_buffer_clear_contents: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * - * + * Clears the contents of the buffer without resetting other properties. * * Since: 0.9.11 **/ @@ -1200,12 +1247,13 @@ hb_buffer_clear_contents (hb_buffer_t *buffer) /** * hb_buffer_pre_allocate: - * @buffer: a buffer. - * @size: + * @buffer: an #hb_buffer_t. + * @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 **/ @@ -1217,11 +1265,12 @@ hb_buffer_pre_allocate (hb_buffer_t *buffer, unsigned int size) /** * hb_buffer_allocation_successful: - * @buffer: a buffer. + * @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 **/ @@ -1233,11 +1282,15 @@ hb_buffer_allocation_successful (hb_buffer_t *buffer) /** * hb_buffer_add: - * @buffer: a buffer. - * @codepoint: - * @cluster: + * @buffer: an #hb_buffer_t. + * @codepoint: a Unicode code point. + * @cluster: the cluster value of @codepoint. * - * + * Appends a character with the Unicode value of @codepoint to @buffer, and + * gives it the initial cluster value of @cluster. Clusters can be any thing + * the client wants, they are usually used to refer to the index of the + * character in the input text stream and are output in + * #hb_glyph_info_t.cluster field. * * Since: 0.9.7 **/ @@ -1252,7 +1305,7 @@ hb_buffer_add (hb_buffer_t *buffer, /** * hb_buffer_set_length: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @length: * * @@ -1292,11 +1345,12 @@ hb_buffer_set_length (hb_buffer_t *buffer, /** * hb_buffer_get_length: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * * Returns the number of items in the buffer. * - * Return value: buffer length. + * Return value: + * The @buffer length. * * Since: 0.9.2 **/ @@ -1308,13 +1362,14 @@ hb_buffer_get_length (hb_buffer_t *buffer) /** * hb_buffer_get_glyph_infos: - * @buffer: a 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 **/ @@ -1330,13 +1385,14 @@ hb_buffer_get_glyph_infos (hb_buffer_t *buffer, /** * hb_buffer_get_glyph_positions: - * @buffer: a 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 **/ @@ -1355,7 +1411,7 @@ hb_buffer_get_glyph_positions (hb_buffer_t *buffer, /** * hb_buffer_reverse: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * * Reverses buffer contents. * @@ -1369,7 +1425,7 @@ hb_buffer_reverse (hb_buffer_t *buffer) /** * hb_buffer_reverse_range: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @start: start index. * @end: end index. * @@ -1386,7 +1442,7 @@ hb_buffer_reverse_range (hb_buffer_t *buffer, /** * hb_buffer_reverse_clusters: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * * Reverses buffer clusters. That is, the buffer contents are * reversed, then each cluster (consecutive items having the @@ -1402,7 +1458,7 @@ hb_buffer_reverse_clusters (hb_buffer_t *buffer) /** * hb_buffer_guess_segment_properties: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * * Sets unset buffer segment properties based on buffer Unicode * contents. If buffer is not empty, it must have content type @@ -1501,13 +1557,14 @@ hb_buffer_add_utf (hb_buffer_t *buffer, /** * hb_buffer_add_utf8: - * @buffer: a buffer. - * @text: (array length=text_length) (element-type uint8_t): - * @text_length: - * @item_offset: - * @item_length: + * @buffer: an #hb_buffer_t. + * @text: (array length=text_length): an array of UTF-8 characters to append. + * @text_length: the length of the @text, or -1 if it is %NULL terminated. + * @item_offset: the offset of the first character to add to the @buffer. + * @item_length: the number of characters to add to the @buffer, or -1 for the + * end of @text (assuming it is %NULL terminated). * - * + * See hb_buffer_add_codepoints(). * * Since: 0.9.2 **/ @@ -1523,13 +1580,14 @@ hb_buffer_add_utf8 (hb_buffer_t *buffer, /** * hb_buffer_add_utf16: - * @buffer: a buffer. - * @text: (array length=text_length): - * @text_length: - * @item_offset: - * @item_length: + * @buffer: an #hb_buffer_t. + * @text: (array length=text_length): an array of UTF-16 characters to append. + * @text_length: the length of the @text, or -1 if it is %NULL terminated. + * @item_offset: the offset of the first character to add to the @buffer. + * @item_length: the number of characters to add to the @buffer, or -1 for the + * end of @text (assuming it is %NULL terminated). * - * + * See hb_buffer_add_codepoints(). * * Since: 0.9.2 **/ @@ -1545,13 +1603,14 @@ hb_buffer_add_utf16 (hb_buffer_t *buffer, /** * hb_buffer_add_utf32: - * @buffer: a buffer. - * @text: (array length=text_length): - * @text_length: - * @item_offset: - * @item_length: + * @buffer: an #hb_buffer_t. + * @text: (array length=text_length): an array of UTF-32 characters to append. + * @text_length: the length of the @text, or -1 if it is %NULL terminated. + * @item_offset: the offset of the first character to add to the @buffer. + * @item_length: the number of characters to add to the @buffer, or -1 for the + * end of @text (assuming it is %NULL terminated). * - * + * See hb_buffer_add_codepoints(). * * Since: 0.9.2 **/ @@ -1567,7 +1626,7 @@ hb_buffer_add_utf32 (hb_buffer_t *buffer, /** * hb_buffer_add_latin1: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @text: (array length=text_length) (element-type uint8_t): * @text_length: * @item_offset: @@ -1589,13 +1648,22 @@ hb_buffer_add_latin1 (hb_buffer_t *buffer, /** * hb_buffer_add_codepoints: - * @buffer: a buffer. - * @text: (array length=text_length): - * @text_length: - * @item_offset: - * @item_length: + * @buffer: a #hb_buffer_t to append characters to. + * @text: (array length=text_length): an array of Unicode code points to append. + * @text_length: the length of the @text, or -1 if it is %NULL terminated. + * @item_offset: the offset of the first code point to add to the @buffer. + * @item_length: the number of code points to add to the @buffer, or -1 for the + * end of @text (assuming it is %NULL terminated). * - * + * Appends characters from @text array to @buffer. The @item_offset is the + * position of the first character from @text that will be appended, and + * @item_length is the number of character. When shaping part of a larger text + * (e.g. a run of text from a paragraph), instead of passing just the substring + * corresponding to the run, it is preferable to pass the whole + * paragraph and specify the run start and length as @item_offset and + * @item_length, respectively, to give HarfBuzz the full context to be able, + * for example, to do cross-run Arabic shaping or properly handle combining + * marks at stat of run. * * Since: 0.9.31 **/ @@ -1667,7 +1735,7 @@ normalize_glyphs_cluster (hb_buffer_t *buffer, /** * hb_buffer_normalize_glyphs: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * * * @@ -1722,7 +1790,7 @@ hb_buffer_t::sort (unsigned int start, unsigned int end, int(*compar)(const hb_g /** * hb_buffer_set_message_func: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t. * @func: (closure user_data) (destroy destroy) (scope notified): * @user_data: * @destroy: diff --git a/src/hb-buffer.h b/src/hb-buffer.h index a28d47fe3..9b72383ba 100644 --- a/src/hb-buffer.h +++ b/src/hb-buffer.h @@ -40,7 +40,28 @@ HB_BEGIN_DECLS - +/** + * hb_glyph_info_t: + * @codepoint: either a Unicode code point (before shaping) or a glyph index + * (after shaping). + * @mask: + * @cluster: the index of the character in the original text that corresponds + * to this #hb_glyph_info_t, or whatever the client passes to + * hb_buffer_add(). More than one #hb_glyph_info_t can have the same + * @cluster value, if they resulted from the same character (e.g. one + * to many glyph substitution), and when more than one character gets + * merged in the same glyph (e.g. many to one glyph substitution) the + * #hb_glyph_info_t will have cluster value corresponding to the + * first of them. By default some characters are merged into the same + * cluster (e.g. combining marks have the same cluster as their + * bases) even if they are separate glyphs, + * hb_buffer_set_cluster_level() allow selecting more fine-grained + * cluster handling. + * + * The #hb_glyph_info_t is the structure that holds informations about the + * glyphs and their relation to input text. + * + */ typedef struct hb_glyph_info_t { hb_codepoint_t codepoint; hb_mask_t mask; @@ -51,6 +72,22 @@ typedef struct hb_glyph_info_t { hb_var_int_t var2; } hb_glyph_info_t; +/** + * hb_glyph_position_t: + * @x_advance: how much the line advances after drawing this glyph when setting + * text in horizontal direction. + * @y_advance: how much the line advances after drawing this glyph when setting + * text in vertical direction. + * @x_offset: how much the glyph moves on the X-axis before drawing it, this + * should not affect how much the line advances. + * @y_offset: how much the glyph moves on the Y-axis before drawing it, this + * should not affect how much the line advances. + * + * The #hb_glyph_position_t is the structure that holds the positions of the + * glyph in both horizontal and vertical directions. All positions in + * #hb_glyph_position_t are relative to the current point. + * + */ typedef struct hb_glyph_position_t { hb_position_t x_advance; hb_position_t y_advance; @@ -115,7 +152,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, @@ -171,7 +213,22 @@ HB_EXTERN void hb_buffer_guess_segment_properties (hb_buffer_t *buffer); -/* +/** + * hb_buffer_flags_t: + * @HB_BUFFER_FLAG_DEFAULT: the default buffer flag. + * @HB_BUFFER_FLAG_BOT: flag indicating that special handling of the beginning + * of text can be applied to this buffer. Should usually + * be set unless you are passing to the buffer only part + * of the text without the full context. + * @HB_BUFFER_FLAG_EOT: flag indicating that special handling of the end of text + * can be applied to this buffer, similar to + * @HB_BUFFER_FLAG_EOT. + * @HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES: + * flag indication that character with Default Ignorable + * Unicode property should use the corresponding glyph + * from the font, instead of replacing them with the space + * glyph and zeroing the advance width. + * * Since: 0.9.20 */ typedef enum { /*< flags >*/ diff --git a/src/hb-common.cc b/src/hb-common.cc index 710b36e55..e09119009 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 af17d780c..5b0a0b68c 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); diff --git a/src/hb-directwrite.cc b/src/hb-directwrite.cc index 5df1b2af1..af0fd3da0 100644 --- a/src/hb-directwrite.cc +++ b/src/hb-directwrite.cc @@ -659,7 +659,7 @@ _hb_directwrite_shape(hb_shape_plan_t *shape_plan, DWRITE_READING_DIRECTION_RIGHT_TO_LEFT : DWRITE_READING_DIRECTION_LEFT_TO_RIGHT; - /** + /* * There's an internal 16-bit limit on some things inside the analyzer, * but we never attempt to shape a word longer than 64K characters * in a single gfxShapedWord, so we cannot exceed that limit. @@ -824,4 +824,4 @@ _hb_directwrite_shape(hb_shape_plan_t *shape_plan, /* Wow, done! */ return true; -} \ No newline at end of file +} diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index 3049fa1cc..9fc88f6c8 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -458,6 +458,8 @@ hb_ot_layout_language_find_feature (hb_face_t *face, } /** + * hb_ot_layout_feature_get_lookups: + * * Since: 0.9.7 **/ unsigned int @@ -475,6 +477,8 @@ hb_ot_layout_feature_get_lookups (hb_face_t *face, } /** + * hb_ot_layout_table_get_lookup_count: + * * Since: 0.9.22 **/ unsigned int @@ -635,6 +639,8 @@ _hb_ot_layout_collect_lookups_languages (hb_face_t *face, } /** + * hb_ot_layout_collect_lookups: + * * Since: 0.9.8 **/ void @@ -679,6 +685,8 @@ hb_ot_layout_collect_lookups (hb_face_t *face, } /** + * hb_ot_layout_lookup_collect_glyphs: + * * Since: 0.9.7 **/ void @@ -727,6 +735,8 @@ hb_ot_layout_has_substitution (hb_face_t *face) } /** + * hb_ot_layout_lookup_would_substitute: + * * Since: 0.9.7 **/ hb_bool_t @@ -768,6 +778,8 @@ hb_ot_layout_substitute_finish (hb_font_t *font, hb_buffer_t *buffer) } /** + * hb_ot_layout_lookup_substitute_closure: + * * Since: 0.9.7 **/ void @@ -805,6 +817,8 @@ hb_ot_layout_position_finish (hb_font_t *font, hb_buffer_t *buffer) } /** + * hb_ot_layout_get_size_params: + * * Since: 0.9.10 **/ hb_bool_t diff --git a/src/hb-unicode.h b/src/hb-unicode.h index 33b68aa0d..6a15cb00c 100644 --- a/src/hb-unicode.h +++ b/src/hb-unicode.h @@ -405,6 +405,8 @@ hb_unicode_funcs_set_decompose_compatibility_func (hb_unicode_funcs_t *ufuncs, /* accessors */ /** + * hb_unicode_combining_class: + * * Since: 0.9.2 **/ HB_EXTERN hb_unicode_combining_class_t @@ -412,6 +414,8 @@ hb_unicode_combining_class (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode); /** + * hb_unicode_eastasian_width: + * * Since: 0.9.2 **/ HB_EXTERN unsigned int @@ -419,6 +423,8 @@ hb_unicode_eastasian_width (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode); /** + * hb_unicode_general_category: + * * Since: 0.9.2 **/ HB_EXTERN hb_unicode_general_category_t @@ -426,6 +432,8 @@ hb_unicode_general_category (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode); /** + * hb_unicode_mirroring: + * * Since: 0.9.2 **/ HB_EXTERN hb_codepoint_t @@ -433,6 +441,8 @@ hb_unicode_mirroring (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode); /** + * hb_unicode_script: + * * Since: 0.9.2 **/ HB_EXTERN hb_script_t @@ -440,6 +450,8 @@ hb_unicode_script (hb_unicode_funcs_t *ufuncs, hb_codepoint_t unicode); /** + * hb_unicode_compose: + * * Since: 0.9.2 **/ HB_EXTERN hb_bool_t @@ -449,6 +461,8 @@ hb_unicode_compose (hb_unicode_funcs_t *ufuncs, hb_codepoint_t *ab); /** + * hb_unicode_decompose: + * * Since: 0.9.2 **/ HB_EXTERN hb_bool_t @@ -458,6 +472,8 @@ hb_unicode_decompose (hb_unicode_funcs_t *ufuncs, hb_codepoint_t *b); /** + * hb_unicode_decompose_compatibility: + * * Since: 0.9.2 **/ HB_EXTERN unsigned int