Introduce `@example:' subsections.

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;