From cd9889cac3ac3b271f7335f3e94acc4667a59b40 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Sun, 14 Apr 2019 15:33:56 +0100 Subject: [PATCH] Docs: update and extended GTK-Doc comments for hb-ot-math. --- src/hb-ot-math.cc | 133 ++++++++++++++++++++++++++++++++---------------------- src/hb-ot-math.h | 21 +++++++++ 2 files changed, 99 insertions(+), 55 deletions(-) diff --git a/src/hb-ot-math.cc b/src/hb-ot-math.cc index bd31bf5..99ce744 100644 --- a/src/hb-ot-math.cc +++ b/src/hb-ot-math.cc @@ -37,6 +37,11 @@ * @include: hb-ot.h * * Functions for fetching mathematics layout data from OpenType fonts. + * + * HarfBuzz itself does not implement a math layout solution. The + * functions and types provided can be used by client programs to access + * the font data necessary for typesetting OpenType Math layout. + * **/ @@ -48,10 +53,9 @@ * hb_ot_math_has_data: * @face: #hb_face_t to test * - * This function allows to verify the presence of an OpenType MATH table on the - * face. + * Tests whether a face has a `MATH` table. * - * Return value: true if face has a MATH table, false otherwise + * Return value: true if the table is found, false otherwise * * Since: 1.3.3 **/ @@ -63,16 +67,18 @@ hb_ot_math_has_data (hb_face_t *face) /** * hb_ot_math_get_constant: - * @font: #hb_font_t from which to retrieve the value + * @font: #hb_font_t to work upon * @constant: #hb_ot_math_constant_t the constant to retrieve * - * This function returns the requested math constants as a #hb_position_t. - * If the request constant is HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN, - * HB_OT_MATH_CONSTANT_SCRIPT_SCRIPT_PERCENT_SCALE_DOWN or - * HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN then the return value is - * actually an integer between 0 and 100 representing that percentage. + * Fetches the specified math constant. For most constants, the value returned + * is an #hb_position_t. + * + * However, if the requested constant is #HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN, + * #HB_OT_MATH_CONSTANT_SCRIPT_SCRIPT_PERCENT_SCALE_DOWN or + * #HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN, then the return value is + * an integer between 0 and 100 representing that percentage. * - * Return value: the requested constant or 0 + * Return value: the requested constant or zero * * Since: 1.3.3 **/ @@ -85,8 +91,11 @@ hb_ot_math_get_constant (hb_font_t *font, /** * hb_ot_math_get_glyph_italics_correction: - * @font: #hb_font_t from which to retrieve the value - * @glyph: glyph index from which to retrieve the value + * @font: #hb_font_t to work upon + * @glyph: The glyph index from which to retrieve the value + * + * Fetches an italics-correction value (if one exists) for the specified + * glyph index. * * Return value: the italics correction of the glyph or 0 * @@ -101,8 +110,11 @@ hb_ot_math_get_glyph_italics_correction (hb_font_t *font, /** * hb_ot_math_get_glyph_top_accent_attachment: - * @font: #hb_font_t from which to retrieve the value - * @glyph: glyph index from which to retrieve the value + * @font: #hb_font_t to work upon + * @glyph: The glyph index from which to retrieve the value + * + * Fetches a top-accent-attachment value (if one exists) for the specified + * glyph index. * * Return value: the top accent attachment of the glyph or 0 * @@ -117,8 +129,10 @@ hb_ot_math_get_glyph_top_accent_attachment (hb_font_t *font, /** * hb_ot_math_is_glyph_extended_shape: - * @face: a #hb_face_t to test - * @glyph: a glyph index to test + * @face: #hb_face_t to work upon + * @glyph: The glyph index to test + * + * Tests whether the given glyph index is an extended shape in the face. * * Return value: true if the glyph is an extended shape, false otherwise * @@ -133,18 +147,20 @@ hb_ot_math_is_glyph_extended_shape (hb_face_t *face, /** * hb_ot_math_get_glyph_kerning: - * @font: #hb_font_t from which to retrieve the value - * @glyph: glyph index from which to retrieve the value - * @kern: the #hb_ot_math_kern_t from which to retrieve the value + * @font: #hb_font_t to work upon + * @glyph: The glyph index from which to retrieve the value + * @kern: The #hb_ot_math_kern_t from which to retrieve the value * @correction_height: the correction height to use to determine the kerning. * - * This function tries to retrieve the MathKern table for the specified font, - * glyph and #hb_ot_math_kern_t. Then it browses the list of heights from the - * MathKern table to find one value that is greater or equal to specified - * correction_height. If one is found the corresponding value from the list of - * kerns is returned and otherwise the last kern value is returned. + * Fetches the MathKern table for the specified font, glyph index, and + * @kern. * - * Return value: requested kerning or 0 + * If the MathKern table is found, the function examines it to find a height + * value that is greater or equal to @correction_height. If such a height + * value is found, corresponding kerning value from the table is returned. If + * no such height value is found, the last kerning value is returned. + * + * Return value: requested kerning value or zero * * Since: 1.3.3 **/ @@ -162,20 +178,22 @@ hb_ot_math_get_glyph_kerning (hb_font_t *font, /** * hb_ot_math_get_glyph_variants: - * @font: #hb_font_t from which to retrieve the values - * @glyph: index of the glyph to stretch - * @direction: direction of the stretching + * @font: #hb_font_t to work upon + * @glyph: The index of the glyph to stretch + * @direction: The direction of the stretching (H or V) * @start_offset: offset of the first variant to retrieve - * @variants_count: maximum number of variants to retrieve after start_offset - * (IN) and actual number of variants retrieved (OUT) - * @variants: array of size at least @variants_count to store the result + * @variants_count: (inout): Input = the maximum number of variants to return; + * Output = the actual number of variants returned + * @variants: (out) (array length=variants_count): array of variants returned + * + * Fetches the MathGlyphConstruction for the specified font, glyph index, and + * direction. The corresponding list of size variants is returned as a list of + * #hb_ot_math_glyph_variant_t structs. * - * This function tries to retrieve the MathGlyphConstruction for the specified - * font, glyph and direction. Note that only the value of - * #HB_DIRECTION_IS_HORIZONTAL is considered. It provides the corresponding list - * of size variants as an array of hb_ot_math_glyph_variant_t structs. + * Note that only the value of #HB_DIRECTION_IS_HORIZONTAL is considered + * from the @direction parameter. * - * Return value: the total number of size variants available or 0 + * Return value: the total number of size variants available or zero * * Since: 1.3.3 **/ @@ -195,15 +213,17 @@ hb_ot_math_get_glyph_variants (hb_font_t *font, /** * hb_ot_math_get_min_connector_overlap: - * @font: #hb_font_t from which to retrieve the value - * @direction: direction of the stretching + * @font: #hb_font_t to work upon + * @direction: direction of the stretching (H or V) + * + * Fetches the MathVariants table for the specified font and returns the + * minimum overlap of connecting glyphs that are required to draw a glyph + * assembly in the specified direction. * - * This function tries to retrieve the MathVariants table for the specified - * font and returns the minimum overlap of connecting glyphs to draw a glyph - * assembly in the specified direction. Note that only the value of - * #HB_DIRECTION_IS_HORIZONTAL is considered. + * Note that only the value of #HB_DIRECTION_IS_HORIZONTAL is considered + * from the @direction parameter. * - * Return value: requested min connector overlap or 0 + * Return value: requested minimum connector overlap or zero * * Since: 1.3.3 **/ @@ -216,19 +236,22 @@ hb_ot_math_get_min_connector_overlap (hb_font_t *font, /** * hb_ot_math_get_glyph_assembly: - * @font: #hb_font_t from which to retrieve the values - * @glyph: index of the glyph to stretch - * @direction: direction of the stretching + * @font: #hb_font_t to work upon + * @glyph: The index of the glyph to stretch + * @direction: direction of the stretching (H or V) * @start_offset: offset of the first glyph part to retrieve - * @parts_count: maximum number of glyph parts to retrieve after start_offset - * (IN) and actual number of parts retrieved (OUT) - * @parts: array of size at least @parts_count to store the result - * @italics_correction: italic correction of the glyph assembly - * - * This function tries to retrieve the GlyphAssembly for the specified font, - * glyph and direction. Note that only the value of #HB_DIRECTION_IS_HORIZONTAL - * is considered. It provides the information necessary to draw the glyph - * assembly as an array of #hb_ot_math_glyph_part_t. + * @parts_count: (inout): Input = maximum number of glyph parts to return; + * Output = actual number of parts returned + * @parts: (out) (array length=parts_count): the glyph parts returned + * @italics_correction: (out): italics correction of the glyph assembly + * + * Fetches the GlyphAssembly for the specified font, glyph index, and direction. + * Returned are a list of #hb_ot_math_glyph_part_t glyph parts that can be + * used to draw the glyph and an italics-correction value (if one is defined + * in the font). + * + * Note that only the value of #HB_DIRECTION_IS_HORIZONTAL is considered + * from the @direction parameter. * * Return value: the total number of parts in the glyph assembly * diff --git a/src/hb-ot-math.h b/src/hb-ot-math.h index 521a5ca..d88aef8 100644 --- a/src/hb-ot-math.h +++ b/src/hb-ot-math.h @@ -50,6 +50,9 @@ HB_BEGIN_DECLS /** * hb_ot_math_constant_t: * + * The 'MATH' table constants specified at + * https://docs.microsoft.com/en-us/typography/opentype/spec/math + * * Since: 1.3.3 */ typedef enum { @@ -114,6 +117,9 @@ typedef enum { /** * hb_ot_math_kern_t: * + * The math kerning-table types defined for the four corners + * of a glyph. + * * Since: 1.3.3 */ typedef enum { @@ -125,6 +131,10 @@ typedef enum { /** * hb_ot_math_glyph_variant_t: + * @glyph: The glyph index of the variant + * @advance: The advance width of the variant + * + * Data type to hold math-variant information for a glyph. * * Since: 1.3.3 */ @@ -136,6 +146,8 @@ typedef struct hb_ot_math_glyph_variant_t { /** * hb_ot_math_glyph_part_flags_t: * + * Flags for math glyph parts. + * * Since: 1.3.3 */ typedef enum { /*< flags >*/ @@ -144,6 +156,15 @@ typedef enum { /*< flags >*/ /** * hb_ot_math_glyph_part_t: + * @glyph: The glyph index of the variant part + * @start_connector_length: The length of the connector on the starting side of the variant part + * @end_connection_length: The length of the conector on the ending side of the variant part + * @full_advance: The total advance of the part + * @flags: #hb_ot_math_glyph_part_flags_t flags for the part + * + * Data type to hold information for a "part" component of a math-variant glyph. + * Large variants for stretchable math glyphs (such as parentheses) can be constructed + * on the fly from parts. * * Since: 1.3.3 */ -- 2.7.4