* include/*.*: Convert comments to markdown.

This commit was created by applying scripts `markify.py' and
`markdown-format.bash' to all C header files, followed by minor
clean-up.

No change in functionality, of course.

Scripts used:
https://github.com/nikramakrishnan/freetype-docs.git: Commit dfce31e.

http://lists.nongnu.org/archive/html/freetype-devel/2018-08/msg00013.html:
With patches applied.

1 files changed, 156 insertions, 205 deletions

diff --git a/include/freetype/tttables.h b/include/freetype/tttables.h
index 8ecc8e274..cbb17def7 100644
--- a/include/freetype/tttables.h
+++ b/include/freetype/tttables.h
@@ -77,8 +77,8 @@ FT_BEGIN_HEADER
    *   TT_Header
    *
    * @description:
-   *   A structure to model a TrueType font header table.  All fields
-   *   follow the OpenType specification.
+   *   A structure to model a TrueType font header table.  All fields follow
+   *   the OpenType specification.
    */
   typedef struct  TT_Header_
   {
@@ -115,76 +115,61 @@ FT_BEGIN_HEADER
    *   TT_HoriHeader
    *
    * @description:
-   *   A structure to model a TrueType horizontal header, the `hhea'
-   *   table, as well as the corresponding horizontal metrics table,
-   *   `hmtx'.
+   *   A structure to model a TrueType horizontal header, the 'hhea' table,
+   *   as well as the corresponding horizontal metrics table, 'hmtx'.
    *
    * @fields:
    *   Version ::
    *     The table version.
    *
    *   Ascender ::
-   *     The font's ascender, i.e., the distance
-   *     from the baseline to the top-most of all
-   *     glyph points found in the font.
+   *     The font's ascender, i.e., the distance from the baseline to the
+   *     top-most of all glyph points found in the font.
    *
-   *     This value is invalid in many fonts, as
-   *     it is usually set by the font designer,
-   *     and often reflects only a portion of the
-   *     glyphs found in the font (maybe ASCII).
+   *     This value is invalid in many fonts, as it is usually set by the
+   *     font designer, and often reflects only a portion of the glyphs found
+   *     in the font (maybe ASCII).
    *
-   *     You should use the `sTypoAscender' field
-   *     of the `OS/2' table instead if you want
-   *     the correct one.
+   *     You should use the `sTypoAscender` field of the 'OS/2' table instead
+   *     if you want the correct one.
    *
    *   Descender ::
-   *     The font's descender, i.e., the distance
-   *     from the baseline to the bottom-most of
-   *     all glyph points found in the font.  It
-   *     is negative.
+   *     The font's descender, i.e., the distance from the baseline to the
+   *     bottom-most of all glyph points found in the font.  It is negative.
    *
-   *     This value is invalid in many fonts, as
-   *     it is usually set by the font designer,
-   *     and often reflects only a portion of the
-   *     glyphs found in the font (maybe ASCII).
+   *     This value is invalid in many fonts, as it is usually set by the
+   *     font designer, and often reflects only a portion of the glyphs found
+   *     in the font (maybe ASCII).
    *
-   *     You should use the `sTypoDescender'
-   *     field of the `OS/2' table instead if you
-   *     want the correct one.
+   *     You should use the `sTypoDescender` field of the 'OS/2' table
+   *     instead if you want the correct one.
    *
    *   Line_Gap ::
-   *     The font's line gap, i.e., the distance
-   *     to add to the ascender and descender to
-   *     get the BTB, i.e., the
-   *     baseline-to-baseline distance for the
-   *     font.
+   *     The font's line gap, i.e., the distance to add to the ascender and
+   *     descender to get the BTB, i.e., the baseline-to-baseline distance
+   *     for the font.
    *
    *   advance_Width_Max ::
-   *     This field is the maximum of all advance
-   *     widths found in the font.  It can be
-   *     used to compute the maximum width of an
-   *     arbitrary string of text.
+   *     This field is the maximum of all advance widths found in the font.
+   *     It can be used to compute the maximum width of an arbitrary string
+   *     of text.
    *
    *   min_Left_Side_Bearing ::
-   *     The minimum left side bearing of all
-   *     glyphs within the font.
+   *     The minimum left side bearing of all glyphs within the font.
    *
    *   min_Right_Side_Bearing ::
-   *     The minimum right side bearing of all
-   *     glyphs within the font.
+   *     The minimum right side bearing of all glyphs within the font.
    *
    *   xMax_Extent ::
-   *     The maximum horizontal extent (i.e., the
-   *     `width' of a glyph's bounding box) for
-   *     all glyphs in the font.
+   *     The maximum horizontal extent (i.e., the 'width' of a glyph's
+   *     bounding box) for all glyphs in the font.
    *
    *   caret_Slope_Rise ::
-   *     The rise coefficient of the cursor's
-   *     slope of the cursor (slope=rise/run).
+   *     The rise coefficient of the cursor's slope of the cursor
+   *     (slope=rise/run).
    *
    *   caret_Slope_Run ::
-   *     The run coefficient of the cursor's
-   *     slope.
+   *     The run coefficient of the cursor's slope.
    *
    *   caret_Offset ::
    *     The cursor's offset for slanted fonts.
@@ -196,21 +181,20 @@ FT_BEGIN_HEADER
    *     Always~0.
    *
    *   number_Of_HMetrics ::
-   *     Number of HMetrics entries in the `hmtx'
-   *     table -- this value can be smaller than
-   *     the total number of glyphs in the font.
+   *     Number of HMetrics entries in the 'hmtx' table -- this value can be
+   *     smaller than the total number of glyphs in the font.
    *
    *   long_metrics ::
-   *     A pointer into the `hmtx' table.
+   *     A pointer into the 'hmtx' table.
    *
    *   short_metrics ::
-   *     A pointer into the `hmtx' table.
+   *     A pointer into the 'hmtx' table.
    *
    * @note:
-   *   For an OpenType variation font, the values of the following fields
-   *   can change after a call to @FT_Set_Var_Design_Coordinates (and
-   *   friends) if the font contains an `MVAR' table: `caret_Slope_Rise',
-   *   `caret_Slope_Run', and `caret_Offset'.
+   *   For an OpenType variation font, the values of the following fields can
+   *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
+   *   the font contains an 'MVAR' table: `caret_Slope_Rise`,
+   *   `caret_Slope_Run`, and `caret_Offset`.
    */
   typedef struct  TT_HoriHeader_
   {
@@ -249,78 +233,61 @@ FT_BEGIN_HEADER
    *   TT_VertHeader
    *
    * @description:
-   *   A structure used to model a TrueType vertical header, the `vhea'
-   *   table, as well as the corresponding vertical metrics table,
-   *   `vmtx'.
+   *   A structure used to model a TrueType vertical header, the 'vhea'
+   *   table, as well as the corresponding vertical metrics table, 'vmtx'.
    *
    * @fields:
    *   Version ::
    *     The table version.
    *
    *   Ascender ::
-   *     The font's ascender, i.e., the distance
-   *     from the baseline to the top-most of
-   *     all glyph points found in the font.
+   *     The font's ascender, i.e., the distance from the baseline to the
+   *     top-most of all glyph points found in the font.
    *
-   *     This value is invalid in many fonts, as
-   *     it is usually set by the font designer,
-   *     and often reflects only a portion of
-   *     the glyphs found in the font (maybe
-   *     ASCII).
+   *     This value is invalid in many fonts, as it is usually set by the
+   *     font designer, and often reflects only a portion of the glyphs found
+   *     in the font (maybe ASCII).
    *
-   *     You should use the `sTypoAscender'
-   *     field of the `OS/2' table instead if
-   *     you want the correct one.
+   *     You should use the `sTypoAscender` field of the 'OS/2' table instead
+   *     if you want the correct one.
    *
    *   Descender ::
-   *     The font's descender, i.e., the
-   *     distance from the baseline to the
-   *     bottom-most of all glyph points found
-   *     in the font.  It is negative.
+   *     The font's descender, i.e., the distance from the baseline to the
+   *     bottom-most of all glyph points found in the font.  It is negative.
    *
-   *     This value is invalid in many fonts, as
-   *     it is usually set by the font designer,
-   *     and often reflects only a portion of
-   *     the glyphs found in the font (maybe
-   *     ASCII).
+   *     This value is invalid in many fonts, as it is usually set by the
+   *     font designer, and often reflects only a portion of the glyphs found
+   *     in the font (maybe ASCII).
    *
-   *     You should use the `sTypoDescender'
-   *     field of the `OS/2' table instead if
-   *     you want the correct one.
+   *     You should use the `sTypoDescender` field of the 'OS/2' table
+   *     instead if you want the correct one.
    *
    *   Line_Gap ::
-   *     The font's line gap, i.e., the distance
-   *     to add to the ascender and descender to
-   *     get the BTB, i.e., the
-   *     baseline-to-baseline distance for the
-   *     font.
+   *     The font's line gap, i.e., the distance to add to the ascender and
+   *     descender to get the BTB, i.e., the baseline-to-baseline distance
+   *     for the font.
    *
    *   advance_Height_Max ::
-   *     This field is the maximum of all
-   *     advance heights found in the font.  It
-   *     can be used to compute the maximum
-   *     height of an arbitrary string of text.
+   *     This field is the maximum of all advance heights found in the font.
+   *     It can be used to compute the maximum height of an arbitrary string
+   *     of text.
    *
    *   min_Top_Side_Bearing ::
-   *     The minimum top side bearing of all
-   *     glyphs within the font.
+   *     The minimum top side bearing of all glyphs within the font.
    *
    *   min_Bottom_Side_Bearing ::
-   *     The minimum bottom side bearing of all
-   *     glyphs within the font.
+   *     The minimum bottom side bearing of all glyphs within the font.
    *
    *   yMax_Extent ::
-   *     The maximum vertical extent (i.e., the
-   *     `height' of a glyph's bounding box) for
-   *     all glyphs in the font.
+   *     The maximum vertical extent (i.e., the 'height' of a glyph's
+   *     bounding box) for all glyphs in the font.
    *
    *   caret_Slope_Rise ::
-   *     The rise coefficient of the cursor's
-   *     slope of the cursor (slope=rise/run).
+   *     The rise coefficient of the cursor's slope of the cursor
+   *     (slope=rise/run).
    *
    *   caret_Slope_Run ::
-   *     The run coefficient of the cursor's
-   *     slope.
+   *     The run coefficient of the cursor's slope.
    *
    *   caret_Offset ::
    *     The cursor's offset for slanted fonts.
@@ -332,23 +299,20 @@ FT_BEGIN_HEADER
    *     Always~0.
    *
    *   number_Of_VMetrics ::
-   *     Number of VMetrics entries in the
-   *     `vmtx' table -- this value can be
-   *     smaller than the total number of glyphs
-   *     in the font.
+   *     Number of VMetrics entries in the 'vmtx' table -- this value can be
+   *     smaller than the total number of glyphs in the font.
    *
    *   long_metrics ::
-   *     A pointer into the `vmtx' table.
+   *     A pointer into the 'vmtx' table.
    *
    *   short_metrics ::
-   *     A pointer into the `vmtx' table.
+   *     A pointer into the 'vmtx' table.
    *
    * @note:
-   *   For an OpenType variation font, the values of the following fields
-   *   can change after a call to @FT_Set_Var_Design_Coordinates (and
-   *   friends) if the font contains an `MVAR' table: `Ascender',
-   *   `Descender', `Line_Gap', `caret_Slope_Rise', `caret_Slope_Run',
-   *   and `caret_Offset'.
+   *   For an OpenType variation font, the values of the following fields can
+   *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
+   *   the font contains an 'MVAR' table: 'Ascender', 'Descender',
+   *   `Line_Gap`, `caret_Slope_Rise`, `caret_Slope_Run`, and `caret_Offset`.
    */
   typedef struct  TT_VertHeader_
   {
@@ -387,26 +351,24 @@ FT_BEGIN_HEADER
    *   TT_OS2
    *
    * @description:
-   *   A structure to model a TrueType `OS/2' table.  All fields comply
-   *   to the OpenType specification.
+   *   A structure to model a TrueType 'OS/2' table.  All fields comply to
+   *   the OpenType specification.
    *
-   *   Note that we now support old Mac fonts that do not include an
-   *   `OS/2' table.  In this case, the `version' field is always set to
-   *   0xFFFF.
+   *   Note that we now support old Mac fonts that do not include an 'OS/2'
+   *   table.  In this case, the 'version' field is always set to 0xFFFF.
    *
    * @note:
-   *   For an OpenType variation font, the values of the following fields
-   *   can change after a call to @FT_Set_Var_Design_Coordinates (and
-   *   friends) if the font contains an `MVAR' table: `sCapHeight',
-   *   `sTypoAscender', `sTypoDescender', `sTypoLineGap', `sxHeight',
-   *   `usWinAscent', `usWinDescent', `yStrikeoutPosition',
-   *   `yStrikeoutSize', `ySubscriptXOffset', `ySubScriptXSize',
-   *   `ySubscriptYOffset', `ySubscriptYSize', `ySuperscriptXOffset',
-   *   `ySuperscriptXSize', `ySuperscriptYOffset', and
-   *   `ySuperscriptYSize'.
-   *
-   *   Possible values for bits in the `ulUnicodeRangeX' fields are given
-   *   by the @TT_UCR_XXX macros.
+   *   For an OpenType variation font, the values of the following fields can
+   *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
+   *   the font contains an 'MVAR' table: `sCapHeight`, `sTypoAscender`,
+   *   `sTypoDescender`, `sTypoLineGap`, `sxHeight`, `usWinAscent`,
+   *   `usWinDescent`, `yStrikeoutPosition`, `yStrikeoutSize`,
+   *   `ySubscriptXOffset`, `ySubScriptXSize`, `ySubscriptYOffset`,
+   *   `ySubscriptYSize`, `ySuperscriptXOffset`, `ySuperscriptXSize`,
+   *   `ySuperscriptYOffset`, and `ySuperscriptYSize`.
+   *
+   *   Possible values for bits in the `ulUnicodeRangeX` fields are given by
+   *   the @TT_UCR_XXX macros.
    */
 
   typedef struct  TT_OS2_
@@ -473,16 +435,16 @@ FT_BEGIN_HEADER
    *   TT_Postscript
    *
    * @description:
-   *   A structure to model a TrueType `post' table.  All fields comply
-   *   to the OpenType specification.  This structure does not reference
-   *   a font's PostScript glyph names; use @FT_Get_Glyph_Name to
-   *   retrieve them.
+   *   A structure to model a TrueType 'post' table.  All fields comply to
+   *   the OpenType specification.  This structure does not reference a
+   *   font's PostScript glyph names; use @FT_Get_Glyph_Name to retrieve
+   *   them.
    *
    * @note:
-   *   For an OpenType variation font, the values of the following fields
-   *   can change after a call to @FT_Set_Var_Design_Coordinates (and
-   *   friends) if the font contains an `MVAR' table: `underlinePosition'
-   *   and `underlineThickness'.
+   *   For an OpenType variation font, the values of the following fields can
+   *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
+   *   the font contains an 'MVAR' table: `underlinePosition` and
+   *   `underlineThickness`.
    */
   typedef struct  TT_Postscript_
   {
@@ -508,8 +470,8 @@ FT_BEGIN_HEADER
    *   TT_PCLT
    *
    * @description:
-   *   A structure to model a TrueType `PCLT' table.  All fields comply
-   *   to the OpenType specification.
+   *   A structure to model a TrueType 'PCLT' table.  All fields comply to
+   *   the OpenType specification.
    */
   typedef struct  TT_PCLT_
   {
@@ -538,75 +500,65 @@ FT_BEGIN_HEADER
    *   TT_MaxProfile
    *
    * @description:
-   *   The maximum profile (`maxp') table contains many max values, which
-   *   can be used to pre-allocate arrays for speeding up glyph loading
-   *   and hinting.
+   *   The maximum profile ('maxp') table contains many max values, which can
+   *   be used to pre-allocate arrays for speeding up glyph loading and
+   *   hinting.
    *
    * @fields:
    *   version ::
    *     The version number.
    *
    *   numGlyphs ::
-   *     The number of glyphs in this TrueType
-   *     font.
+   *     The number of glyphs in this TrueType font.
    *
    *   maxPoints ::
-   *     The maximum number of points in a
-   *     non-composite TrueType glyph.  See also
-   *     `maxCompositePoints'.
+   *     The maximum number of points in a non-composite TrueType glyph.  See
+   *     also `maxCompositePoints`.
    *
    *   maxContours ::
-   *     The maximum number of contours in a
-   *     non-composite TrueType glyph.  See also
-   *     `maxCompositeContours'.
+   *     The maximum number of contours in a non-composite TrueType glyph.
+   *     See also `maxCompositeContours`.
    *
    *   maxCompositePoints ::
-   *     The maximum number of points in a
-   *     composite TrueType glyph.  See also
-   *     `maxPoints'.
+   *     The maximum number of points in a composite TrueType glyph.  See
+   *     also `maxPoints`.
    *
    *   maxCompositeContours ::
-   *     The maximum number of contours in a
-   *     composite TrueType glyph.  See also
-   *     `maxContours'.
+   *     The maximum number of contours in a composite TrueType glyph.  See
+   *     also `maxContours`.
    *
    *   maxZones ::
-   *     The maximum number of zones used for
-   *     glyph hinting.
+   *     The maximum number of zones used for glyph hinting.
    *
    *   maxTwilightPoints ::
-   *     The maximum number of points in the
-   *     twilight zone used for glyph hinting.
+   *     The maximum number of points in the twilight zone used for glyph
+   *     hinting.
    *
    *   maxStorage ::
-   *     The maximum number of elements in the
-   *     storage area used for glyph hinting.
+   *     The maximum number of elements in the storage area used for glyph
+   *     hinting.
    *
    *   maxFunctionDefs ::
-   *     The maximum number of function
-   *     definitions in the TrueType bytecode for
-   *     this font.
+   *     The maximum number of function definitions in the TrueType bytecode
+   *     for this font.
    *
    *   maxInstructionDefs ::
-   *     The maximum number of instruction
-   *     definitions in the TrueType bytecode for
-   *     this font.
+   *     The maximum number of instruction definitions in the TrueType
+   *     bytecode for this font.
    *
    *   maxStackElements ::
-   *     The maximum number of stack elements used
-   *     during bytecode interpretation.
+   *     The maximum number of stack elements used during bytecode
+   *     interpretation.
    *
    *   maxSizeOfInstructions ::
-   *     The maximum number of TrueType opcodes
-   *     used for glyph hinting.
+   *     The maximum number of TrueType opcodes used for glyph hinting.
    *
    *   maxComponentElements ::
-   *     The maximum number of simple (i.e.,
-   *     non-composite) glyphs in a composite glyph.
+   *     The maximum number of simple (i.e., non-composite) glyphs in a
+   *     composite glyph.
    *
    *   maxComponentDepth ::
-   *     The maximum nesting depth of composite
-   *     glyphs.
+   *     The maximum nesting depth of composite glyphs.
    *
    * @note:
    *   This structure is only used during font loading.
@@ -638,8 +590,8 @@ FT_BEGIN_HEADER
    *   FT_Sfnt_Tag
    *
    * @description:
-   *   An enumeration to specify indices of SFNT tables loaded and parsed
-   *   by FreeType during initialization of an SFNT font.  Used in the
+   *   An enumeration to specify indices of SFNT tables loaded and parsed by
+   *   FreeType during initialization of an SFNT font.  Used in the
    *   @FT_Get_Sfnt_Table API function.
    *
    * @values:
@@ -705,30 +657,29 @@ FT_BEGIN_HEADER
    *     The index of the SFNT table.
    *
    * @return:
-   *   A type-less pointer to the table.  This will be NULL in case of
-   *   error, or if the corresponding table was not found *OR* loaded
-   *   from the file.
+   *   A type-less pointer to the table.  This will be NULL in case of error,
+   *   or if the corresponding table was not found **OR** loaded from the
+   *   file.
    *
-   *   Use a typecast according to `tag' to access the structure
-   *   elements.
+   *   Use a typecast according to 'tag' to access the structure elements.
    *
    * @note:
    *   The table is owned by the face object and disappears with it.
    *
-   *   This function is only useful to access SFNT tables that are loaded
-   *   by the sfnt, truetype, and opentype drivers.  See @FT_Sfnt_Tag for
-   *   a list.
+   *   This function is only useful to access SFNT tables that are loaded by
+   *   the sfnt, truetype, and opentype drivers.  See @FT_Sfnt_Tag for a
+   *   list.
    *
    * @example:
-   *   Here an example how to access the `vhea' table.
+   *   Here an example how to access the 'vhea' table.
    *
-   *   {
+   *   ```
    *     TT_VertHeader*  vert_header;
    *
    *
    *     vert_header =
    *       (TT_VertHeader*)FT_Get_Sfnt_Table( face, FT_SFNT_VHEA );
-   *   }
+   *   ```
    */
   FT_EXPORT( void* )
   FT_Get_Sfnt_Table( FT_Face      face,
@@ -748,8 +699,8 @@ FT_BEGIN_HEADER
    *     A handle to the source face.
    *
    *   tag ::
-   *     The four-byte tag of the table to load.  Use value~0 if you want
-   *     to access the whole font file.  Otherwise, you can use one of the
+   *     The four-byte tag of the table to load.  Use value~0 if you want to
+   *     access the whole font file.  Otherwise, you can use one of the
    *     definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
    *     one with @FT_MAKE_TAG.
    *
@@ -763,10 +714,10 @@ FT_BEGIN_HEADER
    *
    * @inout:
    *   length ::
-   *     If the `length' parameter is NULL, try to load the whole table.
+   *     If the 'length' parameter is NULL, try to load the whole table.
    *     Return an error code if it fails.
    *
-   *     Else, if `*length' is~0, exit immediately while returning the
+   *     Else, if '*length' is~0, exit immediately while returning the
    *     table's (or file) full size in it.
    *
    *     Else the number of bytes to read from the table or file, from the
@@ -777,9 +728,9 @@ FT_BEGIN_HEADER
    *
    * @note:
    *   If you need to determine the table's length you should first call this
-   *   function with `*length' set to~0, as in the following example:
+   *   function with '*length' set to~0, as in the following example:
    *
-   *   {
+   *   ```
    *     FT_ULong  length = 0;
    *
    *
@@ -791,7 +742,7 @@ FT_BEGIN_HEADER
    *
    *     error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
    *     if ( error ) { ... could not load table ... }
-   *   }
+   *   ```
    *
    *   Note that structures like @TT_Header or @TT_OS2 can't be used with
    *   this function; they are limited to @FT_Get_Sfnt_Table.  Reason is that
@@ -825,14 +776,14 @@ FT_BEGIN_HEADER
    *
    * @inout:
    *   tag ::
-   *     The name tag of the SFNT table.  If the value is NULL, `table_index'
-   *     is ignored, and `length' returns the number of SFNT tables in the
+   *     The name tag of the SFNT table.  If the value is NULL, `table_index`
+   *     is ignored, and 'length' returns the number of SFNT tables in the
    *     font.
    *
    * @output:
    *   length ::
-   *     The length of the SFNT table (or the number of SFNT tables, depending
-   *     on `tag').
+   *     The length of the SFNT table (or the number of SFNT tables,
+   *     depending on 'tag').
    *
    * @return:
    *   FreeType error code.  0~means success.
@@ -863,8 +814,8 @@ FT_BEGIN_HEADER
    *     The target charmap.
    *
    * @return:
-   *   The language ID of `charmap'.  If `charmap' doesn't belong to an
-   *   SFNT face, just return~0 as the default value.
+   *   The language ID of 'charmap'.  If 'charmap' doesn't belong to an SFNT
+   *   face, just return~0 as the default value.
    *
    *   For a format~14 cmap (to access Unicode IVS), the return value is
    *   0xFFFFFFFF.
@@ -879,15 +830,15 @@ FT_BEGIN_HEADER
    *   FT_Get_CMap_Format
    *
    * @description:
-   *   Return the format of an SFNT `cmap' table.
+   *   Return the format of an SFNT 'cmap' table.
    *
    * @input:
    *   charmap ::
    *     The target charmap.
    *
    * @return:
-   *   The format of `charmap'.  If `charmap' doesn't belong to an SFNT
-   *   face, return -1.
+   *   The format of 'charmap'.  If 'charmap' doesn't belong to an SFNT face,
+   *   return -1.
    */
   FT_EXPORT( FT_Long )
   FT_Get_CMap_Format( FT_CharMap  charmap );