ref: 19be8620ec33cdf2c451139f024301f65b147899
parent: 934a6159ba940fe15f02a84deeccdb789823242e
author: Werner Lemberg <[email protected]>
date: Wed Aug 29 14:15:03 EDT 2018
Doc fix.
--- 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.
*/
/* */
--- 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