Doc fix.
This commit is contained in:
Werner Lemberg
parent
934a6159ba
commit
19be8620ec
@ -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.
|
||||
*/
|
||||
|
||||
/* */
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user