ref: b3fce59d52fa65c1f2088942bb3009393cdd7285
parent: f9be567f5f6703e68980761f54ef3d896b63185b
author: Werner Lemberg <[email protected]>
date: Thu Jul 23 09:35:07 EDT 2015
Describe error values and strings in the documentation.
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -119,3 +119,17 @@
/* lcd_filtering */
/* */
/***************************************************************************/
+
+/***************************************************************************/
+/* */
+/* <Chapter> */
+/* error_codes */
+/* */
+/* <Title> */
+/* Error Codes */
+/* */
+/* <Sections> */
+/* error_enumerations */
+/* error_code_values */
+/* */
+/***************************************************************************/
--- a/include/freetype/fterrdef.h
+++ b/include/freetype/fterrdef.h
@@ -16,19 +16,44 @@
/***************************************************************************/
- /*******************************************************************/
- /*******************************************************************/
- /***** *****/
- /***** LIST OF ERROR CODES/MESSAGES *****/
- /***** *****/
- /*******************************************************************/
- /*******************************************************************/
+ /*************************************************************************/
+ /* */
+ /* <Section> */
+ /* error_code_values */
+ /* */
+ /* <Title> */
+ /* Error Code Values */
+ /* */
+ /* <Abstract> */
+ /* All possible error codes returned by FreeType functions. */
+ /* */
+ /* <Description> */
+ /* The list below is taken verbatim from the file `fterrdef.h' */
+ /* (loaded automatically by including `FT_FREETYPE_H'). The first */
+ /* argument of the `FT_ERROR_DEF_' macro is the error label; by */
+ /* default, the prefix `FT_Err_' gets added so that you get error */
+ /* names like `FT_Err_Cannot_Open_Resource'. The second argument is */
+ /* the error code, and the last argument an error string, which is not */
+ /* used by FreeType. */
+ /* */
+ /* Within your application you should *only* use error names and */
+ /* *never* its numeric values! The latter might (and actually do) */
+ /* change in forthcoming FreeType versions. */
+ /* */
+ /* Macro `FT_NOERRORDEF_' defines `FT_Err_Ok', which is always zero. */
+ /* See the `Error Enumerations' subsection how to automatically */
+ /* generate a list of error strings. */
+ /* */
+ /*************************************************************************/
- /* You need to define both FT_ERRORDEF_ and FT_NOERRORDEF_ before */
- /* including this file. */
+ /*************************************************************************/
+ /* */
+ /* <Enum> */
+ /* FT_Err_XXX */
+ /* */
+ /*************************************************************************/
-
/* generic errors */
FT_NOERRORDEF_( Ok, 0x00,
@@ -244,6 +269,8 @@
"Font header corrupted or missing fields" )
FT_ERRORDEF_( Corrupted_Font_Glyphs, 0xBA,
"Font glyphs corrupted or missing fields" )
+
+ /* */
/* END */
--- a/include/freetype/fterrors.h
+++ b/include/freetype/fterrors.h
@@ -18,68 +18,86 @@
/*************************************************************************/
/* */
- /* This special header file is used to define the handling of FT2 */
- /* enumeration constants. It can also be used to generate error message */
- /* strings with a small macro trick explained below. */
+ /* <Section> */
+ /* error_enumerations */
/* */
- /* I - Error Formats */
- /* ----------------- */
+ /* <Title> */
+ /* Error Enumerations */
/* */
+ /* <Abstract> */
+ /* 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. */
+ /* */
+ /* *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 */
+ /* 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). See the file `ftmoderr.h' for */
- /* more details. */
+ /* with standard builds of FreeType 2, however). See the file */
+ /* `ftmoderr.h' for more details. */
/* */
+ /* *Error* *Message* *Strings* */
/* */
- /* II - 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). */
/* */
- /* The error definitions below are made through special macros that */
- /* allow client applications to build a table of error message strings */
- /* if they need it. 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: */
+ /* this file. */
/* */
- /* 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 */
- /* (see below). */
+ /* { */+ /* FT_ERROR_START_LIST */
+ /* } */
/* */
- /* FT_ERROR_DEF( e, v, s ) :: */
- /* This macro is called to define one single error. */
- /* `e' is the error code identifier (e.g. FT_Err_Invalid_Argument). */
- /* `v' is the error numerical value. */
- /* `s' is the corresponding error string. */
+ /* 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_END_LIST :: */
- /* This macro ends the list. */
+ /* { */+ /* FT_ERROR_DEF( e, v, s ) */
+ /* } */
/* */
- /* Additionally, you have to undefine __FTERRORS_H__ before #including */
- /* this file. */
+ /* 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. */
/* */
- /* Here is a simple example: */
+ /* { */+ /* FT_ERROR_END_LIST */
+ /* } */
/* */
+ /* This macro ends the list. */
+ /* */
+ /* Additionally, you have to undefine `__FTERRORS_H__' before */
+ /* #including this file. */
+ /* */
+ /* 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 } }; */+ /* */
+ /* const struct */
/* { */- /* #undef __FTERRORS_H__ */
- /* #define FT_ERRORDEF( e, v, s ) { e, s }, */- /* #define FT_ERROR_START_LIST { */- /* #define FT_ERROR_END_LIST { 0, 0 } }; */+ /* 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' but with */
+ /* `FT_NOERRORDEF'; it is always zero. */
/* */
/*************************************************************************/
+ /* */
#ifndef __FTERRORS_H__
#define __FTERRORS_H__