From fffc303a7f397d08eee719eca351bdb55b3a1e83 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Tue, 28 Jul 2020 18:28:10 +0200 Subject: Formatting, improving comments. --- include/freetype/config/public-macros.h | 136 +++++++++-------- include/freetype/internal/compiler-macros.h | 221 ++++++++++++++++------------ 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 - * , 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 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. */ -- cgit v1.2.1