From 19be8620ec33cdf2c451139f024301f65b147899 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Wed, 29 Aug 2018 18:15:03 +0200 Subject: [PATCH] Doc fix. --- include/freetype/fterrors.h | 112 +++++++++++++++++++----------------- include/freetype/ftmoderr.h | 10 +++- 2 files changed, 67 insertions(+), 55 deletions(-) diff --git a/include/freetype/fterrors.h b/include/freetype/fterrors.h index 43585bc5c..f3198111c 100644 --- a/include/freetype/fterrors.h +++ b/include/freetype/fterrors.h @@ -19,82 +19,90 @@ /************************************************************************** * * @section: - * error_enumerations + * error_enumerations * * @title: - * Error Enumerations + * Error Enumerations * * @abstract: - * How to handle errors and error strings. + * How to handle errors and error strings. * * @description: - * The header file `fterrors.h` (which is automatically included by - * `freetype.h` defines the handling of FreeType's enumeration constants. - * It can also be used to generate error message strings with a small - * macro trick explained below. + * The header file `fterrors.h` (which is automatically included by + * `freetype.h` defines the handling of FreeType's enumeration + * constants. It can also be used to generate error message strings + * with a small macro trick explained below. * - * **Error Formats** + * **Error Formats** * - * The configuration macro FT_CONFIG_OPTION_USE_MODULE_ERRORS can be - * defined in `ftoption.h` in order to make the higher byte indicate the - * module where the error has happened (this is not compatible with - * standard builds of FreeType~2, however). See the file `ftmoderr.h` for - * more details. + * The configuration macro FT_CONFIG_OPTION_USE_MODULE_ERRORS can be + * defined in `ftoption.h` in order to make the higher byte indicate the + * module where the error has happened (this is not compatible with + * standard builds of FreeType~2, however). See the file `ftmoderr.h` + * for more details. * - * **Error Message Strings** + * **Error Message Strings** * - * Error definitions are set up with special macros that allow client - * applications to build a table of error message strings. The strings - * are not included in a normal build of FreeType~2 to save space (most - * client applications do not use them). + * Error definitions are set up with special macros that allow client + * applications to build a table of error message strings. The strings + * are not included in a normal build of FreeType~2 to save space (most + * client applications do not use them). * - * To do so, you have to define the following macros before including this - * file. + * To do so, you have to define the following macros before including + * this file. * - * ``` - * FT_ERROR_START_LIST - * ``` + * ``` + * FT_ERROR_START_LIST + * ``` * - * This macro is called before anything else to define the start of the - * error list. It is followed by several FT_ERROR_DEF calls. + * This macro is called before anything else to define the start of the + * error list. It is followed by several FT_ERROR_DEF calls. * - * ``` - * FT_ERROR_DEF( e, v, s ) - * ``` + * ``` + * FT_ERROR_DEF( e, v, s ) + * ``` * - * This macro is called to define one single error. 'e' is the error code - * identifier (e.g., `Invalid_Argument`), 'v' is the error's numerical - * value, and 's' is the corresponding error string. + * This macro is called to define one single error. 'e' is the error + * code identifier (e.g., `Invalid_Argument`), 'v' is the error's + * numerical value, and 's' is the corresponding error string. * - * ``` - * FT_ERROR_END_LIST - * ``` + * ``` + * FT_ERROR_END_LIST + * ``` * - * This macro ends the list. + * This macro ends the list. * - * Additionally, you have to undefine `FTERRORS_H_` before #including this - * file. + * Additionally, you have to undefine `FTERRORS_H_` before #including + * this file. * - * Here is a simple example. + * Here is a simple example. * - * ``` - * #undef FTERRORS_H_ - * #define FT_ERRORDEF( e, v, s ) { e, s }, - * #define FT_ERROR_START_LIST { - * #define FT_ERROR_END_LIST { 0, NULL } }; + * ``` + * #undef FTERRORS_H_ + * #define FT_ERRORDEF( e, v, s ) { e, s }, + * #define FT_ERROR_START_LIST { + * #define FT_ERROR_END_LIST { 0, NULL } }; * - * const struct - * { - * int err_code; - * const char* err_msg; - * } ft_errors[] = + * const struct + * { + * int err_code; + * const char* err_msg; + * } ft_errors[] = * - * #include FT_ERRORS_H - * ``` + * #include FT_ERRORS_H + * ``` * - * Note that `FT_Err_Ok` is _not_ defined with `FT_ERRORDEF`; it is - * always zero. + * An alternative to using an array is a switch statement. * + * ``` + * #undef FTERRORS_H_ + * #define FT_ERROR_START_LIST switch ( error_code ) { + * #define FT_ERRORDEF( e, v, s ) case v: return s; + * #define FT_ERROR_END_LIST } + * ``` + * + * If you use FT_CONFIG_OPTION_USE_MODULE_ERRORS, 'error_code' should be + * replaced with 'FT_ERROR_BASE(error_code)' in the last example. */ /* */ diff --git a/include/freetype/ftmoderr.h b/include/freetype/ftmoderr.h index af651c225..e72933ac8 100644 --- a/include/freetype/ftmoderr.h +++ b/include/freetype/ftmoderr.h @@ -37,6 +37,7 @@ * provides some macros in `fttypes.h`. * * FT_ERR( err ) + * * Add current error module prefix (as defined with the `FT_ERR_PREFIX` * macro) to 'err'. For example, in the BDF module the line * @@ -49,7 +50,9 @@ * For simplicity, you can always use `FT_Err_Ok` directly instead of * 'FT_ERR( Ok )'. * - * FT_ERR_EQ( errcode, err ) FT_ERR_NEQ( errcode, err ) + * FT_ERR_EQ( errcode, err ) + * FT_ERR_NEQ( errcode, err ) + * * Compare error code 'errcode' with the error 'err' for equality and * inequality, respectively. Example: * @@ -63,9 +66,10 @@ * if ( error == FT_Err_Invalid_Outline ) * ... * - * FT_ERROR_BASE( errcode ) FT_ERROR_MODULE( errcode ) - * Get base error and module error code, respectively. + * FT_ERROR_BASE( errcode ) + * FT_ERROR_MODULE( errcode ) * + * Get base error and module error code, respectively. * * It can also be used to create a module error message table easily with * something like