From 877d80944b00a15acfee965a55e92ee3a77a812e Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Mon, 18 Jun 2018 10:08:17 +0200 Subject: [PATCH] Introduce `@example:' subsections. --- include/freetype/freetype.h | 3 +- include/freetype/ftdriver.h | 178 +++++++++++++++++++----------------- include/freetype/ftmac.h | 4 +- include/freetype/ftoutln.h | 7 +- include/freetype/tttables.h | 3 +- 5 files changed, 104 insertions(+), 91 deletions(-) diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index 2daf52957..7564b3925 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -2391,6 +2391,7 @@ FT_BEGIN_HEADER * See the discussion of reference counters in the description of * @FT_Reference_Face. * + * @example: * To loop over all faces, use code similar to the following snippet * (omitting the error handling). * @@ -4008,7 +4009,7 @@ FT_BEGIN_HEADER * @return: * FreeType error code. 0~means success. * - * @note: + * @example: * Here an example that sets three properties. You must define * FT_CONFIG_OPTION_SUBPIXEL_RENDERING to make the LCD filter examples * work. diff --git a/include/freetype/ftdriver.h b/include/freetype/ftdriver.h index 510f0c03e..2384dc610 100644 --- a/include/freetype/ftdriver.h +++ b/include/freetype/ftdriver.h @@ -371,6 +371,13 @@ FT_BEGIN_HEADER * `freetype' if T1_CONFIG_OPTION_OLD_ENGINE is defined, and `adobe' * otherwise. * + * @note: + * This property can be used with @FT_Property_Get also. + * + * This property can be set via the `FREETYPE_PROPERTIES' environment + * variable (using values `adobe' or `freetype'). + * + * @example: * The following example code demonstrates how to select Adobe's hinting * engine for the `cff' module (omitting the error handling). * @@ -385,12 +392,6 @@ FT_BEGIN_HEADER * "hinting-engine", &hinting_engine ); * } * - * @note: - * This property can be used with @FT_Property_Get also. - * - * This property can be set via the `FREETYPE_PROPERTIES' environment - * variable (using values `adobe' or `freetype'). - * * @since: * 2.4.12 (for `cff' module) * @@ -442,6 +443,15 @@ FT_BEGIN_HEADER * Note that stem darkening is never applied if @FT_LOAD_NO_SCALE is * set. * + * @note: + * This property can be used with @FT_Property_Get also. + * + * This property can be set via the `FREETYPE_PROPERTIES' environment + * variable (using values 1 and 0 for `on' and `off', respectively). + * It can also be set per face using @FT_Face_Properties with + * @FT_PARAM_TAG_STEM_DARKENING. + * + * @example: * { * FT_Library library; * FT_Bool no_stem_darkening = TRUE; @@ -453,14 +463,6 @@ FT_BEGIN_HEADER * "no-stem-darkening", &no_stem_darkening ); * } * - * @note: - * This property can be used with @FT_Property_Get also. - * - * This property can be set via the `FREETYPE_PROPERTIES' environment - * variable (using values 1 and 0 for `on' and `off', respectively). - * It can also be set per face using @FT_Face_Properties with - * @FT_PARAM_TAG_STEM_DARKENING. - * * @since: * 2.4.12 (for `cff' module) * @@ -492,22 +494,8 @@ FT_BEGIN_HEADER * control points can be set with the macro * `CFF_CONFIG_OPTION_DARKENING_PARAMETERS'; the CFF, Type~1, and CID * drivers share these values. At runtime, the control points can be - * changed using the `darkening-parameters' property, as the following - * example demonstrates for the Type~1 driver. - * - * { - * FT_Library library; - * FT_Int darken_params[8] = { 500, 300, // x1, y1 - * 1000, 200, // x2, y2 - * 1500, 100, // x3, y3 - * 2000, 0 }; // x4, y4 - * - * - * FT_Init_FreeType( &library ); - * - * FT_Property_Set( library, "type1", - * "darkening-parameters", darken_params ); - * } + * changed using the `darkening-parameters' property (see the example + * below that demonstrates this for the Type~1 driver). * * The x~values give the stem width, and the y~values the darkening * amount. The unit is 1000th of pixels. All coordinate values must be @@ -531,6 +519,21 @@ FT_BEGIN_HEADER * type1:darkening-parameters=500,300,1000,200,1500,100,2000,0 * } * + * @example: + * { + * FT_Library library; + * FT_Int darken_params[8] = { 500, 300, // x1, y1 + * 1000, 200, // x2, y2 + * 1500, 100, // x3, y3 + * 2000, 0 }; // x4, y4 + * + * + * FT_Init_FreeType( &library ); + * + * FT_Property_Set( library, "type1", + * "darkening-parameters", darken_params ); + * } + * * @since: * 2.5.1 (for `cff' module) * @@ -594,6 +597,13 @@ FT_BEGIN_HEADER * * If `no-long-family-names' is set, this feature gets switched off. * + * @note: + * This property can be used with @FT_Property_Get also. + * + * This property can be set via the `FREETYPE_PROPERTIES' environment + * variable (using values 1 and 0 for `on' and `off', respectively). + * + * @example: * { * FT_Library library; * FT_Bool no_long_family_names = TRUE; @@ -606,12 +616,6 @@ FT_BEGIN_HEADER * &no_long_family_names ); * } * - * @note: - * This property can be used with @FT_Property_Get also. - * - * This property can be set via the `FREETYPE_PROPERTIES' environment - * variable (using values 1 and 0 for `on' and `off', respectively). - * * @since: * 2.8 */ @@ -778,6 +782,13 @@ FT_BEGIN_HEADER * chosen interpreter, it simply ignores instructions on vertical stems * to arrive at very similar results. * + * @note: + * This property can be used with @FT_Property_Get also. + * + * This property can be set via the `FREETYPE_PROPERTIES' environment + * variable (using values `35', `38', or `40'). + * + * @example: * The following example code demonstrates how to deactivate subpixel * hinting (omitting the error handling). * @@ -794,12 +805,6 @@ FT_BEGIN_HEADER * &interpreter_version ); * } * - * @note: - * This property can be used with @FT_Property_Get also. - * - * This property can be set via the `FREETYPE_PROPERTIES' environment - * variable (using values `35', `38', or `40'). - * * @since: * 2.5 */ @@ -834,6 +839,7 @@ FT_BEGIN_HEADER * the auto-hinter so that the global analysis of the font shapes * actually uses the modified mapping. * + * @example: * The following example code demonstrates how to access it (omitting * the error handling). * @@ -1026,17 +1032,6 @@ FT_BEGIN_HEADER * @FT_AUTOHINTER_SCRIPT_CJK. Using the `fallback-script' property, * this fallback value can be changed. * - * { - * FT_Library library; - * FT_UInt fallback_script = FT_AUTOHINTER_SCRIPT_NONE; - * - * - * FT_Init_FreeType( &library ); - * - * FT_Property_Set( library, "autofitter", - * "fallback-script", &fallback_script ); - * } - * * @note: * This property can be used with @FT_Property_Get also. * @@ -1048,6 +1043,18 @@ FT_BEGIN_HEADER * an @FT_Face structure but not loaded any glyph (using the * auto-hinter), a change of the fallback script will affect this face. * + * @example: + * { + * FT_Library library; + * FT_UInt fallback_script = FT_AUTOHINTER_SCRIPT_NONE; + * + * + * FT_Init_FreeType( &library ); + * + * FT_Property_Set( library, "autofitter", + * "fallback-script", &fallback_script ); + * } + * * @since: * 2.4.11 * @@ -1074,17 +1081,6 @@ FT_BEGIN_HEADER * By default, this is @FT_AUTOHINTER_SCRIPT_LATIN. Using the * `default-script' property, this default value can be changed. * - * { - * FT_Library library; - * FT_UInt default_script = FT_AUTOHINTER_SCRIPT_NONE; - * - * - * FT_Init_FreeType( &library ); - * - * FT_Property_Set( library, "autofitter", - * "default-script", &default_script ); - * } - * * @note: * This property can be used with @FT_Property_Get also. * @@ -1096,6 +1092,18 @@ FT_BEGIN_HEADER * an @FT_Face structure but not loaded any glyph (using the * auto-hinter), a change of the default script will affect this face. * + * @example: + * { + * FT_Library library; + * FT_UInt default_script = FT_AUTOHINTER_SCRIPT_NONE; + * + * + * FT_Init_FreeType( &library ); + * + * FT_Property_Set( library, "autofitter", + * "default-script", &default_script ); + * } + * * @since: * 2.5.3 * @@ -1114,6 +1122,13 @@ FT_BEGIN_HEADER * this property to improve the legibility of small font sizes if * necessary. * + * @note: + * This property can be used with @FT_Property_Get also. + * + * Set this value right after calling @FT_Set_Char_Size, but before + * loading any glyph (using the auto-hinter). + * + * @example: * { * FT_Library library; * FT_Face face; @@ -1131,12 +1146,6 @@ FT_BEGIN_HEADER * "increase-x-height", &prop ); * } * - * @note: - * This property can be used with @FT_Property_Get also. - * - * Set this value right after calling @FT_Set_Char_Size, but before - * loading any glyph (using the auto-hinter). - * * @since: * 2.4.11 * @@ -1179,20 +1188,7 @@ FT_BEGIN_HEADER * To find out a glyph's optimal scaling and shifting value, various * parameter combinations are tried and scored. * - * By default, warping is off. The example below shows how to switch on - * warping (omitting the error handling). - * - * { - * FT_Library library; - * FT_Bool warping = 1; - * - * - * FT_Init_FreeType( &library ); - * - * FT_Property_Set( library, "autofitter", - * "warping", &warping ); - * } - * + * By default, warping is off. * @note: * This property can be used with @FT_Property_Get also. * @@ -1207,6 +1203,20 @@ FT_BEGIN_HEADER * change its value before rendering any face. Otherwise, you should * reload all faces that get auto-hinted in `normal' hinting mode. * + * @example: + * This example shows how to switch on warping (omitting the error + * handling). + * + * { + * FT_Library library; + * FT_Bool warping = 1; + * + * + * FT_Init_FreeType( &library ); + * + * FT_Property_Set( library, "autofitter", "warping", &warping ); + * } + * * @since: * 2.6 * diff --git a/include/freetype/ftmac.h b/include/freetype/ftmac.h index 82a6aaeda..4249ff547 100644 --- a/include/freetype/ftmac.h +++ b/include/freetype/ftmac.h @@ -92,12 +92,12 @@ FT_BEGIN_HEADER * @return: * FreeType error code. 0~means success. * - * @note: + * @example: * This function can be used to create @FT_Face objects from fonts * that are installed in the system as follows. * * { - * fond = GetResource( 'FOND', fontName ); + * fond = GetResource( 'FOND', fontName ); * error = FT_New_Face_From_FOND( library, fond, 0, &face ); * } */ diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h index 99eebf09b..9dae104de 100644 --- a/include/freetype/ftoutln.h +++ b/include/freetype/ftoutln.h @@ -376,16 +376,17 @@ FT_BEGIN_HEADER * If you need `better' metrics values you should call * @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. * - * Example call: + * To get meaningful results, font scaling values must be set with + * functions like @FT_Set_Char_Size before calling FT_Render_Glyph. * + * @example: * { * FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); + * * if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE ) * FT_Outline_Embolden( &face->glyph->outline, strength ); * } * - * To get meaningful results, font scaling values must be set with - * functions like @FT_Set_Char_Size before calling FT_Render_Glyph. */ FT_EXPORT( FT_Error ) FT_Outline_Embolden( FT_Outline* outline, diff --git a/include/freetype/tttables.h b/include/freetype/tttables.h index 7ba576e6f..57bbc036d 100644 --- a/include/freetype/tttables.h +++ b/include/freetype/tttables.h @@ -719,7 +719,8 @@ FT_BEGIN_HEADER * by the sfnt, truetype, and opentype drivers. See @FT_Sfnt_Tag for * a list. * - * Here an example how to access the `vhea' table: + * @example: + * Here an example how to access the `vhea' table. * * { * TT_VertHeader* vert_header;