From d055e1fc781c123f38d321846937965ef794257e Mon Sep 17 00:00:00 2001 From: Khaled Hosny Date: Wed, 8 Jan 2014 02:28:55 +0200 Subject: [PATCH] Some attempt into initial hb-shape documentation Very anaemic, needs to descripe the format understood by hb_feature_from_string() etc., but it is just start. --- src/hb-shape.cc | 70 +++++++++++++++++++++++++++++++++---------------- src/hb-shape.h | 3 --- 2 files changed, 47 insertions(+), 26 deletions(-) diff --git a/src/hb-shape.cc b/src/hb-shape.cc index 4e22c6186..13ec92614 100644 --- a/src/hb-shape.cc +++ b/src/hb-shape.cc @@ -33,6 +33,17 @@ #include "hb-buffer-private.hh" #include "hb-font-private.hh" +/** + * SECTION:hb-shape + * @title: Shaping + * @short_description: Conversion of text strings into positioned glyphs + * @include: hb.h + * + * Shaping is the central operation of HarfBuzz. Shaping operates on buffers, + * which are sequences of Unicode characters that use the same font and have + * the same text direction, script and language. After shaping the buffer + * contains the output glyphs and their positions. + **/ static bool parse_space (const char **pp, const char *end) @@ -198,13 +209,14 @@ parse_one_feature (const char **pp, const char *end, hb_feature_t *feature) /** * hb_feature_from_string: - * @str: (array length=len) (element-type uint8_t): - * @len: - * @feature: (out) (optional): + * @str: (array length=len) (element-type uint8_t): a string to parse + * @len: length of @str, or -1 if string is nul-terminated + * @feature: (out): the #hb_feature_t to initialize with the parsed values * - * + * Parses a string into a #hb_feature_t. If @len is -1 then @str is + * %NULL-terminated. * - * Return value: + * Return value: %true if @str is successfully parsed, %false otherwise * * Since: 1.0 **/ @@ -231,11 +243,13 @@ hb_feature_from_string (const char *str, int len, /** * hb_feature_to_string: - * @feature: - * @buf: (array length=size): - * @size: + * @feature: an #hb_feature_t to convert + * @buf: (array length=size) (out): output string + * @size: the allocated size of @buf * - * + * Converts a #hb_feature_t into a %NULL-terminated string in the format + * understood by hb_feature_from_string(). The client in responsible for + * allocating big enough size for @buf, 128 bytes is more than enough. * * Since: 1.0 **/ @@ -290,9 +304,10 @@ void free_static_shaper_list (void) /** * hb_shape_list_shapers: * - * + * Retrieves the list of shapers supported by HarfBuzz. * - * Return value: (transfer none): + * Return value: (transfer none) (array zero-terminated=1): an array of + * constant strings * * Since: 1.0 **/ @@ -333,15 +348,19 @@ retry: /** * hb_shape_full: - * @font: a font. - * @buffer: a buffer. - * @features: (array length=num_features): - * @num_features: - * @shaper_list: (array zero-terminated=1): + * @font: an #hb_font_t to use for shaping + * @buffer: an #hb_buffer_t to shape + * @features: (array length=num_features) (allow-none): an array of user + * specified #hb_feature_t or %NULL + * @num_features: the length of @features array + * @shaper_list: (array zero-terminated=1) (allow-none): a %NULL-terminated + * array of shapers to use or %NULL * - * + * See hb_shape() for details. If @shaper_list is not %NULL, the specified + * shapers will be used in the given order, otherwise the default shapers list + * will be used. * - * Return value: + * Return value: %false if all shapers failed, %true otherwise * * Since: 1.0 **/ @@ -368,12 +387,17 @@ hb_shape_full (hb_font_t *font, /** * hb_shape: - * @font: a font. - * @buffer: a buffer. - * @features: (array length=num_features): - * @num_features: + * @font: an #hb_font_t to use for shaping + * @buffer: an #hb_buffer_t to shape + * @features: (array length=num_features) (allow-none): an array of user + * specified #hb_feature_t or %NULL + * @num_features: the length of @features array * - * + * Shapes @buffer using @font turning its Unicode characters content to + * positioned glyphs. If @features is not %NULL, it will be used to control the + * features applied during shaping. + * + * Return value: %false if all shapers failed, %true otherwise * * Since: 1.0 **/ diff --git a/src/hb-shape.h b/src/hb-shape.h index 10a35cb51..b665509a0 100644 --- a/src/hb-shape.h +++ b/src/hb-shape.h @@ -47,13 +47,10 @@ typedef struct hb_feature_t { unsigned int end; } hb_feature_t; -/* len=-1 means str is NUL-terminated */ hb_bool_t hb_feature_from_string (const char *str, int len, hb_feature_t *feature); -/* Something like 128 bytes is more than enough. - * nul-terminates. */ void hb_feature_to_string (hb_feature_t *feature, char *buf, unsigned int size);