Commit b3fce59d52fa65c1f2088942bb3009393cdd7285
2015-07-23T13:35:07
Describe error values and strings in the documentation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index d333761..ab43895 100644
--- 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 */
+/* */
+/***************************************************************************/
diff --git a/include/freetype/fterrdef.h b/include/freetype/fterrdef.h
index 1bf0751..d865da7 100644
--- a/include/freetype/fterrdef.h
+++ b/include/freetype/fterrdef.h
@@ -16,18 +16,43 @@
/***************************************************************************/
- /*******************************************************************/
- /*******************************************************************/
- /***** *****/
- /***** 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 */
@@ -245,5 +270,7 @@
FT_ERRORDEF_( Corrupted_Font_Glyphs, 0xBA,
"Font glyphs corrupted or missing fields" )
+ /* */
+
/* END */
diff --git a/include/freetype/fterrors.h b/include/freetype/fterrors.h
index 376bee6..0507b9a 100644
--- 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 */
- /* -------------------------- */
- /* */
- /* 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). */
+ /* 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: */
+ /* 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. */
+ /* */
+ /* { */
+ /* 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. */
/* */
- /* 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__