Formatting, improving comments.

2 files changed, 203 insertions, 154 deletions

diff --git a/include/freetype/config/public-macros.h b/include/freetype/config/public-macros.h
index 5cc3236ed..6aa673e80 100644
--- a/include/freetype/config/public-macros.h
+++ b/include/freetype/config/public-macros.h
@@ -15,81 +15,101 @@
  *
  */
 
-/* The definitions in this file are used by the public FreeType headers,
- * and thus should be considered part of the public API.
- *
- * Other compiler-specific macro definitions that are not exposed by the
- * FreeType API should go into include/freetype/internal/compiler-macros.h
- * instead.
- */
+  /*
+   * The definitions in this file are used by the public FreeType headers
+   * and thus should be considered part of the public API.
+   *
+   * Other compiler-specific macro definitions that are not exposed by the
+   * FreeType API should go into
+   * `include/freetype/internal/compiler-macros.h` instead.
+   */
 #ifndef FREETYPE_CONFIG_PUBLIC_MACROS_H_
 #define FREETYPE_CONFIG_PUBLIC_MACROS_H_
 
-/* FT_BEGIN_HEADER and FT_END_HEADER might have already been defined by
- * <freetype/config/ftheader.h>, but we don't want to include this header
- * here, so redefine the macros here only when needed. Their definition is
- * very stable, so keeping them in sync with the ones in the header should
- * not be a maintenance issue.
- */
+  /*
+   * `FT_BEGIN_HEADER` and `FT_END_HEADER` might have already been defined
+   * by `freetype/config/ftheader.h`, but we don't want to include this
+   * header here, so redefine the macros here only when needed.  Their
+   * definition is very stable, so keeping them in sync with the ones in the
+   * header should not be a maintenance issue.
+   */
 #ifndef FT_BEGIN_HEADER
-#  ifdef __cplusplus
-#    define FT_BEGIN_HEADER extern "C" {
-#  else
-#    define FT_BEGIN_HEADER  /* nothing */
-#  endif
-#endif  /* FT_END_HEADER */
+#ifdef __cplusplus
+#define FT_BEGIN_HEADER  extern "C" {
+#else
+#define FT_BEGIN_HEADER  /* empty */
+#endif
+#endif  /* FT_BEGIN_HEADER */
 
 #ifndef FT_END_HEADER
-#  ifdef __cplusplus
-#    define FT_END_HEADER  }
-#  else
-#    define FT_END_HEADER  /* nothing */
-#  endif
+#ifdef __cplusplus
+#define FT_END_HEADER  }
+#else
+#define FT_END_HEADER  /* empty */
+#endif
 #endif  /* FT_END_HEADER */
 
+
 FT_BEGIN_HEADER
 
-/* Mark a function declaration as public. This ensures it will be properly
- * exported to client code. Place this before a function declaration.
- *
- * NOTE: This macro should be considered an internal implementation detail, and
- * not part of the FreeType API. It is only defined here because it is needed
- * by FT_EXPORT()
- */
-#if defined(_WIN32)
-#  if defined(FT2_BUILD_LIBRARY) && defined( DLL_EXPORT )
-#    define FT_PUBLIC_FUNCTION_ATTRIBUTE  __declspec( dllexport )
-#  elif defined( DLL_IMPORT )
-#    define FT_PUBLIC_FUNCTION_ATTRIBUTE  __declspec( dllimport )
-#  endif
-#elif (defined(__GNUC__) && __GNUC__ >= 4) || defined(__clang__)
-#  define FT_PUBLIC_FUNCTION_ATTRIBUTE  __attribute__((visibility("default")))
-#elif defined(__SUNPRO_C) && __SUNPRO_C >= 0x550
-#  define FT_PUBLIC_FUNCTION_ATTRIBUTE __global
+  /*
+   * Mark a function declaration as public.  This ensures it will be
+   * properly exported to client code.  Place this before a function
+   * declaration.
+   *
+   * NOTE: This macro should be considered an internal implementation
+   * detail, and not part of the FreeType API.  It is only defined here
+   * because it is needed by `FT_EXPORT`.
+   */
+
+  /* Visual C, mingw */
+#if defined( _WIN32 )
+
+#if defined( FT2_BUILD_LIBRARY ) && defined( DLL_EXPORT )
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE  __declspec( dllexport )
+#elif defined( DLL_IMPORT )
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE  __declspec( dllimport )
 #endif
 
+  /* gcc, clang */
+#elif ( defined( __GNUC__ ) && __GNUC__ >= 4 ) || defined( __clang__ )
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE \
+          __attribute__(( visibility( "default" ) ))
+
+  /* Sun */
+#elif defined( __SUNPRO_C ) && __SUNPRO_C >= 0x550
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE  __global
+#endif
+
+
 #ifndef FT_PUBLIC_FUNCTION_ATTRIBUTE
-#  define FT_PUBLIC_FUNCTION_ATTRIBUTE  /* nothing */
+#define FT_PUBLIC_FUNCTION_ATTRIBUTE  /* empty */
 #endif
 
-/* Define a public FreeType API function. This ensures it is properly exported
- * or imported at build time. The macro parameter is the function's return type
- * as in:
- *
- *     FT_EXPORT( FT_Bool )  FT_Object_Method( FT_Object obj, ... );
- *
- * NOTE: This requires that all FT_EXPORT() uses are inside FT_BEGIN_HEADER ..
- * FT_END_HEADER blocks. This guarantees that the functions are exported with
- * C linkage, even when the header is included by a C++ source file.
- */
+
+  /*
+   * Define a public FreeType API function.  This ensures it is properly
+   * exported or imported at build time.  The macro parameter is the
+   * function's return type as in:
+   *
+   *   FT_EXPORT( FT_Bool )
+   *   FT_Object_Method( FT_Object  obj,
+   *                     ... );
+   *
+   * NOTE: This requires that all `FT_EXPORT` uses are inside
+   * `FT_BEGIN_HEADER ... FT_END_HEADER` blocks.  This guarantees that the
+   * functions are exported with C linkage, even when the header is included
+   * by a C++ source file.
+   */
 #define FT_EXPORT( x )  FT_PUBLIC_FUNCTION_ATTRIBUTE extern x
 
-  /* `FT_UNUSED` indicates that a given parameter is not used --   */
-  /* this is only used to get rid of unpleasant compiler warnings. */
-  /*                                                               */
-  /* Technically, this was not meant to be part of the public API, */
-  /* but some third-party code depends on it.                      */
-  /*                                                               */
+  /*
+   * `FT_UNUSED` indicates that a given parameter is not used -- this is
+   * only used to get rid of unpleasant compiler warnings.
+   *
+   * Technically, this was not meant to be part of the public API, but some
+   * third-party code depends on it.
+   */
 #ifndef FT_UNUSED
 #define FT_UNUSED( arg )  ( (arg) = (arg) )
 #endif
diff --git a/include/freetype/internal/compiler-macros.h b/include/freetype/internal/compiler-macros.h
index b62c0777b..f86a84f52 100644
--- a/include/freetype/internal/compiler-macros.h
+++ b/include/freetype/internal/compiler-macros.h
@@ -36,50 +36,60 @@ FT_BEGIN_HEADER
 #  endif
 #endif
 
-/* When defining a macro that expands to a non-trivial C statement, use
- * FT_BEGIN_STMNT and FT_END_STMNT to enclose the macro's body. This ensures
- * there are no surprises when the macro is invoked in conditional branches.
- *
- * E.g.:
- *   #define  LOG(...) \
- *      FT_BEGIN_STMNT \
- *        if (logging_enabled) \
- *           log(__VA_ARGS__); \
- *      FT_END_STMNT
- */
+  /*
+   * When defining a macro that expands to a non-trivial C statement, use
+   * FT_BEGIN_STMNT and FT_END_STMNT to enclose the macro's body.  This
+   * ensures there are no surprises when the macro is invoked in conditional
+   * branches.
+   *
+   * Example:
+   *
+   *   #define  LOG( ... )        \
+   *     FT_BEGIN_STMNT           \
+   *       if ( logging_enabled ) \
+   *         log( __VA_ARGS__ );  \
+   *     FT_END_STMNT
+   */
 #define FT_BEGIN_STMNT  do {
 #define FT_END_STMNT    } while ( 0 )
 
-/* FT_DUMMY_STMNT expands to an empty C statement. Useful for conditionally
- * define statement macros, as in:
- *
- * #ifdef BUILD_CONFIG_LOGGING
- * #  define LOG(...) \
- *     FT_BEGIN_STMNT \
- *       if (logging_enabled) \
- *         log(__VA_ARGS__); \
- *     FT_END_STMNT
- * #else
- * #  define LOG(...)  FT_DUMMY_STMNT
- * #endif
- */
+  /*
+   * FT_DUMMY_STMNT expands to an empty C statement.  Useful for
+   * conditionally defined statement macros.
+   *
+   * Example:
+   *
+   *   #ifdef BUILD_CONFIG_LOGGING
+   *   #define  LOG( ... )         \
+   *      FT_BEGIN_STMNT           \
+   *        if ( logging_enabled ) \
+   *          log( __VA_ARGS__ );  \
+   *      FT_END_STMNT
+   *   #else
+   *   #  define LOG( ... )  FT_DUMMY_STMNT
+   *   #endif
+   */
 #define FT_DUMMY_STMNT  FT_BEGIN_STMNT FT_END_STMNT
 
 #ifdef _WIN64
- /* only 64bit Windows uses the LLP64 data model, i.e., */
- /* 32-bit integers, 64-bit pointers.                   */
-#define FT_UINT_TO_POINTER( x ) (void*)(unsigned __int64)(x)
+  /* only 64bit Windows uses the LLP64 data model, i.e., */
+  /* 32-bit integers, 64-bit pointers.                   */
+#define FT_UINT_TO_POINTER( x )  (void *)(unsigned __int64)(x)
 #else
-#define FT_UINT_TO_POINTER( x ) (void*)(unsigned long)(x)
+#define FT_UINT_TO_POINTER( x )  (void *)(unsigned long)(x)
 #endif
 
-/* Use FT_TYPEOF(type) to cast a value to |type|. This is useful to suppress
- * signedness compilation warnings in macros as in:
- *
- * #define PAD_(x, n)  ( (x) & ~FT_TYPEOF( x )( (n) - 1 ) )
- *
- * `typeof` condition taken from gnulib's `intprops.h` header file
- */
+  /*
+   * Use `FT_TYPEOF( type )` to cast a value to `type`.  This is useful to
+   * suppress signedness compilation warnings in macros.
+   *
+   * Example:
+   *
+   *   #define PAD_( x, n )  ( (x) & ~FT_TYPEOF( x )( (n) - 1 ) )
+   *
+   * (The `typeof` condition is taken from gnulib's `intprops.h` header
+   * file.)
+   */
 #if ( ( defined( __GNUC__ ) && __GNUC__ >= 2 )                       || \
       ( defined( __IBMC__ ) && __IBMC__ >= 1210 &&                      \
         defined( __IBM__TYPEOF__ ) )                                 || \
@@ -89,94 +99,113 @@ FT_BEGIN_HEADER
 #define FT_TYPEOF( type )  /* empty */
 #endif
 
-/* Mark a function declaration as internal to the library. This ensures that
- * it will not be exposed by default to client code, and helps generate smaller
- * and faster code on ELF-based platforms. Place this before a function
- * declaration.
- */
-#if (defined(__GNUC__) && __GNUC__ >= 4) || defined(__clang__)
-#define FT_INTERNAL_FUNCTION_ATTRIBUTE  __attribute__((visibility("hidden")))
+  /*
+   * Mark a function declaration as internal to the library.  This ensures
+   * that it will not be exposed by default to client code, and helps
+   * generate smaller and faster code on ELF-based platforms.  Place this
+   * before a function declaration.
+   */
+#if ( defined( __GNUC__ ) && __GNUC__ >= 4 ) || defined( __clang__ )
+#define FT_INTERNAL_FUNCTION_ATTRIBUTE  \
+          __attribute__(( visibility( "hidden" ) ))
 #else
-#define FT_INTERNAL_FUNCTION_ATTRIBUTE  /* nothing */
+#define FT_INTERNAL_FUNCTION_ATTRIBUTE  /* empty */
 #endif
 
-/* FreeType supports compiling its C sources to be compiled as C++ instead,
- * this introduces a number of subtle issues.
- *
- * The main one is that a C++ function declaration and its definition must have
- * the same 'linkage'. Because all FreeType headers declare their function with
- * C linkage (i.e. within an extern "C" { .. } block, due to the magic of
- * FT_BEGIN_HEADER and FT_END_HEADER), then their definition in FreeType
- * sources should also be prefixed with 'extern "C"' when compiled in C++ mode.
- *
- * The FT_FUNCTION_DECLARATION() and FT_FUNCTION_DEFINITION() macros are
- * provided to deal with this case, as well as FT_CALLBACK_DEF et al below.
- */
+  /*
+   * FreeType supports compilation of its C sources with a C++ compiler (in
+   * C++ mode); this introduces a number of subtle issues.
+   *
+   * The main one is that a C++ function declaration and its definition must
+   * have the same 'linkage'.  Because all FreeType headers declare their
+   * functions with C linkage (i.e., within an `extern "C" { ... }` block
+   * due to the magic of FT_BEGIN_HEADER and FT_END_HEADER), their
+   * definition in FreeType sources should also be prefixed with `extern
+   * "C"` when compiled in C++ mode.
+   *
+   * The `FT_FUNCTION_DECLARATION` and `FT_FUNCTION_DEFINITION` macros are
+   * provided to deal with this case, as well as `FT_CALLBACK_DEF` and its
+   * siblings below.
+   */
 
-/* FT_FUNCTION_DECLARATION(type) can be used to write a C function declaration,
- * and ensure it will have C linkage when the library is built with a C++
- * compiler. The parameter is the function's return type, so a declaration
- * would look like:
- *
- *    FT_FUNCTION_DECLARATION(int) foo(int x);
- *
- * NOTE: This requires that all uses are inside FT_BEGIN_HEADER..FT_END_HEADER
- * blocks. Which guarantees that the declarations have C linkage when the
- * headers are included by C++ sources.
- *
- * NOTE: Do not use directly, use FT_LOCAL()/FT_BASE()/FT_EXPORT() instead.
- */
+  /*
+   * `FT_FUNCTION_DECLARATION( type )` can be used to write a C function
+   * declaration to ensure it will have C linkage when the library is built
+   * with a C++ compiler.  The parameter is the function's return type, so a
+   * declaration would look like
+   *
+   *    FT_FUNCTION_DECLARATION( int )
+   *    foo( int x );
+   *
+   * NOTE: This requires that all uses are inside of `FT_BEGIN_HEADER ...
+   * FT_END_HEADER` blocks, which guarantees that the declarations have C
+   * linkage when the headers are included by C++ sources.
+   *
+   * NOTE: Do not use directly.  Use `FT_LOCAL`, `FT_BASE`, and `FT_EXPORT`
+   * instead.
+   */
 #define FT_FUNCTION_DECLARATION( x )  extern x
 
-/* Same as FT_FUNCTION_DECLARATION(), but for function definitions instead.
- * NOTE: Do not use directly, use FT_LOCAL_DEF()/FT_BASE_DEF()/FT_EXPORT_DEF()
- * instead.
- */
+  /*
+   * Same as `FT_FUNCTION_DECLARATION`, but for function definitions instead.
+   *
+   * NOTE: Do not use directly.  Use `FT_LOCAL_DEF`, `FT_BASE_DEF`, and
+   * `FT_EXPORT_DEF` instead.
+   */
 #ifdef __cplusplus
 #define FT_FUNCTION_DEFINITION( x )  extern "C" x
 #else
 #define FT_FUNCTION_DEFINITION( x )  x
 #endif
 
-/* Use FT_LOCAL()/FT_LOCAL_DEF() to declare and define an internal FreeType
- * function that is only used by the sources of a single src/module/ directory.
- * This ensures the functions are turned into static ones at build time,
- * resulting in smaller and faster code.
- */
+  /*
+   * Use `FT_LOCAL` and `FT_LOCAL_DEF` to declare and define, respectively,
+   * an internal FreeType function that is only used by the sources of a
+   * single `src/module/` directory.  This ensures that the functions are
+   * turned into static ones at build time, resulting in smaller and faster
+   * code.
+   */
 #ifdef FT_MAKE_OPTION_SINGLE_OBJECT
 
-#  define FT_LOCAL( x )  static x
-#  define FT_LOCAL_DEF( x )  static x
+#define FT_LOCAL( x )      static x
+#define FT_LOCAL_DEF( x )  static x
 
 #else
 
-#define FT_LOCAL( x )      FT_INTERNAL_FUNCTION_ATTRIBUTE FT_FUNCTION_DECLARATION( x )
+#define FT_LOCAL( x )      FT_INTERNAL_FUNCTION_ATTRIBUTE \
+                           FT_FUNCTION_DECLARATION( x )
 #define FT_LOCAL_DEF( x )  FT_FUNCTION_DEFINITION( x )
 
 #endif  /* FT_MAKE_OPTION_SINGLE_OBJECT */
 
-/* Use FT_LOCAL_ARRAY()/FT_LOCAL_ARRAY_DEF() to declare and define a constant
- * array that must be accessed from several sources in the same src/module/
- * sub-directory, but are otherwise internal to the library.
- */
-#define FT_LOCAL_ARRAY( x )      FT_INTERNAL_FUNCTION_ATTRIBUTE extern const x
+  /*
+   * Use `FT_LOCAL_ARRAY` and `FT_LOCAL_ARRAY_DEF` to declare and define,
+   * respectively, a constant array that must be accessed from several
+   * sources in the same `src/module/` sub-directory, and which are internal
+   * to the library.
+   */
+#define FT_LOCAL_ARRAY( x )      FT_INTERNAL_FUNCTION_ATTRIBUTE \
+                                 extern const x
 #define FT_LOCAL_ARRAY_DEF( x )  FT_FUNCTION_DEFINITION( const x )
 
-/* Use FT_BASE()/FT_BASE_DEF() to declare or define an internal library
- * function that are used by more than one single module.
- */
-#define FT_BASE( x )      FT_INTERNAL_FUNCTION_ATTRIBUTE FT_FUNCTION_DECLARATION( x )
+  /*
+   * `Use FT_BASE` and `FT_BASE_DEF` to declare and define, respectively, an
+   * internal library function that is used by more than a single module.
+   */
+#define FT_BASE( x )      FT_INTERNAL_FUNCTION_ATTRIBUTE \
+                          FT_FUNCTION_DECLARATION( x )
 #define FT_BASE_DEF( x )  FT_FUNCTION_DEFINITION( x )
 
 
-/* NOTE: Conditionally define FT_EXPORT_VAR() due to its definition in
- * src/smooth/ftgrays.h to make the header more portable.
- */
+  /*
+   * NOTE: Conditionally define `FT_EXPORT_VAR` due to its definition in
+   * `src/smooth/ftgrays.h` to make the header more portable.
+   */
 #ifndef FT_EXPORT_VAR
-#define FT_EXPORT_VAR( x )   FT_FUNCTION_DECLARATION( x )
+#define FT_EXPORT_VAR( x )  FT_FUNCTION_DECLARATION( x )
 #endif
 
-  /* When compiling FreeType as a DLL or DSO with hidden visibility    */
+  /* When compiling FreeType as a DLL or DSO with hidden visibility,   */
   /* some systems/compilers need a special attribute in front OR after */
   /* the return type of function declarations.                         */
   /*                                                                   */
@@ -211,8 +240,8 @@ FT_BEGIN_HEADER
   /* To export a variable, use `FT_EXPORT_VAR`.                        */
   /*                                                                   */
 
-/* See <freetype/config/compiler_macros.h> for the FT_EXPORT() definition */
-#define FT_EXPORT_DEF( x ) FT_FUNCTION_DEFINITION( x )
+  /* See `freetype/config/compiler_macros.h` for the `FT_EXPORT` definition */
+#define FT_EXPORT_DEF( x )  FT_FUNCTION_DEFINITION( x )
 
   /* The following macros are needed to compile the library with a   */
   /* C++ compiler and with 16bit compilers.                          */